Skip to content

The @cats and @cats_requires decorators

from cats import cats, cats_requires. @cats attaches a standard (and, optionally, its control ids and group) to a test, and carries the custom markers declared in reporting.custom_markers. Its three keywords are frozen by the compatibility contract.

@cats_requires declares what the deployment must provide for the test to apply; the test runs only when test_selection.provides in cats.yaml (or a pytest_cats_provides hook) provides every requirement, and is recorded as not_run otherwise. See Test selection.

cats(*, standard_name=None, control_ids=None, control_group=None, **kwargs)

Attach compliance metadata and custom markers to a test.

@cats is optional metadata: CATS records every test in report.json and junit.xml whether or not it is decorated, and the compliance writers (OSCAL findings, Security Hub findings) act only on tests that carry a standard. A test that attests to no standard but carries a custom marker, @cats(team="platform"), is a first-class case.

The keywords are standard_name, control_ids and control_group. Every other keyword is a custom marker and must be declared under reporting.custom_markers in cats.yaml; @cats never gains a keyword, so a declared custom marker is never shadowed by a later release.

Markers applied:

  • cats_standard(name=..., control_ids=..., control_group=...) — one per standard name. control_ids / control_group are attached to the same marker so pytest -m "cats_standard(name='...')" selects by standard.
  • Each custom marker as marker(kwarg=value), one marker per list element for a list value.

Parameters:

Name Type Description Default
standard_name str | list[str] | None

One or more standard identifiers. Stack multiple @cats() decorators to attach different control_ids or control_group per standard.

None
control_ids list[str] | None

Framework control IDs this standard attests to (e.g. ["AC-3", "SC-7"]). Per-test override of the pytest_cats_standards registry. If both empty, the writer falls back to [standard_name] as a single control ID.

None
control_group str | None

Free-form group label (e.g. "Governance") for grouping observations in OSCAL output. Emitted as observation.props[name="control-group"].

None
**kwargs str | bool | list[str]

Custom markers declared in reporting.custom_markers; a value is a str, a bool or a list of str.

{}

Raises:

Type Description
CatsUsageError

A keyword is not a declared custom marker (a misspelled CATS keyword would otherwise silently drop a standard from the evidence); control_ids or control_group is given without standard_name; standard_name is not a str or a non-empty list of str; a custom marker value has another type; a control id is not a non-empty string, or is not an OSCAL token while oscal_ar is a configured format.

cats_requires(*requirements)

Declare what the deployment must provide for this test to apply.

A test runs only when every requirement it declares is provided, by test_selection.provides in cats.yaml or by a pytest_cats_provides hook. Otherwise it is deselected and recorded as not_run, with the gap named (requires {a, b}; not provided {b}), where a test -k or -m removed leaves no record at all. A test with no requirements always runs.

Applies one cats_requires(name=...) mark per distinct requirement, sorted, so @cats_requires("b", "a") and @cats_requires("a", "b") attach identical marks, and stacked decorators union their requirements. pytest -m "cats_requires(name='x')" selects on it like any mark (and is recorded in run.selection like any -m). Requirement names are free-form strings: a new deployment variant is a new name, and CATS keeps no registry of them. The semantics are AND only: mutually exclusive variants are two positive requirements (standard-deployment / container-deployment), and a control shared across variants is two tests, or one requirement every variant provides.

cats_requires is a precondition on the deployment, declared on the test, not a feature flag: tests cannot read the provided set, and providing a requirement only ever runs more tests, never changes what a test asserts. Applies to classes like any pytest mark.

Raises:

Type Description
CatsUsageError

No requirement was given, or one is not a non-empty string.

Options

Every keyword other than these three is a custom marker and must be declared under reporting.custom_markers; an undeclared keyword, including a misspelled CATS keyword, raises CatsUsageError when the test module is imported, so a typo can never silently drop a standard from the evidence.

Option Type Description
standard_name str \| list[str] Compliance standard identifier. Pass a list to attach the same test to several standards. Optional: a test may carry only custom markers.
control_ids list[str] Framework control IDs this standard attests to, carried as written into every report format. Overrides the standards registry per field. Needs standard_name. With oscal_ar in report_formats each ID must be an OSCAL token (ac-2.1, not AC-2(1)); the decorator refuses one that is not at import time.
control_group str Free-form group label emitted as an observation control-group prop. Overrides the registry. Needs standard_name.
**kwargs str \| bool \| list[str] Custom markers declared under reporting.custom_markers in cats.yaml.

Skipping and slow-marking are pytest's job: use @pytest.mark.skip(reason=...) and your own registered markers alongside @cats.