---
title: "Invoke-CatTest"
description: "Invoke-CatTest — run the tests of the open project and get the summary back."
url: "https://docs.justcat.it/reference/powershell-module/invoke-cattest/"
---
# Invoke-CatTest

## Synopsis

```powershell
Invoke-CatTest [-Filter <string>] [-TestID <guid[]>] [-IncludeTag <string[]>] [-ExcludeTag <string[]>] [-SkipOutputs]
```

## Parameters

| Parameter | Type | Position | Default | Meaning |
|-----------|------|----------|---------|---------|
| `-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`). |
| `-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. |

## What it does

Runs the tests of the project opened with `Open-CatProject` — the filters combine, a test runs only if it satisfies all of them — writes the project's outputs unless `-SkipOutputs`, and returns the summary. Unlike `Invoke-CatProject` it does not open, does not print the project, and does not print the result block; it is the building block for scripts that open once and run several times (different filters, the same project), or that want the summary as a value. Each call replaces the previous results of the session.

## Output

One `TestExecutionSummary` object — the same `Get-CatTestResultSummary` returns: `TotalCount`, `PassedCount`, `FailedCount`, `ErrorCount`, `InconclusiveCount`, `PassRate`, `Duration`, `Results`, … On the host, one line per test as it finishes only when the session's logging level (set by `Open-CatProject -LoggingLevel`) is `Information` or more.

## Errors

`There is no CAT session active…` when no project was opened. **Failed tests are not errors** — check the returned summary.

## Examples

```powershell
Open-CatProject -Path 'D:\Testing\DwhTests.cat.yaml'
$s = Invoke-CatTest -IncludeTag Smoke
if ($s.FailedCount -eq 0) { $s = Invoke-CatTest -ExcludeTag Smoke }
"$($s.PassRate) % passed"

# the same project, one suite at a time
foreach ($suite in 'Departures', 'Arrivals') {
    $s = Invoke-CatTest -Filter "[$suite]." -SkipOutputs
    "$suite`: $($s.FailedCount) failed"
}
```

## Related

- [Introduction](https://docs.justcat.it/reference/powershell-module/introduction/ "Introduction") — session model, logging, errors, sign-in.
- [`Invoke-CatProject`](https://docs.justcat.it/reference/powershell-module/invoke-catproject/ "Invoke-CatProject") — open and run in one call.
- [`Get-CatTestResult`](https://docs.justcat.it/reference/powershell-module/get-cattestresult/ "Get-CatTestResult") — the per-test results of the last call.
- [`Show-CatTestResultSummary`](https://docs.justcat.it/reference/powershell-module/show-cattestresultsummary/ "Show-CatTestResultSummary") — print the result block.