VCR.py

VCR.py automatically records the HTTP interactions your test suite makes and replays them on subsequent runs. The first time a test runs, VCR.py captures every outbound request and its response into a ‘cassette’ file; on later runs it serves those recorded responses instead of hitting the network, so tests become fast, deterministic, and independent of external services.

Inspired by Ruby’s VCR, it patches popular Python HTTP stacks — urllib3, requests, httpx, aiohttp, tornado, and more — transparently, so you usually only need to wrap a test in a decorator or context manager. Configurable request matching, record modes, and sensitive-data filtering give fine-grained control over what gets recorded and replayed.

What You Get

• Automatic recording of HTTP interactions into reusable cassette files
• Transparent patching of urllib3, requests, httpx, aiohttp, tornado, and more
• Configurable record modes (once, new_episodes, none, all)
• Custom request matchers on method, URI, body, headers, and query
• Filters to scrub secrets like auth headers and query parameters from cassettes

Common Use Cases

• Making tests that call external APIs fast and deterministic
• Running a test suite offline without depending on live third-party services
• Preventing flaky tests caused by network variability or rate limits
• Scrubbing credentials from recorded fixtures before committing them

Under The Hood

Architecture — The vcr package centers on cassette.py (the Cassette that stores and matches interactions), config.py (the VCR object and use_cassette entry point), and patch.py (which monkey-patches the underlying HTTP libraries’ connection classes). request.py models a normalized request, matchers.py implements pluggable matching strategies, filters.py scrubs sensitive data, and persisters/ plus serializers/ handle reading and writing cassette files. stubs/ contains the patched connection implementations per library.

Tech Stack — Pure Python distributed under MIT, depending only on PyYAML for cassette serialization and wrapt for robust monkey-patching. Optional test extras integrate with aiohttp, requests, httpx, tornado, urllib3, and boto3, reflecting the HTTP stacks it can intercept.

Code Quality — The repository has a large tests/ suite covering each supported HTTP library, unit and integration tests via httpbin, and Sphinx documentation. The design cleanly separates matching, filtering, serialization, and persistence, making the many-library support tractable and well-tested.

API Design — The common path is a single decorator or context manager, vcr.use_cassette(‘name.yaml’), with sensible defaults that require no other setup. More advanced needs — custom matchers, record modes, header filtering — are opt-in keyword arguments on a reusable VCR instance, keeping simple cases simple while allowing precise control.