On this page

M

MockAgent

History
Source Code: lib/mock/mock-agent.js
Stability: 2Stable

A MockAgent is a <Dispatcher> that intercepts HTTP requests made through undici and replies with programmed mock responses instead of contacting the network. It is useful for testing code that performs HTTP requests without relying on a live server.

A MockAgent does not intercept requests on its own. Mock responses are registered on the <MockClient> or <MockPool> instances returned by mockAgent.get(origin), and requests are routed through them once the MockAgent is set as the dispatcher (for example through setGlobalDispatcher() or a per-request dispatcher option).

import { MockAgent } from 'undici'

const mockAgent = new MockAgent()
JavaScript
C

MockAgent

History
class MockAgent extends Dispatcher

Intercepts HTTP requests made through undici and returns mocked responses.

new MockAgent(options?): MockAgent
Attributes
options:<MockAgentOptions>
(optional)
Returns:<MockAgent>

When instantiated, a MockAgent is automatically activated. It does not intercept any request until mock interceptors are registered on the dispatchers returned by mockAgent.get(origin).

Attributes
Extends:<AgentOptions>
agent?:<Dispatcher>
(optional) A custom agent to be encapsulated by the  MockAgent . It must implement the Agent API (that is, expose a dispatch function). Default:  a new <Agent> constructed from  options .
ignoreTrailingSlash?:<boolean>
(optional) Whether trailing slashes in the request path are ignored when matching interceptors.  Default: false .
acceptNonStandardSearchParameters?:<boolean>
(optional) Whether the matcher also accepts URLs using non-standard search-parameter syntaxes, such as multi-value items written with  [] (for example param[]=1&param[]=2 ) or comma-separated values (for example param=1,2,3 ). Default: false .
enableCallHistory?:<boolean>
(optional) Whether call history recording is enabled. See  mockAgent.getCallHistory() . Default: false .
import { MockAgent } from 'undici'

const mockAgent = new MockAgent()
JavaScript
M

mockAgent.get

History
mockAgent.get(origin): MockClient | MockPool
Attributes
origin:<string> | <RegExp> | <Function>
A matcher for the origin to retrieve. The function form has the signature  (origin) => boolean .
Returns:<MockClient> | <MockPool>

Creates and retrieves the mock dispatcher used to intercept requests for the given origin. When the connections option of the MockAgent is 1, a <MockClient> is returned; otherwise a <MockPool> is returned. Subsequent calls with the same origin return the same instance.

The way origin is matched against incoming requests depends on its type:

Matcher typeCondition to pass
stringExact match against the value
RegExpThe regular expression matches
FunctionThe function returns true
import { MockAgent, setGlobalDispatcher, request } from 'undici'

const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)

const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')

const { statusCode, body } = await request('http://localhost:3000/foo')

console.log('response received', statusCode) // response received 200

for await (const data of body) {
  console.log('data', data.toString('utf8')) // data foo
}
JavaScript
M

mockAgent.dispatch

History
mockAgent.dispatch(options, handler): boolean
Attributes
options:<AgentDispatchOptions>
handler:<DispatchHandler>
Returns:<boolean>

Dispatches a mocked request. This implements Dispatcher.dispatch() for the encapsulated agent: it ensures the mock dispatcher for options.origin exists, records the call in the call history when enabled, and forwards the request to the underlying agent. It is normally invoked indirectly through higher-level methods such as mockAgent.request().

import { MockAgent } from 'undici'

const mockAgent = new MockAgent()

const mockPool = mockAgent.get('http://localhost:3000')
mockPool.intercept({ path: '/foo' }).reply(200, 'foo')

const { statusCode, body } = await mockAgent.request({
  origin: 'http://localhost:3000',
  path: '/foo',
  method: 'GET'
})

console.log('response received', statusCode) // response received 200

for await (const data of body) {
  console.log('data', data.toString('utf8')) // data foo
}
JavaScript
M

mockAgent.close

History
mockAgent.close(): Promise<void>
Returns:
{Promise } Resolves once the agent and its registered mock pools and clients have closed.

Clears the call history, closes the encapsulated agent, and waits for all registered mock pools and clients to close.

import { MockAgent, setGlobalDispatcher } from 'undici'

const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)

await mockAgent.close()
JavaScript
M

mockAgent.deactivate

History
mockAgent.deactivate(): undefined
Returns:<undefined>

Disables mocking on the MockAgent. While deactivated, requests are no longer intercepted.

import { MockAgent, setGlobalDispatcher } from 'undici'

const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)

mockAgent.deactivate()
JavaScript
M

mockAgent.activate

History
mockAgent.activate(): undefined
Returns:<undefined>

Enables mocking on the MockAgent. A MockAgent is activated automatically when instantiated, so this method is only required after mockAgent.deactivate() has been called.

import { MockAgent, setGlobalDispatcher } from 'undici'

const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)

mockAgent.deactivate()
// No mocking will occur

// Later
mockAgent.activate()
JavaScript
M

mockAgent.enableNetConnect

History
mockAgent.enableNetConnect(matcher?): undefined
Attributes
matcher:<string> | <RegExp> | <Function>
(optional) A host matcher. When a string is used it should only contain the hostname and, optionally, the port. The function form has the signature  (host) => boolean . When omitted, all non-matching requests are allowed to perform a real request.
Returns:<undefined>

Defines host matchers so that requests that are not intercepted by a mock dispatcher are allowed to perform a real HTTP request. Calling this method multiple times with a string appends each value to the list of allowed hosts.

import { MockAgent, setGlobalDispatcher, request } from 'undici'

const mockAgent = new MockAgent()
setGlobalDispatcher(mockAgent)

mockAgent.enableNetConnect()

await request('http://example.com')
// A real request is made
JavaScript
M

mockAgent.disableNetConnect

History
mockAgent.disableNetConnect(): undefined
Returns:<undefined>

Causes every request that is not matched by a mock interceptor to throw, disallowing real HTTP requests.

import { MockAgent, request } from 'undici'

const mockAgent = new MockAgent()

mockAgent.disableNetConnect()

await request('http://example.com')
// Will throw
JavaScript
M

mockAgent.enableCallHistory

History
mockAgent.enableCallHistory(): MockAgent
Returns:<MockAgent>
The same  MockAgent instance, for chaining.

Enables call history recording. Once enabled, subsequent calls are registered and can be retrieved through mockAgent.getCallHistory(). Call history can also be enabled at construction time with the enableCallHistory option.

import { MockAgent } from 'undici'

const mockAgent = new MockAgent()

mockAgent.enableCallHistory()
JavaScript
M

mockAgent.disableCallHistory

History
mockAgent.disableCallHistory(): MockAgent
Returns:<MockAgent>
The same  MockAgent instance, for chaining.

Disables call history recording. Subsequent calls are no longer registered.

import { MockAgent } from 'undici'

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

mockAgent.disableCallHistory()
JavaScript
M

mockAgent.getCallHistory

History
mockAgent.getCallHistory(): MockCallHistory | undefined
Returns:<MockCallHistory> | <undefined>
The <MockCallHistory> instance, or  undefined when call history is not enabled.

Returns the call history instance, which records every request made through the MockAgent (whether intercepted or not). Call history is not enabled by default; enable it with the enableCallHistory option or mockAgent.enableCallHistory().

import { MockAgent, setGlobalDispatcher, request } from 'undici'

const mockAgent = new MockAgent({ enableCallHistory: true })
setGlobalDispatcher(mockAgent)

await request('http://example.com', { query: { item: 1 } })

mockAgent.getCallHistory()?.firstCall()
// Returns
// MockCallHistoryLog {
//   body: undefined,
//   headers: undefined,
//   method: 'GET',
//   origin: 'http://example.com',
//   fullUrl: 'http://example.com/?item=1',
//   path: '/',
//   searchParams: { item: '1' },
//   protocol: 'http:',
//   host: 'example.com',
//   port: ''
// }
JavaScript
M

mockAgent.clearCallHistory

History
mockAgent.clearCallHistory(): undefined
Returns:<undefined>

Clears the call history, deleting every recorded <MockCallHistoryLog> on the <MockCallHistory> instance. It is a no-op when call history has never been enabled.

import { MockAgent } from 'undici'

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

mockAgent.clearCallHistory()
JavaScript
M

mockAgent.pendingInterceptors

History
mockAgent.pendingInterceptors(): PendingInterceptor
Returns:<PendingInterceptor>
[] A  PendingInterceptor is a MockDispatch with an additional origin   <string> property.

Returns the interceptors registered on the MockAgent that are still pending. An interceptor is pending when it meets one of the following criteria:

  • It is registered with neither .times(<number>) nor .persist() and has not been invoked.
  • It is persistent (registered with .persist()) and has not been invoked.
  • It is registered with .times(<number>) and has not been invoked <number> times.
import { MockAgent } from 'undici'

const mockAgent = new MockAgent()
mockAgent.disableNetConnect()

mockAgent
  .get('https://example.com')
  .intercept({ method: 'GET', path: '/' })
  .reply(200)

const pendingInterceptors = mockAgent.pendingInterceptors()
// Returns [
//   {
//     timesInvoked: 0,
//     times: 1,
//     persist: false,
//     consumed: false,
//     pending: true,
//     path: '/',
//     method: 'GET',
//     body: undefined,
//     headers: undefined,
//     data: {
//       error: null,
//       statusCode: 200,
//       data: '',
//       headers: {},
//       trailers: {}
//     },
//     origin: 'https://example.com'
//   }
// ]
JavaScript
M

mockAgent.assertNoPendingInterceptors

History
mockAgent.assertNoPendingInterceptors(options?): undefined
Attributes
options:<Object>
(optional)
pendingInterceptorsFormatter?:<Object>
An object exposing a  format(pendingInterceptors) method used to render the pending interceptors in the thrown error message. Default: a built-in formatter that prints a table.
Returns:<undefined>

Throws an <UndiciError> when the MockAgent has any pending interceptors. The criteria for an interceptor being pending are the same as for mockAgent.pendingInterceptors().

import { MockAgent } from 'undici'

const mockAgent = new MockAgent()
mockAgent.disableNetConnect()

mockAgent
  .get('https://example.com')
  .intercept({ method: 'GET', path: '/' })
  .reply(200)

mockAgent.assertNoPendingInterceptors()
// Throws an UndiciError with the following message:
//
// 1 interceptor is pending:
//
// ┌─────────┬────────┬───────────────────────┬──────┬─────────────┬────────────┬─────────────┬───────────┐
// │ (index) │ Method │        Origin         │ Path │ Status code │ Persistent │ Invocations │ Remaining │
// ├─────────┼────────┼───────────────────────┼──────┼─────────────┼────────────┼─────────────┼───────────┤
// │    0    │ 'GET'  │ 'https://example.com' │ '/'  │     200     │    '❌'    │      0      │     1     │
// └─────────┴────────┴───────────────────────┴──────┴─────────────┴────────────┴─────────────┴───────────┘
JavaScript
P

mockAgent.isMockActive

History
Type:<boolean>
true while mocking is active, false after mockAgent.deactivate() has been called.

A read-only property indicating whether mocking is currently active on the MockAgent.

import { MockAgent } from 'undici'

const mockAgent = new MockAgent()

console.log(mockAgent.isMockActive) // true

mockAgent.deactivate()

console.log(mockAgent.isMockActive) // false
JavaScript