A VCR alternative when the cassette needs to be a URL

Honest opening: VCR and vcrpy are healthy, maintained, excellent libraries — this is not a "the project is dead" page. Checked against the registries the week of writing (Sep 2026): Ruby's vcr gem is at 6.4.0 (released Dec 2025, back under a dual MIT license since 6.3.0) with over 160 million downloads; Python's vcrpy is at 8.3.0 (released Jul 2026). Record a real HTTP interaction into a YAML cassette once, replay it in every test run after: deterministic, offline, fast. The pattern earned its decade of popularity.

The reasons people search "vcr alternative" aren't neglect — they're structural, baked into the cassette-file-in-one-process model. We reproduced every one of them before writing this page (Ruby VCR 6.4.0 via webmock 3.26.4, vcrpy 8.3.0 with requests, Sep 2026 — every snippet below was actually run).

The structural gotchas, reproduced

Cassettes record your secrets verbatim — by default, in both libraries. We made one request with an Authorization header and an X-Api-Key, then read the cassette back. Both tokens were sitting in the YAML, in plaintext, ready to be committed (details below). The fixes — Ruby's filter_sensitive_data, vcrpy's filter_headers — are opt-in, per-header, and easy to forget once. A forgotten header in a pushed cassette means rotating keys.
The replay only exists inside one process. Inside an active vcrpy cassette context, a subprocess curl of the exact same URL sailed straight past the cassette to the live network (run shown below). Same for your browser, your Playwright/Cypress suite, a second service, a mobile app, a teammate's machine: the cassette is a monkey-patch on one process's HTTP stack, and nothing else can see it.
Stale cassettes replay yesterday's API forever, silently. The default record mode (once / :once) never re-records. When the real API adds a field, renames one, or changes an error shape, your tests keep passing against the old response — no warning, no staleness marker. Re-recording means deleting files and running with live credentials from a machine that has them.
Strict matching turns small changes into cryptic failures. With a cassette already on disk, a request whose query string merely differs (?limit=3 vs the recorded ?limit=2) raised vcrpy's CannotOverwriteExistingCassetteException; Ruby raised VCR::Errors::UnhandledHTTPRequestError for a new path. Both errors are famous enough to have their own search-suggestion entries. The knobs (match_on, record: :new_episodes) exist — they're also how cassettes quietly accumulate junk.
Cassettes live in git. Multi-hundred-line YAML blobs per test churn in every re-record, collide in merges, and bloat reviews. (Honesty: this is also a feature — reviewable diffs of what your dependencies return. It cuts both ways.)

The secrets run, verbatim

vcrpy 8.3.0, default configuration, one recorded request against our live demo API:

import vcr, requests, yaml

with vcr.use_cassette('cassette1.yaml'):
    requests.get('https://mockbird.mockbird.workers.dev/m/demo/products?limit=2',
                 headers={'Authorization': 'Bearer super-secret-token',
                          'X-Api-Key': 'sk-live-123'})

print(yaml.safe_load(open('cassette1.yaml'))['interactions'][0]['request']['headers'])
# → {'Authorization': ['Bearer super-secret-token'], 'X-Api-Key': ['sk-live-123'], ...}

Ruby VCR 6.4.0 behaved identically — File.read('rb_cassettes/demo.yml').include?('ruby-secret-token') printed true. Neither library redacts anything unless you configure it to.

And the escape-hatch proof: with the cassette active and its body hand-edited to TAMPERED-BY-EDITOR (so a replay is unmistakable), the in-process client got the tampered recording while a subprocess got the live API:

with vcr.use_cassette('cassette1.yaml', record_mode='none'):
    requests.get(URL).text          # → [{"id":1,"name":"TAMPERED-BY-EDITOR"}]
    subprocess.run(['curl','-s',URL])  # → live data. The cassette never existed for curl.

Record & replay at the URL level instead

Mockbird has the record-and-replay loop built in, but the "cassette" is a hosted route at a real URL — so curl, browsers, Playwright, mobile apps, other services, teammates and CI all replay the same recording. Point a project's proxy at the real API and switch recording on:

# 1. create a project (no signup)
curl -X POST https://mockbird.mockbird.workers.dev/api/projects \
  -H "content-type: application/json" -d '{"name":"recorded","blank":true}'
# → {"id":"<id>","adminKey":"<key>","baseUrl":".../m/<id>", ...}

# 2. proxy unmatched paths to the real API, and record what comes back
curl -X PUT https://mockbird.mockbird.workers.dev/api/projects/<id>/settings \
  -H "x-admin-key: <key>" -H "content-type: application/json" \
  -d '{"proxyBase":"https://dummyjson.com","proxyRecord":true}'

First request for a path forwards upstream and records the 2xx response; every request after that replays locally. The response headers tell you which happened — from our verification run against dummyjson.com:

$ curl -sD - https://mockbird.mockbird.workers.dev/m/<id>/products/1
x-mockbird-proxied: dummyjson.com
x-mockbird-recorded: 1        ← first hit: fetched upstream + recorded
{"id":1,"title":"Essence Mascara Lash Princess", ...}

$ curl -sD - https://mockbird.mockbird.workers.dev/m/<id>/products/1
(no x-mockbird-proxied header) ← second hit: replayed locally, byte-identical body

How this answers each gotcha above:

No secrets in git — there is no cassette file. Recorded stubs live in the project (delete them any time); your Authorization header is forwarded to the upstream during recording but never written into a repo artifact, and the request inspector stores auth headers redacted to their scheme.
Staleness is a visible, deliberate choice — recorded routes are listed with "recorded": true (GET /api/projects/<id>/routes, marked ⏺ in the dashboard). Re-recording one endpoint = delete that route and hit the URL again; no test-suite-wide re-record, no local credentials ceremony. You can also open a recorded body in the dashboard and edit it — hand-updating a stub is a click, not YAML surgery.
Every client replays it — the subprocess-curl escape can't happen, because the recording is the URL.
Matching is deliberately loose — method + path, query strings ignored (the first recorded response for a path answers all query variants). No CannotOverwriteExistingCassetteException class exists here. Honest cost: that's less precise than VCR's matchers — see the wins list below.
Failure drills on the recording — both of these ran against the recorded route above: ?mock_status=503 returned a 503, and ?mock_delay=2000/?mock_chaos=0.3/?mock_seq work the same. Replay yesterday's response or make yesterday's endpoint fail on demand — the drill cassettes can't run. Recipes: testing loading & error states.

Honest scope notes: recorded bodies are text-ish (JSON/XML/text) up to 16 KB, non-2xx responses proxy through without being saved, first recording wins, and the 20-routes/project limit applies. Full semantics: docs → record & replay.

Already have the traffic? Import a HAR

If "record" for you means a browser session, skip the proxy: use your app for a minute with DevTools open, Network → Export HAR, and POST the file — the JSON API responses the page actually received become hosted, stateful collections (bodies served verbatim, full CRUD/filtering/pagination on top):

curl -X POST https://mockbird.mockbird.workers.dev/api/projects/import --data-binary @myapp.har

Walkthrough: HAR file → live mock API.

Or import the cassettes you already have

The same endpoint accepts VCR and vcrpy cassettes directly — the YAML files sitting in your cassettes/ or fixtures/vcr_cassettes/ directory right now (http_interactions: / interactions:; the JSON serializers work too):

curl -X POST https://mockbird.mockbird.workers.dev/api/projects/import \
  --data-binary @spec/cassettes/checkout.yml
# → {"id":"abc123","kind":"cassette","baseUrl":"…/m/abc123","resources":[{"name":"products","records":24,…}]}

The 2xx JSON responses recorded in the cassette become hosted records, served verbatim — the data your suite already trusts, now behind a URL any process can hit. Two details that matter here specifically:

Headers are discarded. Only URLs and JSON bodies are read — the Authorization/X-Api-Key values both libraries recorded verbatim (see above) never enter the project, and the import warns you when credential headers were present in the file, so you know to rotate them if the cassette was ever pushed or shared.
Grouping matches the HAR import: endpoints cluster by URL path (/api/v2/users/42 → users), polling repeats dedupe by id, {"data":[…]} wrappers unwrap, base64-encoded bodies decode. Interactions that only captured a request body get an inferred schema with seeded data. Cassettes up to 8 MB. Docs →

Cassette-per-scenario, without the files

The other thing teams use cassette libraries for is fixtures: a known data state per test scenario. That's snapshots — save the project's entire dataset under a name (baseline, empty, edge-cases), restore it in beforeEach, or pin a GET to a named snapshot per request with the X-Mockbird-Snapshot header so parallel workers each see their own state. Full recipe: deterministic test data.

Or use both — they compose

Keep VCR/vcrpy for offline unit tests — in-process replay with zero latency is genuinely unbeatable there, and both libraries are well maintained.
Point everything cassettes can't reach at a Mockbird URL — browser E2E runs, staging frontends, mobile builds, a teammate's machine, CI against a deployed preview. One env var for the base URL.
No lock-in either direction: GET /m/<project>/db.json ejects the live dataset, and openapi.json / postman.json / types.ts / msw.js exports come free.

Honest comparison

	VCR (Ruby) / vcrpy (Python)	Mockbird
What it is	free OSS record/replay libraries	free hosted mock API service
Maintenance	active — VCR 6.4.0 (Dec 2025), vcrpy 8.3.0 (Jul 2026), verified	hosted, actively maintained
Recording lives	YAML/JSON cassette files in your repo	hosted routes (editable, deletable, listed via API)
Secrets by default	recorded verbatim into cassettes (verified both); filtering is opt-in	no repo artifact; inspector redacts auth headers to scheme
Reachable from	the one process the library patches	anything with HTTP: curl, browser, mobile, other services, CI, agents
Request matching	precise + configurable (method/URI/host/path/body/headers)	method + path only; query ignored (looser — by design)
Staleness	silent — `once` mode replays old responses forever	visible `recorded: true` flags; re-record per route by delete + re-hit
Error/latency drills on recordings	no — replay is verbatim	`?mock_status` / `?mock_delay` / `?mock_chaos` / `?mock_seq` on any recorded route
Stateful CRUD on recorded data	no	HAR-imported records become real collections with writes
Works offline	yes (replay mode)	no — it's a real network call
Latency	zero (in-process)	real network latency
Cost / caps	free forever, no caps	free (beta), 10,000 requests/project/day

Written by the Mockbird maker — bias disclosed. Where VCR and vcrpy genuinely win: offline, zero-latency replay with zero network flakiness; automatic capture of your real API with full headers and every interaction of a test, matched per-test with real precision; cassette diffs in code review; no request caps; and they mock any host with no per-service setup. If your tests are single-process and you've wired up secret filtering, they remain the right tool. When the recording needs to be a URL — for a browser, a subprocess, another language, a teammate, or CI against a deployed build — that's us. (License footnote for completeness: VCR 6.0–6.2 were Hippocratic-licensed only, which some legal teams flagged; since 6.3.0 it's dual-licensed MIT, so that objection is dated.)

⚡ No terminal handy? This link creates a live seeded e-commerce API in one click — no signup. Set proxyBase + proxyRecord in its dashboard settings and you're recording.

Full API reference in the docs. More guides: Polly.JS alternative · HAR file → mock API · nock alternative · MSW alternative · mock API for Ruby · mock API for Python · deterministic test data · testing loading & error states · free mock API tools compared. Create your API →