{"library":"socket-vcr-test","title":"Socket VCR Test","type":"library","description":"socket-vcr-test is a TypeScript-first library (current version 2.0.1) for recording and replaying HTTP interactions in your test suite, ensuring fast, deterministic, and accurate tests. It functions as a fork of `epignosisx/vcr-test`, aiming to provide enhanced features or maintenance. The library offers flexible recording modes (e.g., `once`, `none`, `update`, `all`) to control cassette generation and playback behavior. Key differentiators include built-in support for request masking to handle sensitive data, and a highly extensible request matching system that allows custom logic for comparing URLs, headers, and bodies. It primarily targets modern JavaScript and TypeScript environments for development testing workflows. It's a useful tool for isolating tests from external network dependencies and ensuring consistent test results without relying on live APIs.","language":"javascript","status":"active","last_verified":"Tue Apr 21","install":{"commands":["npm install socket-vcr-test"],"cli":null},"imports":["import { VCR } from 'socket-vcr-test';","import { FileStorage } from 'socket-vcr-test';","import { RecordMode } from 'socket-vcr-test';","import { DefaultRequestMatcher } from 'socket-vcr-test';"],"auth":{"required":false,"env_vars":[]},"links":{"homepage":null,"github":"https://github.com/SocketDev/vcr-test","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/socket-vcr-test","openapi_spec":null,"status_page":null,"smithery":null},"quickstart":{"code":"import { join } from 'node:path';\nimport { VCR, FileStorage, RecordMode } from 'socket-vcr-test';\nimport { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';\n\n// Mock an external API call for demonstration purposes\nconst mockApi = {\n  myAwesomeApiCall: async () => {\n    console.log('    Making a simulated API call...');\n    return new Promise(resolve => setTimeout(() => resolve({ data: 'hello from real API', timestamp: Date.now() }), 50));\n  }\n};\n\n// Basic mocks for a runnable 'test' context\nconst expect = (value: any) => ({\n  toBeDefined: () => {\n    if (value === undefined || value === null) throw new Error('Expected value to be defined');\n  },\n  toEqual: (expected: any) => {\n    if (JSON.stringify(value) !== JSON.stringify(expected)) throw new Error(`Expected ${JSON.stringify(value)} to equal ${JSON.stringify(expected)}`);\n  }\n});\nconst describe = (name: string, fn: () => void) => { console.log(`\\n-- Running Suite: ${name} --`); fn(); };\nconst it = (name: string, fn: () => Promise<void>) => {\n  console.log(`  Test: ${name}`);\n  fn().then(() => console.log(`  ✓ Passed: ${name}`)).catch(e => console.error(`  ✗ Failed: ${name}\\n`, e));\n};\n\n// Setup a dummy directory for cassettes\nconst CASSETTES_DIR = join(process.cwd(), '__quickstart_cassettes__');\nif (!existsSync(CASSETTES_DIR)) {\n  mkdirSync(CASSETTES_DIR, { recursive: true });\n} else {\n  // Clean up previous run's cassettes for a fresh start\n  rmSync(CASSETTES_DIR, { recursive: true, force: true });\n  mkdirSync(CASSETTES_DIR, { recursive: true });\n}\n\ndescribe('socket-vcr-test quickstart', () => {\n  it('should record and replay an API call using VCR', async () => {\n    const cassetteName = 'quickstart_api_call';\n    const cassettePath = join(CASSETTES_DIR, cassetteName + '.yml');\n\n    // 1. Initial run: Configure VCR to record (default mode is 'once')\n    let vcr = new VCR(new FileStorage(CASSETTES_DIR));\n    vcr.mode = RecordMode.once; // Explicitly set, though it's the default\n    console.log(`    First run (Recording mode: ${vcr.mode}): Cassette ${cassetteName}.yml should be created.`);\n\n    await vcr.useCassette(cassetteName, async () => {\n      const result = await mockApi.myAwesomeApiCall();\n      expect(result).toBeDefined();\n      expect((result as any).data).toEqual('hello from real API');\n    });\n    expect(existsSync(cassettePath)).toEqual(true);\n    console.log(`    Cassette '${cassetteName}.yml' now exists.`);\n\n    // 2. Second run: VCR should replay from the cassette\n    // Re-initialize VCR to clear any internal state from the previous run\n    vcr = new VCR(new FileStorage(CASSETTES_DIR));\n    vcr.mode = RecordMode.once; // Still 'once', but cassette exists\n    console.log(`\\n    Second run (Replay mode: ${vcr.mode}): Cassette ${cassetteName}.yml should be replayed.`);\n    \n    const startTime = Date.now();\n    await vcr.useCassette(cassetteName, async () => {\n      const result = await mockApi.myAwesomeApiCall();\n      expect(result).toBeDefined();\n      expect((result as any).data).toEqual('hello from real API');\n    });\n    const endTime = Date.now();\n    console.log(`    API call completed in ${endTime - startTime}ms (expected very fast replay).`);\n    \n    // Demonstrating `update` mode\n    vcr = new VCR(new FileStorage(CASSETTES_DIR));\n    vcr.mode = RecordMode.update;\n    console.log(`\\n    Third run (Update mode: ${vcr.mode}): Simulating change to trigger re-recording if needed.`);\n    await vcr.useCassette(cassetteName, async () => {\n      // Even if mockApi changes, 'update' would re-record or update existing entries\n      const result = await mockApi.myAwesomeApiCall();\n      expect(result).toBeDefined();\n    });\n  });\n});\n\n// To run this example: save as `quickstart.ts`, compile with `tsc quickstart.ts`, then `node quickstart.js`","lang":"typescript","description":"This quickstart demonstrates how to initialize `socket-vcr-test` with `FileStorage`, use `useCassette` to wrap an asynchronous API call, and verifies that the HTTP interactions are recorded and then replayed. It shows both recording (first run) and replaying (subsequent runs) behavior, as well as an example of `RecordMode.update`.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}