HTTP Interaction Recorder for Tests

Common errors

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

  cause 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.

  cause 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.

Warnings

• breaking The `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 */ });`.
• gotcha When 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.
• gotcha The `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.

Install

• npm install vcr-test npm
• yarn add vcr-test yarn
• pnpm add vcr-test pnpm

Imports

• VCR
  wrong:

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

  correct:

  import { VCR } from 'vcr-test'

  Main class for managing HTTP recording and playback. Primarily designed for ESM usage.
• FileStorage
  wrong:

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

  correct:

  import { FileStorage } from 'vcr-test'

  Default storage mechanism for cassettes, typically used when instantiating VCR.
• RecordMode
  wrong:

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

  correct:

  import { RecordMode } from 'vcr-test'

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

  import DefaultRequestMatcher from 'vcr-test/DefaultRequestMatcher'

  correct:

  import { DefaultRequestMatcher } from 'vcr-test'

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

Quickstart

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
});