mark.rst

Overview

The [mark.rst](/projects/286/67332) file serves as a comprehensive guide and reference documentation for the **marking system** in the pytest testing framework. It explains how to apply metadata to test functions using pytest's `mark` feature, which is primarily used to tag tests with attributes such as `slow`, `skip`, `xfail`, or custom user-defined markers.

This documentation covers:

• The purpose and usage of pytest markers.

• Builtin markers available in pytest.

• How to create and register custom markers.

• The behavior of unknown or unregistered marks.

• Configuration options related to marker validation.

This file is primarily a user-facing documentation resource written in reStructuredText (reST) format, intended to help pytest users understand and utilize test marking effectively.

Detailed Explanation

What is a pytest Mark?

A **mark** in pytest is metadata attached to test functions or test classes to modify their behavior or provide additional information. For example, marks can be used to skip tests, run tests conditionally, or categorize tests for selective execution.

Builtin Markers

pytest provides several builtin markers, including but not limited to:

• usefixtures: Apply fixtures to tests or classes.

• filterwarnings: Filter warnings during test runs.

• skip: Always skip a test.

• skipif: Skip a test if a condition is met.

• xfail: Mark a test as an expected failure under certain conditions.

• parametrize: Run the same test function multiple times with different parameters.

Users can list all available markers (builtin and custom) via the command line:

pytest --markers

Registering Custom Marks

To avoid warnings and enable better integration, custom marks should be **registered** in pytest’s configuration.

Via pytest.ini

Add a `markers` section:

[pytest]
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    serial

Via pyproject.toml

[tool.pytest.ini_options]
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "serial",
]

Programmatically in pytest_configure hook

def pytest_configure(config):
    config.addinivalue_line(
        "markers", "env(name): mark test to run only on named environment"
    )

Registered marks appear in pytest's help and suppress warnings about unknown marks.

Handling Unknown Marks

Unregistered marks used as decorators (e.g., `@pytest.mark.unknown`) generate warnings by default to prevent silent errors caused by typos or misconfiguration.

To enforce strict validation and convert these warnings to errors, use the `--strict-markers` flag:

[pytest]
addopts = --strict-markers
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    serial

This ensures only registered marks are allowed, improving test suite robustness.

Usage Examples

import pytest

@pytest.mark.slow
def test_long_running():
    ...

@pytest.mark.skip(reason="Not implemented yet")
def test_feature():
    ...

@pytest.mark.parametrize("input,expected", [(1, 2), (3, 4)])
def test_addition(input, expected):
    assert add_one(input) == expected

Here, `slow` and `skip` are markers applied to tests, while `parametrize` runs the test multiple times with different inputs.

Important Implementation Details

• Marks are applied as decorators or attributes on test functions and classes.

• Marks do not affect fixtures.

• Registered marks improve discoverability and avoid warning spam.

• The --strict-markers option enforces rigorous validation.

• Markers are integral to pytest’s test selection and execution mechanisms (e.g., selecting tests via -m CLI option).

Interactions with Other Parts of the System

• pytest core uses marks during test collection and execution phases to alter test behavior.

• Plugins can define and register their own markers to extend pytest functionality.

• The command-line interface uses marks for filtering and reporting (-m option).

• Integration with fixtures is explicit; marks do not affect fixture behavior.

• The pytest_configure hook enables programmatic marker registration during pytest initialization.

Mermaid Diagram: pytest Marking System Structure

classDiagram
    class Mark {
        +name: str
        +description: str
        +apply(test_function)
    }

    class BuiltinMark {
        +usefixtures()
        +filterwarnings()
        +skip()
        +skipif(condition)
        +xfail(condition)
        +parametrize(params)
    }

    class CustomMark {
        +register(name, description)
    }

    class PytestConfig {
        +add_marker(name, description)
        +enable_strict_markers()
    }

    Mark <|-- BuiltinMark
    Mark <|-- CustomMark
    PytestConfig --> CustomMark : registers >
    PytestConfig --> BuiltinMark : manages >

Summary

The [mark.rst](/projects/286/67332) file is a vital reference documenting how pytest's marking system works. It educates users on the available builtin markers, guides on creating and registering custom markers, and clarifies the behavior when unknown markers are used. It also explains how markers integrate with pytest's configuration and testing lifecycle, enabling robust and flexible test management.

This documentation is essential for pytest users aiming to organize, categorize, and control test execution effectively using marks.