pytest_test_categories.exceptions¶

Exception classes for pytest-test-categories.

This module defines the exception hierarchy for resource isolation violations. These exceptions are raised when tests violate their size category’s resource restrictions.

Exception Hierarchy:: HermeticityViolationError (base) +– NetworkAccessViolationError +– FilesystemAccessViolationError +– SubprocessViolationError +– DatabaseViolationError +– SleepViolationError

All exceptions use the centralized error registry (errors.py) for: - Consistent error codes (TC001-TC099) - Standardized message format with “what happened”, “why it matters”, “how to fix” - Documentation links for each error type

Example

>>> raise NetworkAccessViolationError(
...     test_size=TestSize.SMALL,
...     test_nodeid='test_module.py::test_function',
...     host='api.example.com',
...     port=443
... )
[TC001] Network Access Violation
Test: test_module.py::test_function
Category: SMALL
...

Exceptions¶

`DatabaseViolationError`	Raised when a test attempts to connect to a database.
`FilesystemAccessViolationError`	Raised when a test makes an unauthorized filesystem access.
`HermeticityViolationError`	Base exception for test hermeticity violations.
`NetworkAccessViolationError`	Raised when a test makes an unauthorized network request.
`SleepViolationError`	Raised when a test calls time.sleep() or similar blocking functions.
`SubprocessViolationError`	Raised when a test attempts to spawn a subprocess.

Module Contents¶

exception pytest_test_categories.exceptions.DatabaseViolationError(test_size, test_nodeid, library, connection_string)[source]¶

Bases: HermeticityViolationError

Raised when a test attempts to connect to a database.

This exception is raised when a test attempts to make a database connection that violates its size category’s restrictions: - Small tests: No database access allowed (including :memory:) - Medium/Large/XLarge: All database access allowed

library[source]¶: The database library name (e.g., ‘sqlite3’, ‘psycopg2’).

connection_string[source]¶: The connection string or database path.

Initialize a database violation error.

Parameters:

test_size (pytest_test_categories.types.TestSize) – The test’s size category.
test_nodeid (str) – The pytest node ID of the violating test.
library (str) – The database library name.
connection_string (str) – The connection string or database path.

connection_string[source]¶

library[source]¶

exception pytest_test_categories.exceptions.FilesystemAccessViolationError(test_size, test_nodeid, path, operation)[source]¶

Bases: HermeticityViolationError

Raised when a test makes an unauthorized filesystem access.

This exception is raised when a test attempts filesystem access that violates its size category’s restrictions: - Small tests: No filesystem access (strict hermeticity - no escape hatches) - Medium/Large/XLarge: All filesystem access allowed

path[source]¶: The attempted path.

operation[source]¶: The type of operation attempted.

Initialize a filesystem access violation error.

Parameters:

test_size (pytest_test_categories.types.TestSize) – The test’s size category.
test_nodeid (str) – The pytest node ID of the violating test.
path (pathlib.Path) – The attempted path.
operation (pytest_test_categories.ports.filesystem.FilesystemOperation) – The type of operation attempted.

operation: pytest_test_categories.ports.filesystem.FilesystemOperation[source]¶

path[source]¶

exception pytest_test_categories.exceptions.HermeticityViolationError(test_size, test_nodeid, error_code, what_happened, remediation)[source]¶

Bases: Exception

Base exception for test hermeticity violations.

Raised when a test violates its size category’s resource restrictions. This is the base class for all resource violation exceptions.

Subclasses should provide: - Specific violation details (host, path, command, etc.) - Appropriate remediation suggestions - Reference to the appropriate error code

test_size[source]¶: The test’s size category.

test_nodeid[source]¶: The pytest node ID of the violating test.

error_code[source]¶: The ErrorCode instance for this violation type.

Initialize a hermeticity violation error.

Parameters:

test_size (pytest_test_categories.types.TestSize) – The test’s size category.
test_nodeid (str) – The pytest node ID of the violating test.
error_code (pytest_test_categories.errors.ErrorCode) – The ErrorCode instance for this violation type.
what_happened (str) – Description of the specific violation.
remediation (list[str]) – List of suggestions for fixing the violation.

error_code[source]¶

remediation[source]¶

test_nodeid[source]¶

test_size[source]¶

what_happened[source]¶

exception pytest_test_categories.exceptions.NetworkAccessViolationError(test_size, test_nodeid, host, port)[source]¶

Bases: HermeticityViolationError

Raised when a test makes an unauthorized network request.

This exception is raised when a test attempts to make a network connection that violates its size category’s restrictions: - Small tests: No network access allowed - Medium tests: Only localhost connections allowed - Large/XLarge tests: All network access allowed

host[source]¶: The attempted destination host.

port[source]¶: The attempted destination port.

Initialize a network access violation error.

Parameters:

test_size (pytest_test_categories.types.TestSize) – The test’s size category.
test_nodeid (str) – The pytest node ID of the violating test.
host (str) – The attempted destination host.
port (int) – The attempted destination port.

host[source]¶

port[source]¶

exception pytest_test_categories.exceptions.SleepViolationError(test_size, test_nodeid, function, duration)[source]¶

Bases: HermeticityViolationError

Raised when a test calls time.sleep() or similar blocking functions.

This exception is raised when a test attempts to use sleep functions that violate its size category’s restrictions: - Small tests: No sleep calls allowed (tests should be fast and deterministic) - Medium/Large/XLarge: All sleep calls allowed

function[source]¶: The sleep function that was called (e.g., ‘time.sleep’).

duration[source]¶: The sleep duration in seconds.

Initialize a sleep violation error.

Parameters:

test_size (pytest_test_categories.types.TestSize) – The test’s size category.
test_nodeid (str) – The pytest node ID of the violating test.
function (str) – The sleep function that was called.
duration (float) – The sleep duration in seconds.

duration[source]¶

function[source]¶

exception pytest_test_categories.exceptions.SubprocessViolationError(test_size, test_nodeid, command, command_args, method)[source]¶

Bases: HermeticityViolationError

Raised when a test attempts to spawn a subprocess.

This exception is raised when a test attempts to spawn a subprocess that violates its size category’s restrictions: - Small tests: No subprocess spawning allowed - Medium/Large/XLarge: All subprocess spawning allowed

command[source]¶: The command that was attempted.

command_args[source]¶: The arguments passed to the command.

method[source]¶: The method used to spawn (e.g., ‘subprocess.run’).

Initialize a subprocess violation error.

Parameters:

test_size (pytest_test_categories.types.TestSize) – The test’s size category.
test_nodeid (str) – The pytest node ID of the violating test.
command (str) – The command that was attempted.
command_args (tuple[str, Ellipsis]) – The arguments passed to the command.
method (str) – The spawn method used (e.g., ‘subprocess.run’).

command[source]¶

command_args[source]¶

method[source]¶