Open-Source Testing · dnaeon

go-vcr

go-vcr is a Go testing library that records HTTP interactions during test runs and replays them in future runs, eliminating external API dependencies and making tests faster and deterministic. It provides hooks for sanitizing sensitive data before storage and supports custom request matching strategies.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/dnaeon/go-vcr

1.4k

GitHub stars

Forks

Primary language

BSD-2-Clause

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	dnaeon/go-vcr
Owner	dnaeon
Primary language	Go
License	BSD-2-Clause — OSI-approved
Stars	1.4k
Forks	80
Open issues	5
Latest release	v4.0.7 (2026-06-25)
Last updated	2026-06-25
Source	https://github.com/dnaeon/go-vcr

What go-vcr is

go-vcr wraps the Go HTTP client to intercept and record request/response pairs as YAML cassettes. It operates in record and replay modes, with extensibility via hooks (AfterCaptureHook, BeforeSaveHook, BeforeResponseReplayHook), custom matchers, and passthrough handlers for bypassing recording on specific requests.

Quickstart

Get the go-vcr source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/dnaeon/go-vcr.git2cd go-vcr3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Testing code that depends on external APIs

Record real API interactions once, then replay them in CI/CD and local environments to avoid rate limits, flaky networks, and API outages during test execution.

Deterministic integration tests

Guarantee consistent test results across environments and time by replaying fixed HTTP responses, eliminating non-determinism from external services.

Securing sensitive data in version control

Use hooks to redact API keys, tokens, and credentials before cassettes are stored, enabling safe commit of test fixtures to repositories.

Implementation considerations

Cassette files (YAML) must be committed to version control and kept in sync when APIs change; plan a process for cassette rotation and invalidation.
Use BeforeSaveHook to redact secrets before persistence; AfterCaptureHook modifies in-memory state and may affect subsequent test requests.
Custom matchers are essential for non-trivial request bodies (JSON payloads, form data); the default matcher handles method, URL, and simple matching.
Passthrough handlers allow specific requests (e.g., authentication flows) to bypass recording; use sparingly to avoid test flakiness.
v4.0.7 is the latest release; migrations between major versions may require cassette regeneration.

When to avoid it — and what to weigh

You need dynamic response validation — If tests require responses that change based on current timestamp, random values, or external state, replayed cassettes will not capture real-time variations.
You're testing real-time or streaming APIs — go-vcr is designed for request/response pairs; streaming, WebSocket, or event-driven protocols are not well-suited to cassette replay.
Your tests exercise multiple concurrent HTTP flows — Matching and replaying concurrent requests requires careful setup; simpler tools or genuine mocking may be cleaner for complex concurrency scenarios.
You need to test API error recovery without fixed responses — If tests must validate behavior against varied error conditions (timeouts, 5xx, rate limits), cassettes lock responses and limit scenario coverage.

License & commercial use

BSD-2-Clause license is a permissive open-source license allowing commercial use, modification, and distribution with minimal restrictions (retain license and copyright notice).

BSD-2-Clause permits commercial use without explicit permission. Ensure your own code and cassette data do not contain third-party IP; cassettes themselves may contain captured API responses subject to those APIs' terms of service.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Cassette files in YAML format store full HTTP request/response bodies including headers and payload; design cassette storage to protect against unauthorized access. Use BeforeSaveHook to redact credentials, tokens, and PII before committing cassettes. No built-in encryption; if cassettes contain sensitive data, apply file-level or repository-level access controls.

Alternatives to consider

httptest + http.Client mocking

Go standard library alternative; fully deterministic but requires manual request/response setup per test; lower maintenance overhead for simple cases.

govcr (fork/alternative VCR library)

Alternative VCR implementation; feature and API design may differ; consider if go-vcr's v4 API does not fit your workflow.

mock/stub HTTP clients (testify/mock, etc.)

Fine-grained control via standard mocking frameworks; avoids cassette file management but requires explicit response setup for each test case.

Software development agency

Build on go-vcr with DEV.co software developers

Integrate go-vcr into your test suite to eliminate external API dependencies and ensure repeatable, fast test runs. Our team can help design a cassette management strategy for your project.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

vcrpy php-vcr pytest-recording

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing API Development Application Development Talk to DEV.co

go-vcr FAQ

What happens if I change my code but the cassette is stale?

If the incoming request no longer matches the recorded request (method, URL, body), the recorder will fail the test or enter passthrough mode depending on configuration. Delete the cassette and re-run to record fresh data.

Can I use go-vcr in production?

No. go-vcr is a testing tool. In production, use standard HTTP clients; cassettes are intended for test isolation only.

How do I prevent API credentials from being stored in cassettes?

Use a BeforeSaveHook to redact Authorization headers, tokens, and sensitive response bodies before the cassette is written to disk.

Does go-vcr work with concurrent requests?

Yes, but request matching becomes critical. Set up a custom matcher that accurately identifies requests under concurrency to avoid mis-pairing recorded pairs.

Software development & web development with DEV.co

DEV.co is a software development agency delivering custom software development services to companies building on open source. Our software developers and web developers design, integrate, and ship production systems — spanning web development, APIs, AI, data, and cloud. If go-vcr is part of your open-source testing roadmap, our team can implement, customize, migrate, and maintain it.

Ready to accelerate your Go testing?

Integrate go-vcr into your test suite to eliminate external API dependencies and ensure repeatable, fast test runs. Our team can help design a cassette management strategy for your project.

Talk to DEV.co Schedule a Consultation