pytest_test_categories.plugin

Core plugin implementation.

This module provides the pytest plugin entry point and hook implementations. It follows hexagonal architecture by orchestrating services and adapters rather than containing business logic.

The plugin’s sole responsibility is: - Registering pytest hooks - Orchestrating calls to services through ports - Managing session lifecycle

All business logic is delegated to services: - TestDiscoveryService: Finding test size markers - TimingValidationService: Validating test timing - DistributionValidationService: Validating distribution - TestReportingService: Managing test reports

All pytest interactions go through adapters: - PytestConfigAdapter: Config state management - PytestItemAdapter: Test item abstraction - PytestWarningAdapter: Warning system - TerminalReporterAdapter: Terminal output

This design makes the hooks thin orchestration layers (5-15 lines each) that are easy to understand and maintain.

Attributes

PLUGIN_VERSION

Functions

pytest_addoption(parser)	Add plugin-specific command-line options.
pytest_collection_finish(session)	Validate test distribution after collection.
pytest_collection_modifyitems(config, items)	Count tests by size and append size labels to test IDs.
pytest_configure(config)	Register markers and initialize plugin state.
pytest_runtest_call(item)	Block resources based on test size during execution and monitor threading.
pytest_runtest_makereport(item)	Validate timing and update test reports.
pytest_runtest_protocol(item, nextitem)	Track test timing during execution.
pytest_sessionfinish(session)	Send distribution stats and report data to controller when running as xdist worker.
pytest_terminal_summary(terminalreporter)	Write distribution summary, hermeticity violations, and optional size report.
pytest_testnodedown(node, error)	Aggregate distribution stats from a worker when it shuts down.

Module Contents

pytest_test_categories.plugin.pytest_addoption(parser)

Add plugin-specific command-line options.

This hook registers the –test-size-report option that controls whether and how test size reports are generated and the –test-categories-enforcement option for resource blocking control.

Parameters:

parser (pytest.Parser) – The pytest command-line option parser.

Return type:

None

pytest_test_categories.plugin.pytest_collection_finish(session)

Validate test distribution after collection.

Uses the distribution enforcement mode to determine behavior: - OFF: Skip validation entirely - WARN: Emit warning if out of spec, allow build to continue - STRICT: Raise DistributionViolationError if out of spec

Parameters:

session (pytest.Session) – The pytest session object.

Raises:

pytest.UsageError – If enforcement mode is STRICT and distribution is outside acceptable range.

Return type:

None

pytest_test_categories.plugin.pytest_collection_modifyitems(config, items)

Count tests by size and append size labels to test IDs.

Parameters:

• config (pytest.Config)

• items (list[pytest.Item])

Return type:

None

pytest_test_categories.plugin.pytest_configure(config)

Register markers and initialize plugin state.

Parameters:

config (pytest.Config) – The pytest configuration object.

Return type:

None

pytest_test_categories.plugin.pytest_runtest_call(item)

Block resources based on test size during execution and monitor threading.

This hook enforces resource isolation based on test size and enforcement configuration. When enforcement is enabled (strict or warn):

Network access (based on Google’s test size definitions): - Small tests: All network blocked (BLOCK_ALL) - Medium tests: Localhost only (LOCALHOST_ONLY) - Large/XLarge tests: Full network access (ALLOW_ALL)

Filesystem and process isolation (small tests only): - Small tests: Filesystem access blocked (no escape hatches) - Small tests: Subprocess spawning blocked - Small tests: Database connections blocked - Small tests: Thread creation warnings emitted

External systems detection (medium tests only): - Medium tests: Warn if testcontainers/docker imported (unless suppressed) - Suppressed via @pytest.mark.medium(allow_external_systems=True)

Note: Thread monitoring WARNS instead of blocking because many libraries use threading internally. Blocking would break legitimate test infrastructure.

Uses ExitStack pattern to manage all resource blockers together, ensuring proper cleanup even if exceptions occur.

Parameters:

item (pytest.Item) – The test item being executed.

Yields:

Control to pytest to run the test.

Return type:

collections.abc.Generator[None, None, None]

pytest_test_categories.plugin.pytest_runtest_makereport(item)

Validate timing and update test reports.

Parameters:

item (pytest.Item) – The test item that ran.

Yields:

Control to pytest to generate the report.

Return type:

collections.abc.Generator[None, None, None]

pytest_test_categories.plugin.pytest_runtest_protocol(item, nextitem)

Track test timing during execution.

Parameters:

• item (pytest.Item)

• nextitem (pytest.Item | None)

Return type:

collections.abc.Generator[None, None, None]

pytest_test_categories.plugin.pytest_sessionfinish(session)

Send distribution stats and report data to controller when running as xdist worker.

When running with pytest-xdist, workers collect and run tests but the terminal summary is displayed by the controller. This hook sends the worker’s stats back to the controller via the workeroutput mechanism.

Parameters:

session (pytest.Session) – The pytest session object.

Return type:

None

pytest_test_categories.plugin.pytest_terminal_summary(terminalreporter)

Write distribution summary, hermeticity violations, and optional size report.

Parameters:

terminalreporter (pytest.TerminalReporter)

Return type:

None

pytest_test_categories.plugin.pytest_testnodedown(node, error)

Aggregate distribution stats from a worker when it shuts down.

This xdist hook is called on the controller when a worker node completes. We use it to aggregate the distribution counts and report data from all workers.

Parameters:

• node (object) – The xdist WorkerController node that shut down.

• error (object | None) – Error if the worker crashed, None otherwise.

Return type:

None

pytest_test_categories.plugin.PLUGIN_VERSION