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_groupare attached to the same marker sopytest -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
|
None
|
control_ids
|
list[str] | None
|
Framework control IDs this standard attests to
(e.g. |
None
|
control_group
|
str | None
|
Free-form group label (e.g. |
None
|
**kwargs
|
str | bool | list[str]
|
Custom markers declared in |
{}
|
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);
|
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.