Registry / testing / pytest-recording

pytest-recording

JSON →
library0.13.4pypypi✓ verified 26d ago

pytest-recording is a pytest plugin that integrates VCR.py to record and replay HTTP traffic during tests. It aims to make testing code that interacts with external services faster and more reliable by preventing unnecessary network requests. The library uses VCR.py's 'none' recording mode by default to avoid unintentional live network calls. The current version is 0.13.4, and it maintains an active release cadence.

pip install pytest-recording
INSTALL
IMPORT
SIG · PYTEST-RECORDING
P
pytest-recording
testingpythonv0.13.4
Install
3.8s avg
Import
404ms
Disk
34MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.13.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.432s · 34.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.8s · import 0.376s · 36MB
34MB installed
● package 34MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pytest.mark.vcr
import pytest # Use as decorator: @pytest.mark.vcr
pytest-recording integrates directly with pytest markers and fixtures, rather than providing direct class imports from its own namespace.
vcr_config fixture
import pytest @pytest.fixture(scope='module') def vcr_config(): return {'filter_headers': ['Authorization']}
The `vcr_config` fixture is a common way to configure VCR.py behavior globally or per scope for pytest-recording.

This quickstart demonstrates setting up `pytest-recording` to record and replay HTTP requests using the `@pytest.mark.vcr` decorator. It includes a `vcr_config` fixture, typically placed in a `conftest.py` file or at the top of a test module, to apply global VCR.py configurations like filtering sensitive headers. To run these tests and record the network interactions, use `pytest --record-mode=once your_test_file.py`. The `--record-mode=once` argument is crucial for the initial recording, as `pytest-recording` defaults to `none` mode to prevent accidental network requests. Subsequent runs without this flag will replay from the cassette.

import pytest import requests import os # Define a vcr_config fixture in conftest.py or test file scope @pytest.fixture(scope="module") def vcr_config(): """ Global VCR.py configuration for all tests in this module/session. Filters out sensitive Authorization headers to prevent them from being written to cassettes. """ return {"filter_headers": ["Authorization"], "ignore_localhost": True} @pytest.mark.vcr def test_http_get_request(): """ Records a simple HTTP GET request to httpbin.org. The cassette will be saved in a default location, e.g., cassettes/{module_name}/test_http_get_request.yaml. """ response = requests.get("http://httpbin.org/get") assert response.status_code == 200 assert response.json()["url"] == "http://httpbin.org/get" @pytest.mark.vcr def test_authenticated_api_call(): """ Demonstrates recording an API call with an Authorization header. The header is filtered by the vcr_config fixture defined above. """ # Simulate retrieving an API key from environment variables api_key = os.environ.get('PYTEST_TEST_API_KEY', 'fake_api_key_123') headers = {"Authorization": f"Bearer {api_key}"} response = requests.get("http://httpbin.org/headers", headers=headers) assert response.status_code == 200 # Verify that the Authorization header is not in the recorded response (due to filtering) assert "Authorization" not in response.json().get("headers", {}) assert "fake_api_key_123" not in str(response.json()) # Ensure actual key content not present
Debug
Known issues
breaking`pytest-recording` is incompatible with `pytest-vcr`. If you have `pytest-vcr` installed, you must uninstall it before using `pytest-recording` to avoid conflicts.
fix
Uninstall `pytest-vcr` using `pip uninstall pytest-vcr` before installing or using `pytest-recording`.
affects: All versions
gotchaBy default, `pytest-recording` uses VCR.py's `none` recording mode, which blocks all network requests and will cause tests to fail if a cassette doesn't exist. To allow network requests for initial recording or updates, you must explicitly set a recording mode (e.g., `once`, `all`, `new_episodes`) via the `--record-mode` CLI option.
fix
When running tests that require recording or updating cassettes, use `pytest --record-mode=once` (or another appropriate mode like `all`) in your command line.
affects: All versions
gotchaSensitive information like API keys, authorization tokens, or personally identifiable information can easily be recorded into VCR.py cassettes. This poses a security risk if cassettes are committed to version control.
fix
Use the `vcr_config` fixture or `pytest.mark.vcr` parameters to `filter_headers` and `filter_query_parameters`. For API keys, pass them via environment variables and ensure they are filtered out of the cassette. For example:
`@pytest.fixture(scope='module') def vcr_config(): return {'filter_headers': ['Authorization']}`
affects: All versions
gotchaConfiguration parameters for VCR.py can be provided via the `vcr_config` fixture (at session, package, module, or function scope) and via individual `pytest.mark.vcr` decorators. These configurations are merged, with more narrowly scoped settings (e.g., function-level mark) taking precedence over broader ones (e.g., session-level fixture).
fix
Be aware of the configuration priority: `vcr_config` fixture (lowest priority) < `pytest.mark.vcr` (broad scope) < `pytest.mark.vcr` (narrow scope, highest priority). Explicitly define parameters where you need specific overrides.
affects: All versions
Errors
Common errors & fixes
vcr.errors.UnhandledHTTPRequestError: No matching cassette was found for the following HTTP request:
The test attempted to make an HTTP request, but `pytest-recording` was in a recording mode (defaulting to `none`) that prevented live network calls or couldn't find a matching recorded interaction in the cassette.
fix
Change the recording mode to allow recording (e.g., `new_episodes` or `all`) using a pytest marker: `@pytest.mark.vcr(record_mode='new_episodes')`.
pytest_recording.errors.CassetteNotFoundError: Cassette not found: path/to/cassette.yaml
The test was run in a recording mode (typically `none` or `once`) that requires a pre-existing cassette file, but the specified file could not be located.
fix
Ensure the cassette file exists at the expected path, or change the recording mode to one that generates a cassette (e.g., `new_episodes` or `all`) using a pytest marker: `@pytest.mark.vcr(record_mode='new_episodes')`.
ModuleNotFoundError: No module named 'pytest_recording'
The `pytest-recording` library has not been installed in the Python environment where `pytest` is being executed.
fix
Install the library using pip: `pip install pytest-recording`.
E pytest.FixtureLookupError: fixture 'vcr' not found
Pytest could not locate the `vcr` fixture, either because `pytest-recording` is not installed, not correctly recognized as a pytest plugin, or the fixture was not properly requested by the test function.
fix
Ensure `pytest-recording` is installed (`pip install pytest-recording`) and the `vcr` fixture is correctly passed as an argument to your test function: `def test_example(vcr): ...`.
Upgrade
Version history
0.13.4latest on PyPI · released May 8, 2025
Audit
Dependencies
VCR.pyrequiredCore dependency for recording and replaying HTTP interactions.
pytestrequiredThis is a pytest plugin and requires pytest to function.
Agent activity
9 hits · last 30 days
node
8
Resources
pytest-recording — pip install pytest-recording · libregistry