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()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(): MockCallHistoryLog<MockCallHistoryLog>Returns every recorded MockCallHistoryLog as an array.
mockAgent.getCallHistory()?.calls()mockCallHistory.firstCall(): MockCallHistoryLog | undefined<MockCallHistoryLog>
|
<undefined>undefined
when no request has been recorded.Returns the first recorded MockCallHistoryLog.
mockAgent.getCallHistory()?.firstCall()mockCallHistory.lastCall(): MockCallHistoryLog | undefined<MockCallHistoryLog>
|
<undefined>undefined
when no request has been recorded.Returns the last recorded MockCallHistoryLog.
mockAgent.getCallHistory()?.lastCall()mockCallHistory.nthCall(position): MockCallHistoryLog | undefined<number><MockCallHistoryLog>
|
<undefined>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 logmockCallHistory.filterCalls(criteria, options?): MockCallHistoryLog<Function>
|
<RegExp>
|
<Object><MockCallHistoryLog>'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): MockCallHistoryLog<string>
|
<RegExp>
|
<null>
|
<undefined><MockCallHistoryLog>criteria
.Filters the recorded logs by request protocol.
mockAgent.getCallHistory()?.filterCallsByProtocol(/https/)
mockAgent.getCallHistory()?.filterCallsByProtocol('https:')mockCallHistory.filterCallsByHost(criteria): MockCallHistoryLog<string>
|
<RegExp>
|
<null>
|
<undefined><MockCallHistoryLog>criteria
.Filters the recorded logs by request host.
mockAgent.getCallHistory()?.filterCallsByHost(/localhost/)
mockAgent.getCallHistory()?.filterCallsByHost('localhost:3000')mockCallHistory.filterCallsByPort(criteria): MockCallHistoryLog<string>
|
<RegExp>
|
<null>
|
<undefined><MockCallHistoryLog>criteria
.Filters the recorded logs by request port.
mockAgent.getCallHistory()?.filterCallsByPort(/3000/)
mockAgent.getCallHistory()?.filterCallsByPort('3000')
mockAgent.getCallHistory()?.filterCallsByPort('')mockCallHistory.filterCallsByOrigin(criteria): MockCallHistoryLog<string>
|
<RegExp>
|
<null>
|
<undefined><MockCallHistoryLog>criteria
.Filters the recorded logs by request origin.
mockAgent.getCallHistory()?.filterCallsByOrigin(/http:\/\/localhost:3000/)
mockAgent.getCallHistory()?.filterCallsByOrigin('http://localhost:3000')mockCallHistory.filterCallsByPath(criteria): MockCallHistoryLog<string>
|
<RegExp>
|
<null>
|
<undefined><MockCallHistoryLog>criteria
.Filters the recorded logs by request path.
mockAgent.getCallHistory()?.filterCallsByPath(/api\/v1\/graphql/)
mockAgent.getCallHistory()?.filterCallsByPath('/api/v1/graphql')mockCallHistory.filterCallsByHash(criteria): MockCallHistoryLog<string>
|
<RegExp>
|
<null>
|
<undefined><MockCallHistoryLog>criteria
.Filters the recorded logs by request hash.
mockAgent.getCallHistory()?.filterCallsByHash(/hash/)
mockAgent.getCallHistory()?.filterCallsByHash('#hash')mockCallHistory.filterCallsByFullUrl(criteria): MockCallHistoryLog<string>
|
<RegExp>
|
<null>
|
<undefined><MockCallHistoryLog>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): MockCallHistoryLog<string>
|
<RegExp>
|
<null>
|
<undefined><MockCallHistoryLog>criteria
.Filters the recorded logs by request method.
mockAgent.getCallHistory()?.filterCallsByMethod(/POST/)
mockAgent.getCallHistory()?.filterCallsByMethod('POST')mockCallHistory.clear(): undefined<undefined>Removes every recorded MockCallHistoryLog. This is performed
automatically when mockAgent.close() is called.
mockAgent.clearCallHistory()
// Equivalent to:
mockAgent.getCallHistory()?.clear()mockCallHistory[Symbol.iterator](): Generator<Generator>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]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. nullkeeps a log only when the field is strictly equal tonull.undefinedkeeps a log only when the field is strictly equal toundefined.- A
<RegExp>keeps a log only when the expression matches the field.
Any other value throws an InvalidArgumentError.