---
title: "invoke_tests"
description: "invoke_tests — run the tests of the open project and return the summary."
url: "https://docs.justcat.it/reference/python-module/invoke-tests/"
---
# invoke_tests

## Signature

```python
cat.invoke_tests(filter: str = None, test_ids: set = None,
                 include_tags: str = None, exclude_tags: str = None,
                 skip_outputs: bool = False)
```

## Parameters

| Parameter | Type | Default | Meaning |
|-----------|------|---------|---------|
| `filter` | str | `None` | 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. |
| `test_ids` | set | `None` | Run only the tests with these IDs — `System.Guid` objects from `get_tests()` of the open project (strings are rejected with `TypeError`). An empty set means no filter. |
| `include_tags` | str | `None` | Run only tests that carry **at least one** of the tags. Several tags in one string, separated by `,` or `;`. Not case-sensitive. |
| `exclude_tags` | str | `None` | Run only tests that carry **none** of the tags. |
| `skip_outputs` | bool | `False` | `True`: skip every output defined in the project. |

## What it does

Runs the tests of the project opened with `open_project` — the filters combine, a test runs only if it satisfies all of them — writes the project's outputs unless `skip_outputs`, and returns the summary. Unlike `invoke_project` it does not reload anything: the building block for scripts that open once and run several times (different filters, the same project, stable test IDs). Each call replaces the previous results.

## Returns

A `TestExecutionSummary` object — the same `get_test_results_summary` returns.

## Raises

The sign-in and plan check (first call of the process) raises the `CatPortalError` family listed on the [Introduction](https://docs.justcat.it/reference/python-module/introduction/ "Introduction") page. With no open project: in the current version a bare `TypeError: exceptions must derive from BaseException` (not a readable message) — call `open_project` first. `TypeError: No method matches given arguments for List`1.Add` when `test_ids` holds strings instead of the `Guid` objects from `get_tests`. **Failed tests do not raise** — read the summary.

## Examples

```python
cat.open_project("D:/Testing/DwhTests.cat.yaml")
smoke = cat.invoke_tests(include_tags="Smoke")
if smoke.FailedCount == 0:
    full = cat.invoke_tests(exclude_tags="Smoke")

# the same project, one suite at a time
for suite in ("Departures", "Arrivals"):
    s = cat.invoke_tests(filter=f"[{suite}].", skip_outputs=True)
    print(suite, s.FailedCount, "failed")
```

## Related

- [Introduction](https://docs.justcat.it/reference/python-module/introduction/ "Introduction") — session model, logging, .NET objects, exceptions, sign-in.
- [`invoke_project`](https://docs.justcat.it/reference/python-module/invoke-project/ "invoke_project") — open and run in one call.
- [`get_tests`](https://docs.justcat.it/reference/python-module/get-tests/ "get_tests") — the IDs for `test_ids`.
- [`get_test_results`](https://docs.justcat.it/reference/python-module/get-test-results/ "get_test_results") — the per-test results of the last call.