Agent skill

pytest-recording

Work with pytest-recording (VCR.py) for recording and replaying HTTP interactions in tests. Use when writing VCR tests, managing cassettes, configuring VCR options, filtering sensitive data, or debugging recorded HTTP responses.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/testing/pytest-recording-bossjones-logging-lab

SKILL.md

pytest-recording (VCR.py) Testing

Overview

pytest-recording wraps VCR.py to record HTTP interactions as YAML cassettes, enabling deterministic tests without live API calls.

Quick Reference

Running Tests

bash
# Run all tests (uses existing cassettes)
uv run pytest tests/

# Run a single test
uv run pytest tests/test_module.py::test_function

# Rewrite all cassettes with fresh responses
uv run pytest tests/ --vcr-record=rewrite

# Record only missing cassettes
uv run pytest tests/ --vcr-record=new_episodes

# Disable VCR (make live requests)
uv run pytest tests/ --disable-recording

Recording Modes

Mode Flag Behavior
none --vcr-record=none Only replay, fail if no cassette
once (default) Record if no cassette exists
new_episodes --vcr-record=new_episodes Record new requests, keep existing
all --vcr-record=all Always record, overwrite existing
rewrite --vcr-record=rewrite Delete and re-record all cassettes

Writing VCR Tests

Basic test with VCR:

python
import pytest

@pytest.mark.vcr()
def test_api_call():
    response = my_api_function()
    assert response.status_code == 200

Custom cassette name:

python
@pytest.mark.vcr("custom_cassette_name.yaml")
def test_with_custom_cassette():
    pass

Multiple cassettes:

python
@pytest.mark.vcr("cassette1.yaml", "cassette2.yaml")
def test_with_multiple_cassettes():
    pass

VCR Configuration in conftest.py

The vcr_config fixture controls VCR behavior:

python
@pytest.fixture(scope="module")
def vcr_config():
    return {
        # Filter sensitive headers from recordings
        "filter_headers": ["authorization", "api-key", "x-api-key"],

        # Filter query parameters
        "filter_query_parameters": ["key", "api_key", "token"],

        # Match requests by these criteria
        "match_on": ["method", "scheme", "host", "port", "path", "query"],

        # Ignore certain hosts (don't record)
        "ignore_hosts": ["localhost", "127.0.0.1"],

        # Record mode
        "record_mode": "once",
    }

Filtering Sensitive Data

For LLM providers, filter authentication:

python
@pytest.fixture(scope="module")
def vcr_config():
    return {
        "filter_headers": [
            "authorization",      # OpenAI, Anthropic
            "api-key",            # Azure OpenAI
            "x-api-key",          # Anthropic
            "x-goog-api-key",     # Google AI
        ],
        "filter_query_parameters": ["key"],
    }

Response Processing

Use pytest_recording_configure for advanced processing:

python
def pytest_recording_configure(config, vcr):
    vcr.serializer = "yaml"
    vcr.decode_compressed_response = True

    # Sanitize response headers
    def sanitize_response(response):
        response['headers']['Set-Cookie'] = 'REDACTED'
        return response

    vcr.before_record_response = sanitize_response

Cassette Location

Cassettes are stored in tests/cassettes/ by default, organized by test module:

tests/
├── cassettes/
│   └── test_module/
│       └── test_function.yaml
└── test_module.py

Debugging

Cassette Not Found

If tests fail with "Can't find cassette":

  1. Run with --vcr-record=once to create missing cassettes
  2. Check cassette path matches test location
  3. Verify cassette file exists and is valid YAML

Request Mismatch

If VCR can't match requests:

  1. Check match_on criteria in vcr_config
  2. Compare request details in cassette vs actual request
  3. Use --vcr-record=new_episodes to add missing interactions

Stale Cassettes

When API responses change:

  1. Delete specific cassette file and re-run test
  2. Or use --vcr-record=rewrite to refresh all cassettes

View Cassette Contents

bash
# View a cassette file
cat tests/cassettes/test_module/test_function.yaml

# Search for specific content in cassettes
grep -r "error" tests/cassettes/

Adding New LLM Providers

When adding a new provider:

  1. Identify authentication headers (check provider docs)
  2. Add headers to filter_headers in vcr_config
  3. Add any query param auth to filter_query_parameters
  4. Test with --vcr-record=once to create cassettes
  5. Verify cassettes don't contain secrets

Common provider authentication:

Provider Headers to Filter
OpenAI authorization
Anthropic x-api-key, authorization
Azure OpenAI api-key
Google AI x-goog-api-key
Cohere authorization

Best Practices

  1. Never commit secrets: Always filter auth headers/params
  2. Use descriptive test names: Cassette names derive from test names
  3. Keep cassettes small: Mock only what you need to test
  4. Review cassettes in PRs: Check for sensitive data leaks
  5. Regenerate periodically: API responses may change over time
  6. Use scope appropriately: scope="module" for shared fixtures

Didn't find tool you were looking for?

Be as detailed as possible for better results