pytest-vcr

1.0.2 · maintenance · verified Sat Apr 11

pytest-vcr is a pytest plugin that simplifies testing HTTP interactions by integrating with VCR.py. It records HTTP requests and responses to YAML 'cassettes' during the first test run, then replays them on subsequent runs, making tests faster, more deterministic, and runnable offline. The current version is 1.0.2, released in April 2019, indicating an infrequent release cadence.

Warnings

breaking pytest-vcr is incompatible with `pytest-recording`, an alternative VCR.py plugin for pytest. If both are installed, unexpected behavior or errors may occur. It is recommended to choose one plugin and uninstall the other.
Fix: Uninstall `pytest-vcr` if using `pytest-recording`, or vice-versa: `pip uninstall pytest-vcr`
breaking The `vcr_cassette_path` fixture was removed in version 1.0.0. To customize cassette paths, use the `vcr_cassette_dir` and `vcr_cassette_name` fixtures instead.
Fix: Replace usage of `vcr_cassette_path` with `vcr_cassette_dir` and `vcr_cassette_name` fixtures.
deprecated The `--vcr-record-mode` command-line option was deprecated in version 1.0.0. Use `--vcr-record` instead.
Fix: Update CLI commands to use `--vcr-record` instead of `--vcr-record-mode`.
gotcha Cassettes can record sensitive information (e.g., API keys, authorization headers). To prevent this, use the `vcr_config` fixture in your `conftest.py` with `filter_headers` to redact sensitive data.
Fix: Implement a `vcr_config` fixture: `@pytest.fixture(scope='module') def vcr_config(): return {'filter_headers': [('authorization', 'DUMMY')]}`
gotcha When running tests in a Continuous Integration (CI) environment, it is recommended to use the `--vcr-record=none` option. This ensures that no new network requests are made, preventing accidental re-recording and verifying all necessary cassettes are committed.
Fix: Run tests with `pytest --vcr-record=none` in CI/CD pipelines.
gotcha pytest-vcr may not work reliably with services that use time-sensitive authentication (e.g., certain Google DataStore authentication methods) as recorded requests might become invalid over time, leading to cassette replay failures.
Fix: For services with time-sensitive authentication, consider using alternative mocking strategies or custom VCR.py matchers/filters if possible, or isolating these tests.
gotcha The library's last release was in April 2019. It may not be fully compatible with newer Python versions (e.g., Python 3.8+ as its core dependency `VCR.py` has dropped support for older Python versions like 3.7) or recent major versions of `pytest`.
Fix: Verify compatibility with your specific Python and pytest versions. Consider `pytest-recording` for more active maintenance and broader compatibility with modern Python/pytest ecosystems.

Install

pip install pytest-vcr Install stable version

Imports

pytest.mark.vcr
```
import pytest

@pytest.mark.vcr()
```
pytest-vcr is a pytest plugin and its main interaction is via markers, not direct imports of pytest_vcr.

Quickstart

Decorate your test function with `@pytest.mark.vcr()`. On the first run, it records HTTP traffic to a YAML cassette file (e.g., `cassettes/test_example_http_request.yaml`). Subsequent runs will replay from this cassette. Cassette files should be committed to version control.

import pytest
import requests # VCR.py integrates with requests

@pytest.mark.vcr()
def test_example_http_request():
    # The first run will record the request to 'cassettes/test_example_http_request.yaml'
    # Subsequent runs will replay from the cassette.
    response = requests.get('http://www.iana.org/domains/reserved')
    assert response.status_code == 200
    assert b'Example domains' in response.content

view raw JSON →