Get Help

Invoke-CatProject

Opens a project, prints what it contains, runs its tests — all of them or a subset — prints the summary and writes the project's outputs. The one-liner for scripts and pipelines.

Synopsis 

Invoke-CatProject [[-Path] <string>] [[-LoggingLevel] <string>] [[-LoggingPath] <string>]
                  [-Filter <string>] [-TestID <guid[]>] [-IncludeTag <string[]>] [-ExcludeTag <string[]>]
                  [-SkipOutputs]

Parameters

Parameter Type Position Default Meaning
-Path string 0 current location A .cat.yaml file, or a directory with exactly one *.cat.yaml; relative to the current location. Empty or omitted: the current location.
-LoggingLevel string 1 Information None · Fatal · Error · Warning · Information · Debug · Verbose. Information prints one line per test as it finishes.
-LoggingPath string 2 <project folder>\Logs\cat-log.log Log file, when logging is on.
-Filter string named Run only tests whose full name contains the text. Substring match, not case-sensitive, no wildcards.
-TestID guid[] named Run only the tests with these IDs (TestDefinitionID from Get-CatTest — new on every open, so only useful inside one session).
-IncludeTag string[] named Run only tests that carry at least one of the tags. Not case-sensitive.
-ExcludeTag string[] named Run only tests that carry none of the tags.
-SkipOutputs switch named off Skip every output defined in the project (files, database tables, …).

What it does

Four steps in one: opens the project with a fresh session (signing in), prints the project summary Show-CatProject prints, runs the tests that pass the filters (-Filter, -TestID, -IncludeTag and -ExcludeTag combine — a test runs only if it satisfies all of them), writes the project’s outputs unless -SkipOutputs, and prints the result block Show-CatTestResultSummary prints. The project stays open afterwards, so Get-CatTestResultSummary, Get-CatTestResult and the other Get-Cat* cmdlets work on it.

Tests with an Inconclusive result are counted but are not failures — they were not run because the plan limits the number of tests per run; see Results.

Output

Nothing on the pipeline. On the host: the project summary, then (at Information or more) one line per test as it finishes —

✅  Passed  [SourceDataTests].[0].[Check if the table DIM.AIRLINES is not empty.]
❌  Failed  [SourceDataTests].[2].[Check if the table DIM.DESTINATIONS is not empty.]

— then the result block:

Results:  😻 41 passed   😿 1 failed

Total:             42 tests
Pass rate:         97.6%.
Execution time:    00:00:03.2140115

followed by a coloured pass-rate bar. Details of failed tests are in the project’s outputs and on Get-CatTestResult.

Errors

Refusals from the sign-in and plan check are terminating errors with the CatPortal.* ids listed on the Introduction page. A project that fails to open is a non-terminating error (the message is printed, nothing runs). Failed tests are not errors — read Get-CatTestResultSummary to fail a script.

Examples 

# the project in the current directory
Invoke-CatProject

# a specific project, quiet
Invoke-CatProject -Path 'D:\Testing\DwhTests.cat.yaml' -LoggingLevel None

# only tests tagged Departures or Passengers, but not ManualOnly; no Excel/JSON/database outputs
Invoke-CatProject -IncludeTag Departures, Passengers -ExcludeTag ManualOnly -SkipOutputs

# in a pipeline (Enterprise): run, then fail the job on failed or errored tests
Import-Module CAT -RequiredVersion '3.0.0'
Invoke-CatProject -Path "$(Build.SourcesDirectory)\tests\Dwh.cat.yaml" -ExcludeTag ManualOnly
$s = Get-CatTestResultSummary
if ($s.FailedCount -gt 0 -or $s.ErrorCount -gt 0) { exit 1 }
← Invoke-CatCommand
Invoke-CatTest →