pytest-recording

Install the plugin via pip.

⚠️ Incompatibility Warning: If you have pytest-vcr installed, you must uninstall it before using pytest-recording as they are incompatible.

pip install pytest-recording

By default, pytest-recording organizes cassettes into a directory structure to prevent name collisions between different test modules.

For a test file located at tests/test_users.py, cassettes will be stored in: tests/cassettes/test_users/

Individual cassette filenames are derived from the test class name and test function name (e.g., TestUserClass.test_create.yaml). If no class is present, the function name is used.

When determining which hosts are allowed during network blocking, pytest-recording follows a specific priority order. The first source found is used:

1. The allowed_hosts argument passed to the @pytest.mark.block_network marker.
2. The --allowed-hosts CLI option.
3. The allowed_hosts key provided in the vcr_config fixture.

When configuring pytest-recording, setting the record_mode to rewrite triggers a specific cleanup behavior:

1. The library calculates the target cassette path.
2. It attempts to delete the existing cassette file at that path.
3. It automatically switches the internal record_mode to new_episodes to ensure the new recording starts fresh without erroring on the missing file.

The CombinedPersister is an internal mechanism used to support loading data from multiple cassette files. It allows the library to:

• Load the primary cassette specified by the test.
• Load additional cassettes provided via pytest markers (extra_paths).
• Combine the requests and responses from all found cassettes into a single unified view for the test execution.

Note: While it loads from multiple sources, it only saves the recording to the first (primary) cassette file.

pytest-recording automatically manages cassette file names and locations based on your test structure.

1. Filename Length Safety: If a generated default_cassette name (plus its extension) exceeds the system's maximum filename length (MAX_FILENAME_LEN), the library truncates the name and appends an MD5 hash to ensure uniqueness and prevent OS errors (e.g., prefix...hash.yaml).
2. Path Transformation: The library uses a path_transformer to ensure cassettes are stored in the correct directory.
3. Extra Cassettes via Markers: You can specify additional cassette files using pytest markers. These paths can be absolute or relative. Relative paths are resolved against the vcr_cassette_dir.

Provide a dictionary via the vcr_config fixture to set global or scoped VCR options (e.g., filter_headers, ignore_hosts). The fixture can have any scope: session, package, module, or function.

Configuration Priority (Low to High):

1. vcr_config fixture
2. Marks applied from broadest scope (session) to narrowest (function)

import pytest

@pytest.fixture(scope="module")
def vcr_config():
    return {
        "filter_headers": ["authorization"],
        "ignore_hosts": ["169.254.169.254"],
    }

You can inject the vcr fixture into your test function to inspect the cassette, such as checking the play_count.

import pytest
import requests

@pytest.mark.vcr
def test_call_count(vcr):
    assert requests.get("http://httpbin.org/get").text == '{"get": true}'
    assert requests.get("http://httpbin.org/ip").text == '{"ip": true}'
    assert vcr.play_count == 2

Use the @pytest.mark.vcr decorator to enable recording/replaying for a test. By default, cassettes are stored in cassettes/{module_name}/test_name.yaml.

import pytest
import requests

@pytest.mark.vcr
def test_single():
    assert requests.get("http://httpbin.org/get").text == '{"get": true}'

You can control which cassettes are used via decorators:

• Use @pytest.mark.default_cassette("filename.yaml") to specify a custom name for the default cassette.
• Use @pytest.mark.vcr("path1.yaml", "path2.yaml") to use multiple cassettes in addition to the default one.

import pytest
import requests

# Custom filename
@pytest.mark.default_cassette("example.yaml")
@pytest.mark.vcr
def test_default():
    assert requests.get("http://httpbin.org/get").text == '{"get": true}'

# Multiple cassettes
@pytest.mark.vcr("/path/to/ip.yaml", "/path/to/get.yaml")
def test_multiple():
    assert requests.get("http://httpbin.org/get").text == '{"get": true}'
    assert requests.get("http://httpbin.org/ip").text == '{"ip": true}'

Use the pytest_recording_configure hook in your conftest.py to access the VCR instance. This allows you to register custom matchers, persisters, or other VCR.py extensions.

# conftest.py

def jurassic_matcher(r1, r2):
    assert r1.uri == r2.uri and "JURASSIC PARK" in r1.body

def pytest_recording_configure(config, vcr):
    vcr.register_matcher("jurassic", jurassic_matcher)