reference.rst

Overview

The `reference.rst` file serves as the comprehensive API reference documentation for the pytest testing framework. It provides a detailed and structured catalog of pytest's internal constants, functions, classes, fixtures, hooks, configuration options, warnings, exceptions, and environment variables. The file is designed as a centralized resource for developers and users to understand the available pytest features, their usage, parameters, and integration points.

This documentation is part of pytest's official docs and is intended to assist plugin authors, advanced users, and contributors by exposing the full API surface, including public interfaces and extension hooks.

Key functionalities covered include:

Detailed Documentation of Major Sections

Constants

Functions

Core pytest functions include:

Marks

Marks are decorators to add metadata or modify test behavior.

Fixtures

Fixtures provide test setup/teardown and resource management.

Example usage of fixture in test:

def test_output(capsys):
    print("hello")
    out, err = capsys.readouterr()
    assert out == "hello\n"

Hooks

Hooks enable customization and extension of pytest's behavior.

Collection Tree Objects

These classes represent the test collection hierarchy:

Other Objects

Key classes accessible from fixtures or hooks:

Global Variables

Special global variables recognized by pytest when defined in test modules or `conftest.py` files:

Environment Variables

List of environment variables that influence pytest behavior, for example:

Configuration Options

Built-in config options that can be set in `pytest.ini`, `tox.ini`, `pyproject.toml`, or `setup.cfg`:

Command-line Flags

Extensive list of pytest CLI options for test selection, reporting, debugging, logging, collection control, and more.

Examples:

Implementation Details & Algorithms

Interaction with Other System Components

Visual Diagram: pytest API Structure Class Diagram

The following Mermaid class diagram summarizes the main classes and their relationships as documented in `reference.rst`. It focuses on the core pytest object model relevant to test collection and execution.

classDiagram
    class Node {
        +id
        +name
        +parent
        +iter_markers()
    }
    class Collector {
        +collect()
        +add_items()
    }
    class Item {
        +runtest()
        +setup()
        +teardown()
    }
    class File
    class Package
    class Module
    class Class
    class Function
    class Session

    Node <|-- Collector
    Node <|-- Item

    Collector <|-- File
    Collector <|-- Package
    Collector <|-- Module
    Collector <|-- Class

    Item <|-- Function

    Session --> Collector : collects

    %% Additional classes for fixtures and markers
    class FixtureDef {
        +scope
        +func
    }
    class Mark {
        +args
        +kwargs
    }
    class Metafunc {
        +parametrize()
    }

    Item o-- FixtureDef : uses
    Node o-- Mark : attached to
    Metafunc ..> Item : parameterizes

Usage Examples

import pytest

@pytest.mark.parametrize("input,expected", [
    (1, 2),
    (3, 4),
    pytest.param(5, 6, id="special_case", marks=pytest.mark.skip)
])
def test_increment(input, expected):
    assert input + 1 == expected

def test_fail_example():
    pytest.fail("This test fails deliberately.")

def test_skip_example():
    pytest.skip("Skipping this test for demonstration.")

Summary

The `reference.rst` file is a vital document that fully enumerates pytest's API, enabling advanced usage, plugin development, and customization. It covers everything from core functions and fixtures to hooks, markers, configuration, and environment variables, giving a complete picture of pytest's extensibility and functionality.

This documentation facilitates deep understanding and correct usage of pytest's rich feature set, supporting both new users and experienced developers in leveraging pytest effectively.

End of documentation for reference.rst