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 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. 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 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 

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 →