pytest_test_categories.errors

Centralized error registry for pytest-test-categories.

This module provides a centralized registry of error codes and message formatting utilities for all violations and warnings in the plugin.

Each error code follows the format TC### where: - TC = Test Categories prefix - ### = Three-digit numeric identifier

Error Code Ranges: - TC001-TC099: Resource isolation violations (network, filesystem, process, database, sleep) - TC100-TC199: Timing violations - TC200-TC299: Distribution warnings - TC900-TC999: Internal errors

Example Usage:

>>> from pytest_test_categories.errors import ERROR_CODES, format_error_message
>>> error_code = ERROR_CODES['network_violation']
>>> message = format_error_message(
...     error_code=error_code,
...     what_happened='Test attempted connection to api.example.com:443',
...     remediation=['Mock the network call', 'Use dependency injection']
... )
>>> print(message)

See also

• exceptions.py: Exception classes that use these error codes

• timing.py: TimingViolationError that uses these error codes

Attributes

ERROR_CODES

Classes

ErrorCode

A structured error code with associated metadata.

Functions

format_error_message(error_code, what_happened, ...[, ...])

Format a standardized error message with remediation guidance.

Module Contents

class pytest_test_categories.errors.ErrorCode

A structured error code with associated metadata.

code

The error code (e.g., ‘TC001’).

title

A short title describing the error.

why_it_matters

Explanation of why this violation is important.

doc_url

Full URL to the documentation for this error.

Example

>>> error = ErrorCode(
...     code='TC001',
...     title='Network Access Violation',
...     why_it_matters='Small tests must be hermetic...',
...     doc_url='https://pytest-test-categories.readthedocs.io/...'
... )

code: str

doc_url: str

title: str

why_it_matters: str

pytest_test_categories.errors.format_error_message(error_code, what_happened, remediation, test_nodeid=None, test_size=None)

Format a standardized error message with remediation guidance.

This function creates a consistently formatted error message that includes: 1. Error code and title (for grep-friendly CI log parsing) 2. Test context (nodeid, size) if provided 3. What happened (specific violation details) 4. Why it matters (explanation from error code) 5. How to fix (bullet-point remediation options) 6. Documentation link

Parameters:

• error_code (ErrorCode) – The ErrorCode instance for this violation.

• what_happened (str) – Description of what went wrong.

• remediation (list[str]) – List of remediation suggestions.

• test_nodeid (str | None) – Optional pytest node ID of the failing test.

• test_size (str | None) – Optional test size category name.

Returns:

A formatted multi-line error message string.

Return type:

str

Example

>>> error_code = ERROR_CODES['network_violation']
>>> message = format_error_message(
...     error_code=error_code,
...     what_happened='Test attempted connection to api.example.com:443',
...     remediation=['Mock the network call', 'Use dependency injection'],
...     test_nodeid='tests/test_api.py::test_fetch',
...     test_size='SMALL',
... )

pytest_test_categories.errors.ERROR_CODES: dict[str, ErrorCode]