# 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. Use when this capability is needed.

- Skill: `tomevault-io/pytest-recording-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/pytest-recording-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/pytest-recording-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/pytest-recording-2

---


# 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

---
> Source: [bossjones/logging-lab](https://github.com/bossjones/logging-lab) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->