cache.rst

Overview

The [cache.rst](/projects/286/67341) file documents the **pytest cache provider plugin**, which is an integral component of the `pytest` testing framework. Its primary purpose is to **manage test state and results across test runs**, enabling features such as rerunning only failed tests, prioritizing failures, and persisting arbitrary JSON-serializable data between test sessions.

Key functionalities covered in this documentation include:

Command-line options to rerun failed tests or prioritize them.
Cache management commands to inspect, clear, or manipulate cached data.
The config.cache API for plugins or test code to store and retrieve persistent state.
The stepwise testing mode to incrementally fix failures.
Behavior customization when no previous failures exist.

This file serves both as a user guide for leveraging these features during test runs and as a reference for plugin developers who want to interact with pytest’s caching mechanism.

Detailed Explanation of Features and Usage

Command-line Options for Failure-based Test Execution

The plugin introduces several CLI options that control how tests are selected and ordered based on previous results.

Option	Description
`--lf`, `--last-failed`	Runs only the tests that failed in the last pytest invocation.
`--ff`, `--failed-first`	Runs previously failing tests first, then runs the rest of the test suite.
`--cache-clear`	Clears all cached data before the test run begins.
`--nf`, [--new-first](/projects/286/67223)	Runs new tests first, then runs the rest, with tests sorted by file modification time.
--lfnf	Governs behavior of `--last-failed` when no failures exist (`all` or `none` modes).
`--sw`, `--stepwise`	Runs tests until the first failure, then stops; on subsequent runs continues from last failure.
`--stepwise-skip`	Skips one failing test in stepwise mode, continuing to next failure. Enables stepwise implicitly.

Usage Examples

Rerun only failures:
```
pytest --lf
```
Runs only the tests that failed previously, skipping all passing tests.
Run failures first, then others:
```
pytest --ff
```
Runs failed tests first, followed by the passing tests.
Clear cache before running:
```
pytest --cache-clear
```
Removes all cached data to ensure a clean test environment.
Control behavior when no previous failures:
```
pytest --last-failed --last-failed-no-failures none
```
Does not run any tests if there were no failures in the last run (exits successfully).

The `config.cache` Object

Plugins and test support code can use the `config.cache` object to **store and retrieve persistent JSON-serializable data** across test runs. This enables expensive computations or state that should be reused without rerunning.

API Methods

cache.get(key: str, default=None) -> Any
Retrieve a cached value by key. Returns default if the key is missing.
cache.set(key: str, value: Any) -> None
Store a JSON-serializable value under the specified key.

Example Usage in a Plugin or Fixture

import pytest

def expensive_computation():
    print("running expensive computation...")
    return 42

@pytest.fixture
def mydata(pytestconfig):
    val = pytestconfig.cache.get("example/value", None)
    if val is None:
        val = expensive_computation()
        pytestconfig.cache.set("example/value", val)
    return val

def test_function(mydata):
    assert mydata == 23

On the first run, the expensive computation is done and cached.
On subsequent runs, the cached value is reused without recomputation.

Inspecting and Clearing Cache Contents

Inspect cache:
```
pytest --cache-show
```
Displays all cached keys and values.
Filter cache inspection by glob pattern:
```
pytest --cache-show example/*
```
Clear cache:
```
pytest --cache-clear
```
Removes all cached data, useful for clean CI runs or troubleshooting.

Stepwise Testing Mode

The `--sw` or `--stepwise` option allows developers to **incrementally fix failing tests one at a time**:

Runs tests until the first failure and stops.
On next run, resumes from last failure and continues until next failure.
Optionally, --stepwise-skip ignores one failing test to avoid getting stuck.

This mode is especially useful when many tests fail, enabling a focused fix-and-verify cycle.

Implementation Details and Algorithms

The plugin stores test outcomes keyed by test node IDs in the cache directory (.pytest_cache by default).
It uses JSON serialization to persist cache entries.
On test collection, the plugin reads cached failure information to reorder or filter tests based on command-line options.
The --stepwise mechanism tracks the last failing test index and controls test execution accordingly.
Cache clearing removes the entire cache directory contents.

Interactions with Other System Components

Test Collection: The plugin hooks into pytest’s collection phase to reorder or deselect tests according to cached failure data.
CLI: Provides command-line options that influence test session behavior.
Plugins: Exposes the config.cache API for other plugins or conftest.py files to persist data.
Filesystem: Stores cache files in .pytest_cache directory for persistence between runs.
Test Reporting: Uses cached data to generate informative messages about reruns and test order.

Visual Diagram: Plugin Structure and Workflow

flowchart TD
    A[pytest CLI Invocation] --> B{Parse CLI Options}
    B -->|--lf / --ff / --sw| C[Cache Plugin]
    B -->|Other options| D[pytest core]

    C --> E[Load .pytest_cache Data]
    E --> F{Determine Tests to Run}
    F -->|--lf| G[Select Failed Tests Only]
    F -->|--ff| H[Run Failed Tests First]
    F -->|--sw| I[Run Tests Until Failure]
    F -->|Default| J[Run All Tests]

    G --> K[pytest Collection - Filtered]
    H --> K
    I --> K
    J --> K

    K --> L[pytest Test Execution]
    L --> M[Update Cache with Results]
    M --> E

    subgraph Cache API Usage
    N[Plugins/Fixtures] --> O[config.cache.get/set]
    end

    style C fill:#f9f,stroke:#333,stroke-width:2px

The diagram illustrates how the cache plugin integrates into the pytest execution flow:
- It interprets CLI options to decide which tests to run.
- Loads and updates cache data from the filesystem.
- Interacts with pytest’s collection and execution phases.
- Exposes a cache API usable by other plugins and test code.

Summary

The [cache.rst](/projects/286/67341) documentation provides a comprehensive guide to pytest’s cache provider plugin. This plugin enhances testing efficiency by enabling reruns of failed tests, caching persistent state, and providing flexible test execution options. It is an essential tool for speeding up test cycles, especially in large test suites, and serves as a foundation for advanced test session management.

By understanding this plugin’s capabilities and APIs, users and plugin authors can leverage caching to improve test reliability, reduce runtime, and create sophisticated test workflows.

For more details, see also the `config.cache` fixture documentation and pytest command-line option references.