SnapshotAgent

SnapshotAgent records real HTTP responses and replays them on later requests, allowing tests to run against deterministic, captured data instead of a live network. It extends MockAgent, so it can be installed with setGlobalDispatcher() or passed explicitly through the dispatcher option, and it works with every undici API (fetch, request, stream, pipeline, and so on).

A SnapshotAgent operates in one of three modes. In 'record' mode it performs real requests and writes the responses to a snapshot file. In 'playback' mode it serves responses from the snapshot file without touching the network. In 'update' mode it replays existing snapshots and records any request that has no matching snapshot.

import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'

const agent = new SnapshotAgent({
  mode: 'record',
  snapshotPath: './snapshots/api.json'
})
setGlobalDispatcher(agent)

const response = await fetch('https://api.example.com/users')
const users = await response.json()

await agent.close()

Constructing a SnapshotAgent emits an ExperimentalWarning once per process.

class SnapshotAgent extends MockAgent

The captured interactions are managed by an internal SnapshotRecorder, which is accessible through agent.getRecorder(). Because SnapshotAgent extends MockAgent, all MockAgent and Dispatcher methods and events are also available.

new SnapshotAgent(options?): void

Creates a new SnapshotAgent. Throws an InvalidArgumentError when mode is 'playback' or 'update' and snapshotPath is not provided, and throws an InvalidArgumentError when mode is not one of the supported values.

When mode is 'playback' or 'update' and snapshotPath is set, snapshots are loaded from the file automatically; a missing file is ignored until the first request requires it.

import { SnapshotAgent, setGlobalDispatcher } from 'undici'

const agent = new SnapshotAgent({
  mode: 'playback',
  snapshotPath: './snapshots/api.json'
})
setGlobalDispatcher(agent)

The mode controls how requests are handled:

• 'record' performs the real request and stores the response.

  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
  
  const agent = new SnapshotAgent({
    mode: 'record',
    snapshotPath: './snapshots/api.json'
  })
  setGlobalDispatcher(agent)
  
  await fetch('https://api.example.com/users')
  await agent.saveSnapshots()

  JavaScriptCopy to clipboard

• 'playback' serves the recorded response without any network access. A request with no matching snapshot rejects with an UndiciError whose message begins with No snapshot found.

  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
  
  const agent = new SnapshotAgent({
    mode: 'playback',
    snapshotPath: './snapshots/api.json'
  })
  setGlobalDispatcher(agent)
  
  const response = await fetch('https://api.example.com/users')

  JavaScriptCopy to clipboard

• 'update' replays an existing snapshot when one is found and otherwise records the request like 'record' mode.

  import { SnapshotAgent, setGlobalDispatcher, fetch } from 'undici'
  
  const agent = new SnapshotAgent({
    mode: 'update',
    snapshotPath: './snapshots/api.json'
  })
  setGlobalDispatcher(agent)
  
  await fetch('https://api.example.com/new-endpoint')

  JavaScriptCopy to clipboard

agent.loadSnapshots(filePath?): Promise<void>

Loads snapshots from disk into memory. In 'playback' mode this also installs the corresponding MockAgent interceptors so that subsequent requests are matched against the loaded snapshots.

await agent.loadSnapshots('./snapshots/api.json')

agent.saveSnapshots(filePath?): Promise<void>

Writes all recorded snapshots to disk.

await agent.saveSnapshots('./snapshots/api.json')

agent.getRecorder(): SnapshotRecorder

Returns the underlying SnapshotRecorder. The recorder exposes lower-level operations over the captured data, including record(), findSnapshot(), getSnapshots(), size(), and clear(). The recorder is an internal type returned for inspection; it is not exported from the package root.

const recorder = agent.getRecorder()
console.log(`Recorded ${recorder.size()} interactions`)

agent.getMode(): string

Returns the mode the agent was constructed with.

agent.clearSnapshots(): undefined

Removes all snapshots from memory.

agent.clearSnapshots()

agent.resetCallCounts(): undefined

Resets the call count of every snapshot to zero. Useful between tests when the same agent is reused, since matching a snapshot in 'playback' mode increments its call count.

agent.resetCallCounts()

agent.deleteSnapshot(requestOpts): boolean

Deletes a single snapshot that matches the given request options.

const deleted = agent.deleteSnapshot({
  method: 'GET',
  origin: 'https://api.example.com',
  path: '/users'
})

agent.getSnapshotInfo(requestOpts): Object | null

Returns metadata about a snapshot without returning the response payload.

const info = agent.getSnapshotInfo({
  method: 'GET',
  origin: 'https://api.example.com',
  path: '/users'
})

agent.replaceSnapshots(snapshotData): undefined

Replaces all in-memory snapshots with the provided data.

const recorder = agent.getRecorder()
const snapshots = recorder.getSnapshots()

agent.replaceSnapshots(snapshots.map((snapshot, index) => ({
  hash: `snapshot-${index}`,
  snapshot
})))

agent.close(): Promise<void>

Closes the agent and releases its resources. In 'record' and 'update' modes the recorder is flushed to disk first. In 'playback' mode nothing is written, because matching a snapshot mutates its call count and saving would needlessly rewrite the snapshot file. The real Agent, when one was created, and the underlying MockAgent are closed as well.

await agent.close()