VCR.py
HTTP interaction recording and replay library for Python — record real HTTP requests to 'cassette' YAML files and replay them in tests without network access. VCR.py features: @vcr.use_cassette() decorator, vcr.VCR() for configuration, cassette recording (record_mode: none/new_episodes/all/once), request matching (URI, method, body, headers), response filtering for sensitive data (filter_headers, filter_query_parameters), support for requests, httpx, urllib3, aiohttp, and httplib backends, cassette inspection, and pytest plugin (pytest-recording). Eliminates network dependencies in tests — record once, replay forever.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
CRITICAL: Cassette YAML files record ALL request headers including Authorization/Cookie by default. Always configure filter_headers and filter_query_parameters before recording. Review cassette files for secrets before committing to git. Use .gitignore for cassettes containing non-filtered sensitive data.
⚡ Reliability
Best When
Testing code that makes real HTTP requests to external APIs — VCR.py records real responses once and replays them deterministically in CI, giving realistic test data without network flakiness or API costs.
Avoid When
You need to define mock responses manually (use responses/respx), test async-heavy code (use respx), or handle streaming responses.
Use Cases
- • Agent API test with cassette — @vcr.use_cassette('fixtures/github_api.yaml'); def test_get_repos(): repos = github_client.get_repos('myorg'); assert len(repos) > 0 — first run records real GitHub API response; subsequent runs replay from cassette; agent API integration tests run without network and with deterministic responses
- • Agent HTTP test with pytest-recording — @pytest.mark.vcr; def test_weather_api(): result = weather_client.get_current('London'); assert result['temp'] == 15.2 — pytest-recording plugin auto-names cassette from test function; agent test suite records all external HTTP during first run, replays deterministically in CI
- • Agent sensitive data filtering — with vcr.VCR(filter_headers=['Authorization', 'X-API-Key'], filter_query_parameters=['api_key']).use_cassette('cassette.yaml'): response = requests.get(url, headers={'Authorization': 'Bearer secret'}) — strips secrets from saved cassette; agent test suite records API interactions without committing credentials to git
- • Agent cassette inspection — with vcr.use_cassette('test.yaml', record_mode='none') as cass: make_api_call(); assert cass.play_count == 1; assert cass.requests[0].uri == expected_uri — assert cassette was fully consumed and correct endpoints called; agent test verifies HTTP calls made without checking network traffic directly
- • Agent new episodes mode — with vcr.use_cassette('cassette.yaml', record_mode='new_episodes'): result = api_client.call() — records new requests not in cassette, replays existing ones; agent tests for growing APIs add new interactions without re-recording existing ones; mix of real and cached responses
Not For
- • Mocking without recording — VCR.py is record/replay not manual mock definition; for explicit request mocking use responses or respx libraries
- • Async-first testing — VCR.py async support (aiohttp) is less mature than sync; for async HTTP testing use respx with httpx
- • Streaming responses — VCR.py records complete response bodies; for streaming API testing use manual mocking
Interface
Authentication
No auth — local test utility. Cassette files store recorded HTTP interactions as YAML.
Pricing
VCR.py is MIT licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Cassettes record in order by default — VCR.py matches requests by URI+method and replays in order; if test makes same request twice, cassette must have two entries; agent tests making multiple identical API calls need cassette with repeated entries or use record_mode='new_episodes'
- ⚠ Secrets in cassettes committed to git — cassette YAML files contain full request/response including auth headers by default; agent test suites MUST configure: vcr = VCR(filter_headers=['Authorization', 'Cookie'], filter_query_parameters=['api_key', 'token']) before recording; review cassettes before git commit
- ⚠ Record mode must be set explicitly for CI — @vcr.use_cassette('x.yaml') without record_mode defaults to 'none' if cassette exists; in CI without cassette, raises CannotSendRequest; agent CI pipeline must commit cassette files OR use record_mode='new_episodes' for auto-recording; never leave record_mode unset
- ⚠ Request matching is strict by default — cassette recorded with ?foo=bar&baz=qux won't match ?baz=qux&foo=bar (different order); agent code with dynamic query parameter ordering must customize: vcr.VCR(match_on=['method', 'host', 'path', 'body']) to ignore query string order
- ⚠ YAML cassettes are large for binary responses — cassette files for APIs returning binary/base64 data grow large quickly; agent test suites with image/file download tests should use cassette_library_dir per test module and exclude large cassettes from git with .gitignore
- ⚠ httpx requires explicit backend configuration — VCR.py works with requests by default; httpx requires: import vcr; my_vcr = vcr.VCR(); my_vcr.register_uri_matcher(httpx_matcher) or use pytest-recording which handles httpx automatically; agent tests using httpx without configuration silently bypass VCR cassette recording
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for VCR.py.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.