The SnapshotAgent provides a powerful way to record and replay HTTP requests for testing purposes. It extends MockAgent to enable automatic snapshot testing, eliminating the need to manually define mock responses.
new SnapshotAgent([options])\nObject (optional)\nString - The snapshot mode: 'record', 'playback', or 'update'. Default: 'record'String - Path to the snapshot file for loading/savingNumber - Maximum number of snapshots to keep in memory. Default: InfinityBoolean - Whether to automatically save snapshots to disk. Default: falseNumber - Interval in milliseconds for auto-flush. Default: 30000Array<String> - Specific headers to include in request matching. Default: all headersArray<String> - Headers to ignore during request matchingArray<String> - Headers to exclude from snapshots (for security)Boolean - Whether to include request body in matching. Default: trueFunction - Optional function (body) => string to normalize the request body before matching (e.g. strip volatile fields like timestamps). Only used when matchBody is true.Boolean - Whether to include query parameters in matching. Default: trueFunction - Optional function (query: URLSearchParams) => string to normalize query parameters before matching (e.g. strip volatile params like cache-busters). Only used when matchQuery is true.Boolean - Whether header matching is case-sensitive. Default: falseFunction - Callback to determine if a request should be recordedFunction - Callback to determine if a request should be played backArray - URL patterns (strings or RegExp) to exclude from recording/playbackMockAgent are supportedMakes real HTTP requests and saves the responses to snapshots.
\nimport { SnapshotAgent, setGlobalDispatcher } from 'undici'\n\nconst agent = new SnapshotAgent({ \n mode: 'record',\n snapshotPath: './test/snapshots/api-calls.json'\n})\nsetGlobalDispatcher(agent)\n\n// Makes real requests and records them\nconst response = await fetch('https://api.example.com/users')\nconst users = await response.json()\n\n// Save recorded snapshots\nawait agent.saveSnapshots()\nReplays recorded responses without making real HTTP requests.
\nimport { SnapshotAgent, setGlobalDispatcher } from 'undici'\n\nconst agent = new SnapshotAgent({\n mode: 'playback',\n snapshotPath: './test/snapshots/api-calls.json'\n})\nsetGlobalDispatcher(agent)\n\n// Uses recorded response instead of real request\nconst response = await fetch('https://api.example.com/users')\nUses existing snapshots when available, but records new ones for missing requests.
\nimport { SnapshotAgent, setGlobalDispatcher } from 'undici'\n\nconst agent = new SnapshotAgent({\n mode: 'update',\n snapshotPath: './test/snapshots/api-calls.json'\n})\nsetGlobalDispatcher(agent)\n\n// Uses snapshot if exists, otherwise makes real request and records it\nconst response = await fetch('https://api.example.com/new-endpoint')\nSaves all recorded snapshots to a file.
", "modules": [ { "textRaw": "Parameters", "name": "parameters", "type": "module", "desc": "String (optional) - Path to save snapshots. Uses constructor snapshotPath if not provided.Promise<void>
await agent.saveSnapshots('./custom-snapshots.json')\nBy default (matchBody: true) the full request body string is included in the snapshot key. Set it to false to ignore the body entirely, or use normalizeBody to strip volatile fields (like timestamps) before matching:
const agent = new SnapshotAgent({\n mode: 'playback',\n snapshotPath: './snapshots.json',\n\n // Match on everything except the timestamp field\n normalizeBody: (body) => {\n if (!body) return ''\n const parsed = JSON.parse(String(body))\n delete parsed.timestamp\n return JSON.stringify(parsed)\n }\n})\nnormalizeBody receives the raw body (string | Buffer | null | undefined) and must return a string. It runs at both record and playback time so the hash is consistent. Two requests match the same snapshot whenever their normalized strings are identical.
Control which headers are used for request matching and what gets stored in snapshots:
\nconst agent = new SnapshotAgent({\n mode: 'record',\n snapshotPath: './snapshots.json',\n \n // Only match these specific headers\n matchHeaders: ['content-type', 'accept'],\n \n // Ignore these headers during matching (but still store them)\n ignoreHeaders: ['user-agent', 'date'],\n \n // Exclude sensitive headers from snapshots entirely\n excludeHeaders: ['authorization', 'x-api-key', 'cookie']\n})\nUse callback functions to determine what gets recorded or played back:
\nconst agent = new SnapshotAgent({\n mode: 'record',\n snapshotPath: './snapshots.json',\n \n // Only record GET requests to specific endpoints\n shouldRecord: (requestOpts) => {\n const url = new URL(requestOpts.path, requestOpts.origin)\n return requestOpts.method === 'GET' && url.pathname.startsWith('/api/v1/')\n },\n \n // Skip authentication endpoints during playback\n shouldPlayback: (requestOpts) => {\n const url = new URL(requestOpts.path, requestOpts.origin)\n return !url.pathname.includes('/auth/')\n }\n})\nExclude specific URLs from recording/playback using patterns:
\nconst agent = new SnapshotAgent({\n mode: 'record',\n snapshotPath: './snapshots.json',\n \n excludeUrls: [\n 'https://analytics.example.com', // String match\n /\\/api\\/v\\d+\\/health/, // Regex pattern\n 'telemetry' // Substring match\n ]\n})\nConfigure automatic memory and disk management:
\nconst agent = new SnapshotAgent({\n mode: 'record',\n snapshotPath: './snapshots.json',\n \n // Keep only 1000 snapshots in memory\n maxSnapshots: 1000,\n \n // Automatically save to disk every 30 seconds\n autoFlush: true,\n flushInterval: 30000\n})\nHandle multiple responses for the same request (similar to nock):
\n// In record mode, multiple identical requests get recorded as separate responses\nconst agent = new SnapshotAgent({ mode: 'record', snapshotPath: './sequential.json' })\n\n// First call returns response A\nawait fetch('https://api.example.com/random')\n\n// Second call returns response B \nawait fetch('https://api.example.com/random')\n\nawait agent.saveSnapshots()\n\n// In playback mode, calls return responses in sequence\nconst playbackAgent = new SnapshotAgent({ mode: 'playback', snapshotPath: './sequential.json' })\n\n// Returns response A\nconst first = await fetch('https://api.example.com/random')\n\n// Returns response B\nconst second = await fetch('https://api.example.com/random')\n\n// Third call repeats the last response (B)\nconst third = await fetch('https://api.example.com/random')\n// Load existing snapshots\nawait agent.loadSnapshots('./old-snapshots.json')\n\n// Get snapshot data\nconst recorder = agent.getRecorder()\nconst snapshots = recorder.getSnapshots()\n\n// Modify or filter snapshots\nconst filteredSnapshots = snapshots.filter(s => \n !s.request.url.includes('deprecated')\n)\n\n// Replace all snapshots\nagent.replaceSnapshots(filteredSnapshots.map((snapshot, index) => ({\n hash: `new-hash-${index}`,\n snapshot\n})))\n\n// Save updated snapshots\nawait agent.saveSnapshots('./updated-snapshots.json')\nLoads snapshots from a file.
", "modules": [ { "textRaw": "Parameters", "name": "parameters", "type": "module", "desc": "String (optional) - Path to load snapshots from. Uses constructor snapshotPath if not provided.Promise<void>
await agent.loadSnapshots('./existing-snapshots.json')\nGets the underlying SnapshotRecorder instance.
SnapshotRecorder
const recorder = agent.getRecorder()\nconsole.log(`Recorded ${recorder.size()} interactions`)\nGets the current snapshot mode.
", "modules": [ { "textRaw": "Returns", "name": "returns", "type": "module", "desc": "String - The current mode ('record', 'playback', or 'update')
Clears all recorded snapshots from memory.
\nagent.clearSnapshots()\n// Record mode\nconst agent = new SnapshotAgent({ mode: 'record', snapshotPath: './get-snapshots.json' })\nsetGlobalDispatcher(agent)\n\nconst response = await fetch('https://jsonplaceholder.typicode.com/posts/1')\nconst post = await response.json()\n\nawait agent.saveSnapshots()\n// Record mode\nconst agent = new SnapshotAgent({ mode: 'record', snapshotPath: './post-snapshots.json' })\nsetGlobalDispatcher(agent)\n\nconst response = await fetch('https://jsonplaceholder.typicode.com/posts', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ title: 'Test Post', body: 'Content' })\n})\n\nawait agent.saveSnapshots()\nSnapshotAgent works with all undici APIs, not just fetch:
\nimport { SnapshotAgent, request, setGlobalDispatcher } from 'undici'\n\nconst agent = new SnapshotAgent({ mode: 'record', snapshotPath: './request-snapshots.json' })\nsetGlobalDispatcher(agent)\n\nconst { statusCode, headers, body } = await request('https://api.example.com/data')\nconst data = await body.json()\n\nawait agent.saveSnapshots()\nimport { test } from 'node:test'\nimport { SnapshotAgent, setGlobalDispatcher, getGlobalDispatcher } from 'undici'\n\ntest('API integration test', async (t) => {\n const originalDispatcher = getGlobalDispatcher()\n \n const agent = new SnapshotAgent({\n mode: 'playback',\n snapshotPath: './test/snapshots/api-test.json'\n })\n setGlobalDispatcher(agent)\n \n t.after(() => setGlobalDispatcher(originalDispatcher))\n \n // This will use recorded data\n const response = await fetch('https://api.example.com/users')\n const users = await response.json()\n \n assert(Array.isArray(users))\n assert(users.length > 0)\n})\nconst mode = process.env.SNAPSHOT_MODE || 'playback'\n\nconst agent = new SnapshotAgent({\n mode,\n snapshotPath: './test/snapshots/integration.json'\n})\n\n// Run with: SNAPSHOT_MODE=record npm test (to record)\n// Run with: npm test (to playback)\nfunction createSnapshotAgent(testName, mode = 'playback') {\n return new SnapshotAgent({\n mode,\n snapshotPath: `./test/snapshots/${testName}.json`\n })\n}\n\ntest('user API test', async (t) => {\n const agent = createSnapshotAgent('user-api')\n setGlobalDispatcher(agent)\n \n // Test implementation...\n})\nSnapshots are stored as JSON with the following structure:
\n[\n {\n \"hash\": \"dGVzdC1oYXNo...\",\n \"snapshot\": {\n \"request\": {\n \"method\": \"GET\",\n \"url\": \"https://api.example.com/users\",\n \"headers\": {\n \"authorization\": \"Bearer token\"\n },\n \"body\": undefined\n },\n \"response\": {\n \"statusCode\": 200,\n \"headers\": {\n \"content-type\": \"application/json\"\n },\n \"body\": \"eyJkYXRhIjoidGVzdCJ9\", // base64 encoded\n \"trailers\": {}\n },\n \"timestamp\": \"2024-01-01T00:00:00.000Z\"\n }\n }\n]\nBy default, SnapshotAgent records all headers and request/response data. For production use, always exclude sensitive information:
\nconst agent = new SnapshotAgent({\n mode: 'record',\n snapshotPath: './snapshots.json',\n \n // Exclude sensitive headers from snapshots\n excludeHeaders: [\n 'authorization',\n 'x-api-key', \n 'cookie',\n 'set-cookie',\n 'x-auth-token',\n 'x-csrf-token'\n ],\n \n // Filter out requests with sensitive data\n shouldRecord: (requestOpts) => {\n const url = new URL(requestOpts.path, requestOpts.origin)\n \n // Don't record authentication endpoints\n if (url.pathname.includes('/auth/') || url.pathname.includes('/login')) {\n return false\n }\n \n // Don't record if request contains sensitive body data\n if (requestOpts.body && typeof requestOpts.body === 'string') {\n const body = requestOpts.body.toLowerCase()\n if (body.includes('password') || body.includes('secret')) {\n return false\n }\n }\n \n return true\n }\n})\nImportant: Snapshot files may contain sensitive data. Handle them securely:
\n.gitignore if they contain real API dataexcludeHeaders option for production snapshots# Exclude snapshots with real data\n/test/snapshots/production-*.json\n/test/snapshots/*-real-data.json\n\n# Include sanitized test snapshots\n!/test/snapshots/mock-*.json\ntry {\n const response = await fetch('https://api.example.com/nonexistent')\n} catch (error) {\n if (error.message.includes('No snapshot found')) {\n // Handle missing snapshot\n console.log('Snapshot not found for this request')\n }\n}\nconst agent = new SnapshotAgent({ mode: 'record', snapshotPath: './snapshots.json' })\n\ntry {\n const response = await fetch('https://nonexistent-api.example.com/data')\n} catch (error) {\n // Network errors are not recorded as snapshots\n console.log('Network error:', error.message)\n}\n// Use descriptive snapshot file names\nconst agent = new SnapshotAgent({\n mode: 'playback',\n snapshotPath: `./test/snapshots/${testSuiteName}-${testName}.json`\n})\nAdd snapshot files to version control to ensure consistent test behavior across environments:
\n# Include snapshots in version control\n!/test/snapshots/*.json\ntest('API test', async (t) => {\n const agent = new SnapshotAgent({\n mode: 'playback',\n snapshotPath: './test/snapshots/temp-test.json'\n })\n \n // Clean up after test\n t.after(() => {\n agent.clearSnapshots()\n })\n})\ntest('validate snapshot contents', async (t) => {\n const agent = new SnapshotAgent({\n mode: 'playback',\n snapshotPath: './test/snapshots/validation.json'\n })\n \n const recorder = agent.getRecorder()\n const snapshots = recorder.getSnapshots()\n \n // Validate snapshot structure\n assert(snapshots.length > 0, 'Should have recorded snapshots')\n assert(snapshots[0].request.url.startsWith('https://'), 'Should use HTTPS')\n})\nManual MockAgent:
\nconst mockAgent = new MockAgent()\nconst mockPool = mockAgent.get('https://api.example.com')\n\nmockPool.intercept({\n path: '/users',\n method: 'GET'\n}).reply(200, [\n { id: 1, name: 'User 1' },\n { id: 2, name: 'User 2' }\n])\nSnapshotAgent:
\n// Record once\nconst agent = new SnapshotAgent({ mode: 'record', snapshotPath: './snapshots.json' })\n// Real API call gets recorded automatically\n\n// Use in tests\nconst agent = new SnapshotAgent({ mode: 'playback', snapshotPath: './snapshots.json' })\n// Automatically replays recorded response\nSnapshotAgent provides similar functionality to nock but is specifically designed for undici:
\nrequest, stream, pipeline, etc.)