VCR.py

VCR.py is a Python library designed to simplify and speed up tests that make HTTP requests. It works by recording HTTP interactions (requests and responses) the first time a test is run and serializing them into a flat file called a 'cassette' (defaulting to YAML format).

On subsequent test runs, VCR.py intercepts matching HTTP requests and returns the recorded responses from the cassette instead of making actual network traffic. This provides:

• Offline capability: Run tests without an internet connection.
• Determinism: Tests are completely deterministic because they use recorded data.
• Speed: Test execution is significantly faster as it avoids network latency.

To update cassettes if an API changes, simply delete the existing cassette files and re-run your tests to record the new interactions.

You can override global VCR settings on a per-cassette basis by passing arguments directly to vcr.use_cassette(). Per-cassette overrides take precedence over the global configuration set in a vcr.VCR instance.

import vcr

with vcr.use_cassette('test.yml', serializer='json', record_mode='once'):
    # your http code here

You can install VCR.py from PyPI using pip.

pip3 install vcrpy

You can prevent VCR from interacting with certain requests using these methods:

• ignore_localhost=True: Ignores requests to localhost, 127.0.0.1, or 0.0.0.0.
• ignore_hosts: A list of hostnames to ignore.
• before_record_request / before_record_response: Return None in these callbacks to ignore specific interactions.

VCR.py uses a safe YAML loader that blocks !!python/object tags for security. To record/replay cassettes containing custom Python objects, register a custom serializer using yamlserializer.with_custom_tags. This allows you to define how specific tags are constructed during loading.

import vcr
from vcr.serializers import yamlserializer

def construct_my_header(loader, node):
    return MyHeader(loader.construct_sequence(node)[0])

my_vcr = vcr.VCR()
my_vcr.register_serializer("yaml", yamlserializer.with_custom_tags({
    "tag:yaml.org,2002:python/object/new:myapp.MyHeader": construct_my_header,
}))

For Pytest users, use the pytest-recording plugin. It provides fixtures for recording cassettes and supports blocking network access.

Note: pytest-vcr is an older, unmaintained plugin and is not recommended for new projects.

You can omit the path argument in use_cassette to automatically generate a filename based on the decorated function's name.

• If cassette_library_dir is NOT set: The cassette is saved in the same directory as the test function.
• If cassette_library_dir IS set: The cassette is saved in that directory.

You can customize the naming behavior using path_transformer and func_path_generator. To append a specific extension to all automatically named cassettes, use VCR.ensure_suffix.

from vcr import VCR

# Add a specific extension to all automatic cassette names
my_vcr = VCR(path_transformer=VCR.ensure_suffix('.yaml'))

@my_vcr.use_cassette
def my_test_function():
    ...

Use before_record_request or before_record_response to manipulate requests/responses before they are saved to a cassette.

• To mutate: Modify the request/response object and return it.
• To ignore: Return None to prevent the interaction from being recorded.

# Example: Ignore requests to '/login'
def before_record_cb(request):
    if request.path == '/login':
        return None
    return request

my_vcr = vcr.VCR(
    before_record_request=before_record_cb,
)

# Example: Scrub sensitive data from response body
def scrub_string(string, replacement=''):
    def before_record_response(response):
        response['body']['string'] = response['body']['string'].replace(string, replacement)
        return response
    return before_record_response

my_vcr = vcr.VCR(
    before_record_response=scrub_string(settings.USERNAME, 'username'),
)

To customize VCR's default behavior globally, instantiate a vcr.VCR object with your desired options. This object can then be used to manage cassettes via its .use_cassette() method.

Common configuration options include:

• serializer: The format used to save cassettes (e.g., 'json').
• cassette_library_dir: The directory where cassettes are stored.
• record_mode: Controls how new interactions are recorded (e.g., 'once').
• match_on: A list of attributes used to match requests.

import vcr

my_vcr = vcr.VCR(
    serializer='json',
    cassette_library_dir='fixtures/cassettes',
    record_mode='once',
    match_on=['uri', 'method'],
)

with my_vcr.use_cassette('test.json'):
    # your http code here

To prevent sensitive information from being recorded in cassettes, use the following configuration options:

• filter_headers: List of header names to filter.
• filter_query_parameters: List of query parameter names to filter.
• filter_post_data_parameters: List of POST data parameter names to filter.

Advanced Filtering: Instead of a simple list of strings, you can pass a list of (key, value) tuples where value can be:

• A new value to replace the original.
• None to remove the key/value pair.
• A callable that returns a new value or None.