MockCallHistory

Stability: 2 - Stable

A MockCallHistory records the configuration of every request intercepted by a MockAgent for which call history is enabled. Each recorded request is stored as a MockCallHistoryLog, and the MockCallHistory exposes helpers to read and filter those logs in tests.

Instances are not created directly. Enable call history on a MockAgent and retrieve the history with mockAgent.getCallHistory():

import { MockAgent } from 'undici'

const mockAgent = new MockAgent({ enableCallHistory: true })
const callHistory = mockAgent.getCallHistory()

Call history can also be enabled after construction:

import { MockAgent } from 'undici'

const mockAgent = new MockAgent()
mockAgent.enableCallHistory()
const callHistory = mockAgent.getCallHistory()

Class: MockCallHistory

Tracks the configuration of intercepted requests as an ordered collection of MockCallHistoryLog entries.

A MockCallHistory is iterable. Use it with a for...of loop, the spread operator, or any constructor that accepts an iterable:

for (const log of mockAgent.getCallHistory()) {
  // ...
}

const logs = [...mockAgent.getCallHistory()]
const logSet = new Set(mockAgent.getCallHistory())

mockCallHistory.calls()

• Returns: {MockCallHistoryLog[]} All recorded logs, in the order the requests were intercepted.

Returns every recorded MockCallHistoryLog as an array.

mockAgent.getCallHistory()?.calls()

mockCallHistory.firstCall()

• Returns: {MockCallHistoryLog|undefined} The first recorded log, or undefined when no request has been recorded.

Returns the first recorded MockCallHistoryLog.

mockAgent.getCallHistory()?.firstCall()

mockCallHistory.lastCall()

• Returns: {MockCallHistoryLog|undefined} The last recorded log, or undefined when no request has been recorded.

Returns the last recorded MockCallHistoryLog.

mockAgent.getCallHistory()?.lastCall()

mockCallHistory.nthCall(position)

• position {number} The 1-based position of the log to return. Must be a positive integer.
• Returns: {MockCallHistoryLog|undefined} The log at position, or undefined when no log exists at that position.

Returns the MockCallHistoryLog at the given 1-based position. The index is 1-based for readability, so nthCall(1) is equivalent to firstCall().

Throws an InvalidArgumentError when position is not a number, not an integer, or not positive. Use firstCall() or lastCall() instead of passing a non-positive value.

mockAgent.getCallHistory()?.nthCall(3) // the third recorded log

mockCallHistory.filterCalls(criteria[, options])

• criteria {Function|RegExp|Object} The filter to apply.
  • When a {Function} is given, it is used as the predicate of Array.prototype.filter and receives each MockCallHistoryLog; logs for which it returns a truthy value are kept.
  • When a {RegExp} is given, a log is kept when the expression matches its mockCallHistoryLog.toString() representation.
  • When an {Object} is given, each property is a request field to filter on and each value is a filter parameter. An empty object returns every log.
    • protocol {string|RegExp|null|undefined} Filters by request protocol.
    • host {string|RegExp|null|undefined} Filters by request host.
    • port {string|RegExp|null|undefined} Filters by request port.
    • origin {string|RegExp|null|undefined} Filters by request origin.
    • path {string|RegExp|null|undefined} Filters by request path.
    • hash {string|RegExp|null|undefined} Filters by request hash.
    • fullUrl {string|RegExp|null|undefined} Filters by request full URL.
    • method {string|RegExp|null|undefined} Filters by request method.
• options {Object} Adjusts the filtering behavior. Only applied when criteria is an object. (optional)
  • operator {string} How to combine multiple object properties. 'OR' keeps a log matching any criterion; 'AND' keeps a log matching every criterion. The value is case-insensitive. Default: 'OR'.
• Returns: {MockCallHistoryLog[]} The matching logs. Duplicates produced by an 'OR' combination are removed.

A convenience method for applying one or several filters at once. It is a more expressive alternative to the per-field helpers below.

Throws an InvalidArgumentError when criteria is not a function, regular expression, or object, or when options.operator is neither 'OR' nor 'AND'.

const callHistory = mockAgent.getCallHistory()

callHistory?.filterCalls((log) =>
  log.hash === '#hash' && log.headers?.authorization !== undefined)

callHistory?.filterCalls(/"errors": "wrong body"/)

// Logs with a hash containing `my-hash` OR a path equal to `/endpoint`.
callHistory?.filterCalls({ hash: /my-hash/, path: '/endpoint' })

// Logs with a hash containing `my-hash` AND a path equal to `/endpoint`.
callHistory?.filterCalls(
  { hash: /my-hash/, path: '/endpoint' },
  { operator: 'AND' }
)

mockCallHistory.filterCallsByProtocol(criteria)

• criteria {string|RegExp|null|undefined} See filter parameter.
• Returns: {MockCallHistoryLog[]} The logs whose protocol matches criteria.

Filters the recorded logs by request protocol.

mockAgent.getCallHistory()?.filterCallsByProtocol(/https/)
mockAgent.getCallHistory()?.filterCallsByProtocol('https:')

mockCallHistory.filterCallsByHost(criteria)

• criteria {string|RegExp|null|undefined} See filter parameter.
• Returns: {MockCallHistoryLog[]} The logs whose host matches criteria.

Filters the recorded logs by request host.

mockAgent.getCallHistory()?.filterCallsByHost(/localhost/)
mockAgent.getCallHistory()?.filterCallsByHost('localhost:3000')

mockCallHistory.filterCallsByPort(criteria)

• criteria {string|RegExp|null|undefined} See filter parameter.
• Returns: {MockCallHistoryLog[]} The logs whose port matches criteria.

Filters the recorded logs by request port.

mockAgent.getCallHistory()?.filterCallsByPort(/3000/)
mockAgent.getCallHistory()?.filterCallsByPort('3000')
mockAgent.getCallHistory()?.filterCallsByPort('')

mockCallHistory.filterCallsByOrigin(criteria)

• criteria {string|RegExp|null|undefined} See filter parameter.
• Returns: {MockCallHistoryLog[]} The logs whose origin matches criteria.

Filters the recorded logs by request origin.

mockAgent.getCallHistory()?.filterCallsByOrigin(/http:\/\/localhost:3000/)
mockAgent.getCallHistory()?.filterCallsByOrigin('http://localhost:3000')

mockCallHistory.filterCallsByPath(criteria)

• criteria {string|RegExp|null|undefined} See filter parameter.
• Returns: {MockCallHistoryLog[]} The logs whose path matches criteria.

Filters the recorded logs by request path.

mockAgent.getCallHistory()?.filterCallsByPath(/api\/v1\/graphql/)
mockAgent.getCallHistory()?.filterCallsByPath('/api/v1/graphql')

mockCallHistory.filterCallsByHash(criteria)

• criteria {string|RegExp|null|undefined} See filter parameter.
• Returns: {MockCallHistoryLog[]} The logs whose hash matches criteria.

Filters the recorded logs by request hash.

mockAgent.getCallHistory()?.filterCallsByHash(/hash/)
mockAgent.getCallHistory()?.filterCallsByHash('#hash')

mockCallHistory.filterCallsByFullUrl(criteria)

• criteria {string|RegExp|null|undefined} See filter parameter.
• Returns: {MockCallHistoryLog[]} The logs whose full URL matches criteria.

Filters the recorded logs by request full URL. The full URL contains the protocol, host, port, path, query parameters, and hash.

mockAgent.getCallHistory()?.filterCallsByFullUrl(/https:\/\/localhost:3000\/\?query=value#hash/)
mockAgent.getCallHistory()?.filterCallsByFullUrl('https://localhost:3000/?query=value#hash')

mockCallHistory.filterCallsByMethod(criteria)

• criteria {string|RegExp|null|undefined} See filter parameter.
• Returns: {MockCallHistoryLog[]} The logs whose method matches criteria.

Filters the recorded logs by request method.

mockAgent.getCallHistory()?.filterCallsByMethod(/POST/)
mockAgent.getCallHistory()?.filterCallsByMethod('POST')

mockCallHistory.clear()

• Returns: {undefined}

Removes every recorded MockCallHistoryLog. This is performed automatically when mockAgent.close() is called.

mockAgent.clearCallHistory()
// Equivalent to:
mockAgent.getCallHistory()?.clear()

mockCallHistory[Symbol.iterator]()

• Returns: {Generator} A generator yielding each recorded MockCallHistoryLog in order.

Makes a MockCallHistory iterable, yielding the same logs returned by calls(). This enables for...of iteration, the spread operator, and constructing other iterables from a history.

const callHistory = mockAgent.getCallHistory()

for (const log of callHistory) {
  console.log(log.method, log.fullUrl)
}

const logs = [...callHistory]

Filter parameter

The per-field filterCallsBy* helpers and the object form of filterCalls() accept a filter parameter that is matched against the corresponding field of each MockCallHistoryLog:

• A {string} keeps a log only when the field is strictly equal to the value.
• null keeps a log only when the field is strictly equal to null.
• undefined keeps a log only when the field is strictly equal to undefined.
• A {RegExp} keeps a log only when the expression matches the field.

Any other value throws an InvalidArgumentError.