vcr-test

library1.4.0jsnpmunverified

vcr-test is a testing utility that records and replays HTTP interactions, enabling fast, deterministic, and accurate tests by eliminating reliance on live external APIs. It intercepts HTTP traffic from any client (`fetch`, `axios`, `got`, etc.) using `@mswjs/interceptors` and stores request/response pairs in YAML "cassette" files. The current stable version is 1.4.0. It provides flexible recording modes (once, none, update, all) and extensibility for request masking, pass-through, and custom matching. Its key differentiator is its framework-agnostic nature and support for modern JavaScript features like `await using`, while also offering a callback API for older environments. While no explicit release cadence is stated, the project appears actively maintained on GitHub.

testing http-networking

npm install vcr-test

github ↗package ↗

INSTALL

IMPORT

SIG · VCR-TEST

vcr-test

testingjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VCR

✓ import { VCR } from 'vcr-test'

✗ const VCR = require('vcr-test').VCR

Main class for managing HTTP recording and playback. Primarily designed for ESM usage.

FileStorage

✓ import { FileStorage } from 'vcr-test'

✗ const FileStorage = require('vcr-test').FileStorage

Default storage mechanism for cassettes, typically used when instantiating VCR.

RecordMode

✓ import { RecordMode } from 'vcr-test'

✗ const RecordMode = require('vcr-test').RecordMode

Enum for controlling VCR's recording behavior (e.g., `RecordMode.update`).

DefaultRequestMatcher

✓ import { DefaultRequestMatcher } from 'vcr-test'

✗ import DefaultRequestMatcher from 'vcr-test/DefaultRequestMatcher'

Class for configuring how incoming requests are matched against recorded interactions. Not a default export.

Demonstrates recording and replaying an HTTP interaction using `VCR` and `FileStorage` with the modern `await using` syntax. It shows how to initialize VCR, wrap an API call with `useCassette`, and assert the replayed result.

import { join } from 'node:path'; import { VCR, FileStorage } from 'vcr-test'; // This would be your actual API client, e.g., using fetch or axios const api = { async myAwesomeApiCall() { const response = await fetch('https://httpbin.org/post', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'john' }) }); return response.json(); } }; describe('some suite', () => { const cassettesPath = join(process.cwd(), '__cassettes__'); const vcr = new VCR(new FileStorage(cassettesPath)); it('should record and replay an API call using await using', async () => { // Ensure the cassette directory exists and is clean for testing // For real usage, you'd manage this outside the test. await using _cassette = await vcr.useCassette('my_test_cassette'); const result = await api.myAwesomeApiCall(); expect(result).toBeDefined(); expect(result.data).toBe('{"name":"john"}'); expect(result.headers['Content-Type']).toContain('application/json'); }, 10000); // Increase timeout for initial recording });

vcr-test --version

Debug

Known issues

breakingThe `await using` syntax for cassette management requires Node.js 22+ and TypeScript 5.2+. Using `vcr-test` with older versions of Node.js or TypeScript will result in syntax errors or runtime issues if this pattern is adopted.

fix

For older environments, use the callback-based API: `await vcr.useCassette('cassette_name', async () => { /* test code */ });`.

affects: <=1.x.x

gotchaWhen manually editing recorded YAML cassette files, especially modifying response bodies, ensure that the `content-length` header in the `response.headers` section is updated to accurately reflect the new body's length. Mismatched `content-length` can lead to unexpected client behavior or parsing issues.

fix

Recalculate the byte length of the modified response body and update the `content-length` header accordingly, or re-record the cassette to automatically generate correct headers.

affects: >=1.0.0

gotchaThe `VCR_MODE` environment variable takes precedence over any programmatically set `vcr.mode` property. This can lead to unexpected recording behavior if tests are run in an environment where `VCR_MODE` is set (e.g., CI/CD) and overrides local settings.

fix

Be aware of `VCR_MODE` in deployment environments. To ensure consistent behavior, explicitly unset `VCR_MODE` if you intend to use programmatic mode settings, or rely solely on the environment variable for mode control in pipelines.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cassette 'cassette_name' not found and mode is 'none'.

The VCR instance's `mode` is set to `RecordMode.none` (or `VCR_MODE=none`), and the specified cassette file does not exist.

fix

Change the `vcr.mode` to `RecordMode.once` (default), `RecordMode.update`, or `RecordMode.all` to allow recording the cassette, or ensure the cassette exists before running the test in `none` mode.

TypeError: Invalid value for 'headers': 'content-length' should be a number.

This error can occur if a manually edited cassette has an invalid or non-numeric value for the `content-length` header in a response.

fix

Open the YAML cassette file and ensure the `content-length` header value for the affected interaction is an integer representing the byte length of the response body, or delete the cassette and re-record it.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/epignosisx/vcr-test ↗

packagehttps://www.npmjs.com/package/vcr-test ↗