---
title: "invoke_project"
description: "invoke_project — open a project, run its tests, return the summary: the one-liner."
url: "https://docs.justcat.it/reference/python-module/invoke-project/"
---
# invoke_project

## Signature

```python
cat.invoke_project(project_file_path: str, loggingLevel: LoggingLevel = None,
                   filter: str = None, test_ids: set = None,
                   include_tags: str = None, exclude_tags: str = None,
                   skip_outputs: bool = False)
```

## Parameters

| Parameter | Type | Default | Meaning |
|-----------|------|---------|---------|
| `project_file_path` | str | required | A `.cat.yaml` file, or a directory with exactly one `*.cat.yaml`. Required — there is no current-directory default. |
| `loggingLevel` | LoggingLevel | `None` | `cat.LoggingLevel` member; used only when this is the first call of the process. See [Logging](https://docs.justcat.it/reference/python-module/introduction/#logging "Logging"). |
| `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 taken from `get_tests()` **of this same open project**; `invoke_project` reloads the project and gives every test a new ID, so IDs from an earlier load match nothing. Use `open_project` + `get_tests` + `invoke_tests` for ID-based runs. |
| `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. Same format. |
| `skip_outputs` | bool | `False` | `True`: skip every output defined in the project (files, database tables, …). |

## What it does

`open_project` followed by `invoke_tests`: reads the project file, loads data sources and tests from every list, generates metadata-driven tests, runs the tests that pass the filters (they combine — a test runs only if it satisfies all of them), writes the project's outputs unless `skip_outputs`, and returns the summary. The project stays open afterwards, so `get_test_results_summary()`, `get_test_results()` and the other project functions work on it. Tests with an `Inconclusive` result are counted but are not failures.

## Returns

A `TestExecutionSummary` object — `TotalCount`, `PassedCount`, `FailedCount`, `ErrorCount`, `InconclusiveCount`, `PassRate` (a `System.Decimal`), `Duration`, `Results`, … — see [`get_test_results_summary`](https://docs.justcat.it/reference/python-module/get-test-results-summary/ "get_test_results_summary"). On standard output, at the default `INFORMATION` level, CAT's log of the run.

## 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. `PlanLimitExceededError` when the project is over a per-project cap of the plan. A project that cannot be opened raises the engine's exception (`System.Exception: Failed to open the project file.` — the reason is in the log). **Failed tests do not raise** — read the summary.

## Examples

```python
from justcatit import cat

# everything in the project
summary = cat.invoke_project("D:/Testing/DwhTests.cat.yaml")
print(f"{summary.PassedCount}/{summary.TotalCount} passed, {summary.PassRate} %")

# only tests tagged Departures or Passengers, but not ManualOnly; no Excel/JSON/database outputs
summary = cat.invoke_project("D:/Testing/DwhTests.cat.yaml",
                             include_tags="Departures, Passengers", exclude_tags="ManualOnly",
                             skip_outputs=True)

# in a job (Enterprise): fail on failed or errored tests
if summary.FailedCount > 0 or summary.ErrorCount > 0:
    raise SystemExit(1)
```

## Related

- [Introduction](https://docs.justcat.it/reference/python-module/introduction/ "Introduction") — session model, logging, .NET objects, exceptions, sign-in.
- [`open_project`](https://docs.justcat.it/reference/python-module/open-project/ "open_project") + [`invoke_tests`](https://docs.justcat.it/reference/python-module/invoke-tests/ "invoke_tests") — the same in two steps, for several runs of one project.
- [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").