pytest_test_categories.violation_tracking

Violation tracking for hermeticity enforcement.

This module provides data structures for tracking resource isolation violations during test execution. It enables the plugin to collect violations in both WARN and STRICT modes for terminal summary reporting.

The violation tracker follows hexagonal architecture principles: - ViolationType: Enum defining the types of violations - ViolationRecord: Immutable record of a single violation - ViolationTracker: Service for collecting and querying violations

Example

>>> tracker = ViolationTracker()
>>> tracker.record_violation(
...     ViolationType.NETWORK,
...     'test_api.py::test_fetch',
...     'Attempted connection to example.com:443'
... )
>>> tracker.total_violations
1
>>> tracker.count_by_type(ViolationType.NETWORK)
1

See also

• exceptions.py: Exception classes for STRICT mode violations

• ports/network.py: NetworkBlockerPort that uses this tracker

Classes

ViolationRecord	Immutable record of a single hermeticity violation.
ViolationTracker	Service for tracking hermeticity violations during test execution.
ViolationType	Types of hermeticity violations that can be tracked.

Module Contents

class pytest_test_categories.violation_tracking.ViolationRecord(/, **data)

Bases: pydantic.BaseModel

Immutable record of a single hermeticity violation.

Captures all information about a violation for reporting purposes. The record is immutable (frozen) to ensure it cannot be modified after creation.

Parameters:

data (Any)

violation_type

The type of resource violation.

test_nodeid

The pytest node ID of the violating test.

details

Human-readable description of the violation.

failed

Whether this violation caused the test to fail (STRICT mode).

Example

>>> record = ViolationRecord(
...     violation_type=ViolationType.NETWORK,
...     test_nodeid='test_api.py::test_fetch',
...     details='Attempted connection to example.com:443',
...     failed=False
... )

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

details: str

failed: bool = False

test_nodeid: str

violation_type: ViolationType

class pytest_test_categories.violation_tracking.ViolationTracker

Service for tracking hermeticity violations during test execution.

This tracker collects violations from all resource blockers and provides query methods for terminal summary reporting. It is designed to work with both WARN and STRICT enforcement modes.

The tracker maintains violations grouped by type for efficient querying and supports counting unique tests across all violation types.

Example

>>> tracker = ViolationTracker()
>>> tracker.record_violation(
...     ViolationType.NETWORK,
...     'test_api.py::test_fetch',
...     'Attempted connection to example.com:443'
... )
>>> tracker.has_violations
True
>>> tracker.count_by_type(ViolationType.NETWORK)
1

Initialize an empty violation tracker.

count_by_type(violation_type)

Get the count of violations for a specific type.

Parameters:

violation_type (ViolationType) – The type to count violations for.

Returns:

Number of violations of the specified type.

Return type:

int

get_failed_tests()

Get the set of tests that failed due to violations (STRICT mode).

Returns:

Set of test nodeids that failed due to hermeticity violations.

Return type:

set[str]

get_test_nodeids_by_type(violation_type)

Get the list of test nodeids for a specific violation type.

Parameters:

violation_type (ViolationType) – The type to retrieve test nodeids for.

Returns:

List of test nodeids in the order they were recorded.

Return type:

list[str]

get_violations_by_type(violation_type)

Get all violations of a specific type.

Parameters:

violation_type (ViolationType) – The type to retrieve violations for.

Returns:

List of ViolationRecord instances for the specified type.

Return type:

list[ViolationRecord]

record_violation(violation_type, test_nodeid, details, *, failed=False)

Record a hermeticity violation.

Parameters:

• violation_type (ViolationType) – The type of resource violation.

• test_nodeid (str) – The pytest node ID of the violating test.

• details (str) – Human-readable description of the violation.

• failed (bool) – Whether this violation caused the test to fail (STRICT mode).

Return type:

None

property has_violations: bool

Check if any violations have been recorded.

Returns:

True if at least one violation has been recorded.

Return type:

bool

property total_violations: int

Get the total number of violations across all types.

Returns:

Total count of all recorded violations.

Return type:

int

property unique_test_count: int

Get the count of unique tests with violations.

A test is counted once even if it has multiple violation types.

Returns:

Number of unique test nodeids with violations.

Return type:

int

class pytest_test_categories.violation_tracking.ViolationType

Bases: enum.StrEnum

Types of hermeticity violations that can be tracked.

Each violation type corresponds to a resource category that tests may access inappropriately based on their size category.

NETWORK

Network access violation (socket connections)

FILESYSTEM

Filesystem access violation (file I/O)

PROCESS

Subprocess spawning violation

DATABASE

Database connection violation

SLEEP

Sleep/timing function violation

Initialize self. See help(type(self)) for accurate signature.

DATABASE = 'database'

FILESYSTEM = 'filesystem'

NETWORK = 'network'

PROCESS = 'process'

SLEEP = 'sleep'

property display_name: str

Get the human-readable display name for terminal output.

Returns:

Title-cased name suitable for terminal display.

Return type:

str