---
title: "Invoke-CatProject"
description: "Invoke-CatProject — open a project, run its tests, print the summary: the one-liner."
url: "https://docs.justcat.it/reference/powershell-module/invoke-catproject/"
---
# Invoke-CatProject

## Synopsis

```powershell
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](https://docs.justcat.it/reference/tests/properties/#full-name "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](https://docs.justcat.it/reference/tests/results/ "Test 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](https://docs.justcat.it/reference/powershell-module/introduction/ "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

```powershell
# 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 }
```

## Related

- [Introduction](https://docs.justcat.it/reference/powershell-module/introduction/ "Introduction") — session model, logging, errors, sign-in.
- [`Open-CatProject`](https://docs.justcat.it/reference/powershell-module/open-catproject/ "Open-CatProject") + [`Invoke-CatTest`](https://docs.justcat.it/reference/powershell-module/invoke-cattest/ "Invoke-CatTest") — the same in two steps, with the summary as return value.
- [Tests — properties](https://docs.justcat.it/reference/tests/properties/ "Test properties") — `Tags`, full name.
- [Outputs](https://docs.justcat.it/reference/outputs/ "Outputs") · [Run your tests](https://docs.justcat.it/how-to-guides/organize-and-run-tests/run-your-tests/ "Run your tests").