Get Help

invoke_project

Opens a project, runs its tests — all of them or a subset — writes the project's outputs and returns the summary. The one-liner for scripts and notebooks.

Signature 

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.
filter str None Run only tests whose full name matches the pattern. * any text, ? one character, not case-sensitive, the square brackets of the full name are ignored.
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. On standard output, at the default INFORMATION level, CAT’s log of the run.

Raises

The license key and plan check (first call of the process) raises the CatPortalError family listed on the Introduction page. 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 

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)
← invoke_command
invoke_tests →