372 lines
10 KiB
Plaintext
372 lines
10 KiB
Plaintext
# MockCallHistory
|
|
|
|
<!--introduced_in=v7.5.0-->
|
|
<!--type=module-->
|
|
<!-- source_link=lib/mock/mock-call-history.js -->
|
|
|
|
> 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()`:
|
|
|
|
```mjs
|
|
import { MockAgent } from 'undici'
|
|
|
|
const mockAgent = new MockAgent({ enableCallHistory: true })
|
|
const callHistory = mockAgent.getCallHistory()
|
|
```
|
|
|
|
Call history can also be enabled after construction:
|
|
|
|
```mjs
|
|
import { MockAgent } from 'undici'
|
|
|
|
const mockAgent = new MockAgent()
|
|
mockAgent.enableCallHistory()
|
|
const callHistory = mockAgent.getCallHistory()
|
|
```
|
|
|
|
## Class: `MockCallHistory`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
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:
|
|
|
|
```mjs
|
|
for (const log of mockAgent.getCallHistory()) {
|
|
// ...
|
|
}
|
|
|
|
const logs = [...mockAgent.getCallHistory()]
|
|
const logSet = new Set(mockAgent.getCallHistory())
|
|
```
|
|
|
|
### `mockCallHistory.calls()`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* Returns: {MockCallHistoryLog[]} All recorded logs, in the order the requests
|
|
were intercepted.
|
|
|
|
Returns every recorded [`MockCallHistoryLog`][] as an array.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.calls()
|
|
```
|
|
|
|
### `mockCallHistory.firstCall()`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* Returns: {MockCallHistoryLog|undefined} The first recorded log, or `undefined`
|
|
when no request has been recorded.
|
|
|
|
Returns the first recorded [`MockCallHistoryLog`][].
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.firstCall()
|
|
```
|
|
|
|
### `mockCallHistory.lastCall()`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* Returns: {MockCallHistoryLog|undefined} The last recorded log, or `undefined`
|
|
when no request has been recorded.
|
|
|
|
Returns the last recorded [`MockCallHistoryLog`][].
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.lastCall()
|
|
```
|
|
|
|
### `mockCallHistory.nthCall(position)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `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.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.nthCall(3) // the third recorded log
|
|
```
|
|
|
|
### `mockCallHistory.filterCalls(criteria[, options])`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `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](#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'`.
|
|
|
|
```mjs
|
|
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)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `criteria` {string|RegExp|null|undefined} See
|
|
[filter parameter](#filter-parameter).
|
|
* Returns: {MockCallHistoryLog[]} The logs whose protocol matches `criteria`.
|
|
|
|
Filters the recorded logs by request protocol.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.filterCallsByProtocol(/https/)
|
|
mockAgent.getCallHistory()?.filterCallsByProtocol('https:')
|
|
```
|
|
|
|
### `mockCallHistory.filterCallsByHost(criteria)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `criteria` {string|RegExp|null|undefined} See
|
|
[filter parameter](#filter-parameter).
|
|
* Returns: {MockCallHistoryLog[]} The logs whose host matches `criteria`.
|
|
|
|
Filters the recorded logs by request host.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.filterCallsByHost(/localhost/)
|
|
mockAgent.getCallHistory()?.filterCallsByHost('localhost:3000')
|
|
```
|
|
|
|
### `mockCallHistory.filterCallsByPort(criteria)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `criteria` {string|RegExp|null|undefined} See
|
|
[filter parameter](#filter-parameter).
|
|
* Returns: {MockCallHistoryLog[]} The logs whose port matches `criteria`.
|
|
|
|
Filters the recorded logs by request port.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.filterCallsByPort(/3000/)
|
|
mockAgent.getCallHistory()?.filterCallsByPort('3000')
|
|
mockAgent.getCallHistory()?.filterCallsByPort('')
|
|
```
|
|
|
|
### `mockCallHistory.filterCallsByOrigin(criteria)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `criteria` {string|RegExp|null|undefined} See
|
|
[filter parameter](#filter-parameter).
|
|
* Returns: {MockCallHistoryLog[]} The logs whose origin matches `criteria`.
|
|
|
|
Filters the recorded logs by request origin.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.filterCallsByOrigin(/http:\/\/localhost:3000/)
|
|
mockAgent.getCallHistory()?.filterCallsByOrigin('http://localhost:3000')
|
|
```
|
|
|
|
### `mockCallHistory.filterCallsByPath(criteria)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `criteria` {string|RegExp|null|undefined} See
|
|
[filter parameter](#filter-parameter).
|
|
* Returns: {MockCallHistoryLog[]} The logs whose path matches `criteria`.
|
|
|
|
Filters the recorded logs by request path.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.filterCallsByPath(/api\/v1\/graphql/)
|
|
mockAgent.getCallHistory()?.filterCallsByPath('/api/v1/graphql')
|
|
```
|
|
|
|
### `mockCallHistory.filterCallsByHash(criteria)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `criteria` {string|RegExp|null|undefined} See
|
|
[filter parameter](#filter-parameter).
|
|
* Returns: {MockCallHistoryLog[]} The logs whose hash matches `criteria`.
|
|
|
|
Filters the recorded logs by request hash.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.filterCallsByHash(/hash/)
|
|
mockAgent.getCallHistory()?.filterCallsByHash('#hash')
|
|
```
|
|
|
|
### `mockCallHistory.filterCallsByFullUrl(criteria)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `criteria` {string|RegExp|null|undefined} See
|
|
[filter parameter](#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.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.filterCallsByFullUrl(/https:\/\/localhost:3000\/\?query=value#hash/)
|
|
mockAgent.getCallHistory()?.filterCallsByFullUrl('https://localhost:3000/?query=value#hash')
|
|
```
|
|
|
|
### `mockCallHistory.filterCallsByMethod(criteria)`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* `criteria` {string|RegExp|null|undefined} See
|
|
[filter parameter](#filter-parameter).
|
|
* Returns: {MockCallHistoryLog[]} The logs whose method matches `criteria`.
|
|
|
|
Filters the recorded logs by request method.
|
|
|
|
```mjs
|
|
mockAgent.getCallHistory()?.filterCallsByMethod(/POST/)
|
|
mockAgent.getCallHistory()?.filterCallsByMethod('POST')
|
|
```
|
|
|
|
### `mockCallHistory.clear()`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* Returns: {undefined}
|
|
|
|
Removes every recorded [`MockCallHistoryLog`][]. This is performed
|
|
automatically when `mockAgent.close()` is called.
|
|
|
|
```mjs
|
|
mockAgent.clearCallHistory()
|
|
// Equivalent to:
|
|
mockAgent.getCallHistory()?.clear()
|
|
```
|
|
|
|
### `mockCallHistory[Symbol.iterator]()`
|
|
|
|
<!-- YAML
|
|
added: v7.5.0
|
|
-->
|
|
|
|
* 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.
|
|
|
|
```mjs
|
|
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`][].
|
|
|
|
[`InvalidArgumentError`]: Errors.md#class-invalidargumenterror
|
|
[`MockAgent`]: MockAgent.md#class-mockagent
|
|
[`MockCallHistoryLog`]: MockCallHistoryLog.md#class-mockcallhistorylog
|
|
[`mockCallHistoryLog.toString()`]: MockCallHistoryLog.md#mockcallhistorylogtostring
|