A MockAgent is a <Dispatcher> that intercepts HTTP requests made through\nundici and replies with programmed mock responses instead of contacting the\nnetwork. It is useful for testing code that performs HTTP requests without\nrelying on a live server.
A MockAgent does not intercept requests on its own. Mock responses are\nregistered on the <MockClient> or <MockPool> instances returned by mockAgent.get(origin), and requests are routed through them once the\nMockAgent is set as the dispatcher (for example through\nsetGlobalDispatcher() or a per-request dispatcher option).
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\n<Dispatcher>Intercepts HTTP requests made through undici and returns mocked responses.
", "signatures": [ { "textRaw": "`new MockAgent([options])`", "name": "MockAgent", "type": "ctor", "meta": { "added": [ "v4.0.0" ], "changes": [ { "version": "v7.16.0", "pr-url": "https://github.com/nodejs/undici/pull/4479", "description": "Mock options are always normalized to an object internally." } ] }, "params": [ { "textRaw": "`options` {MockAgentOptions} (optional)", "name": "options", "type": "MockAgentOptions", "desc": "(optional)", "optional": true } ], "return": { "textRaw": "Returns: {MockAgent}", "name": "return", "type": "MockAgent" }, "desc": "When instantiated, a MockAgent is automatically activated. It does not\nintercept any request until mock interceptors are registered on the dispatchers\nreturned by mockAgent.get(origin).
<AgentOptions>agent <Dispatcher> (optional) A custom agent to be encapsulated by the MockAgent. It must implement the Agent API (that is, expose a dispatch\nfunction). Default: a new <Agent> constructed from options.ignoreTrailingSlash <boolean> (optional) Whether trailing slashes in the\nrequest path are ignored when matching interceptors. Default: false.acceptNonStandardSearchParameters <boolean> (optional) Whether the matcher\nalso accepts URLs using non-standard search-parameter syntaxes, such as\nmulti-value items written with [] (for example param[]=1¶m[]=2) or\ncomma-separated values (for example param=1,2,3). Default: false.enableCallHistory <boolean> (optional) Whether call history recording is\nenabled. See mockAgent.getCallHistory(). Default: false.import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nimport { Agent, MockAgent } from 'undici'\n\nconst agent = new Agent()\n\nconst mockAgent = new MockAgent({ agent })\nCreates and retrieves the mock dispatcher used to intercept requests for the\ngiven origin. When the connections option of the MockAgent is 1, a\n<MockClient> is returned; otherwise a <MockPool> is returned. Subsequent calls\nwith the same origin return the same instance.
The way origin is matched against incoming requests depends on its type:
| Matcher type | \nCondition to pass | \n
|---|---|
string | \nExact match against the value | \n
RegExp | \nThe regular expression matches | \n
Function | \nThe function returns true | \n
import { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('http://localhost:3000')\nmockPool.intercept({ path: '/foo' }).reply(200, 'foo')\n\nconst { statusCode, body } = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // data foo\n}\nimport { MockAgent, request } from 'undici'\n\nconst mockAgent = new MockAgent()\n\nconst mockPool = mockAgent.get('http://localhost:3000')\nmockPool.intercept({ path: '/foo' }).reply(200, 'foo')\n\nconst { statusCode, body } = await request('http://localhost:3000/foo', {\n dispatcher: mockAgent\n})\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // data foo\n}\nimport { MockAgent, request } from 'undici'\n\nconst mockAgent = new MockAgent({ connections: 1 })\n\nconst mockClient = mockAgent.get('http://localhost:3000')\nmockClient.intercept({ path: '/foo' }).reply(200, 'foo')\n\nconst { statusCode, body } = await request('http://localhost:3000/foo', {\n dispatcher: mockClient\n})\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // data foo\n}\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get(new RegExp('http://localhost:3000'))\nmockPool.intercept({ path: '/foo' }).reply(200, 'foo')\n\nconst { statusCode } = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode) // response received 200\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get((origin) => origin === 'http://localhost:3000')\nmockPool.intercept({ path: '/foo' }).reply(200, 'foo')\n\nconst { statusCode } = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode) // response received 200\nDispatches a mocked request. This implements\nDispatcher.dispatch() for the encapsulated agent: it ensures the mock\ndispatcher for options.origin exists, records the call in the call history\nwhen enabled, and forwards the request to the underlying agent. It is normally\ninvoked indirectly through higher-level methods such as\nmockAgent.request().
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\n\nconst mockPool = mockAgent.get('http://localhost:3000')\nmockPool.intercept({ path: '/foo' }).reply(200, 'foo')\n\nconst { statusCode, body } = await mockAgent.request({\n origin: 'http://localhost:3000',\n path: '/foo',\n method: 'GET'\n})\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // data foo\n}\nClears the call history, closes the encapsulated agent, and waits for all\nregistered mock pools and clients to close.
\nimport { MockAgent, setGlobalDispatcher } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nawait mockAgent.close()\nDisables mocking on the MockAgent. While deactivated, requests are no longer\nintercepted.
import { MockAgent, setGlobalDispatcher } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nmockAgent.deactivate()\nEnables mocking on the MockAgent. A MockAgent is activated automatically\nwhen instantiated, so this method is only required after\nmockAgent.deactivate() has been called.
import { MockAgent, setGlobalDispatcher } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nmockAgent.deactivate()\n// No mocking will occur\n\n// Later\nmockAgent.activate()\nDefines host matchers so that requests that are not intercepted by a mock\ndispatcher are allowed to perform a real HTTP request. Calling this method\nmultiple times with a string appends each value to the list of allowed hosts.
\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nmockAgent.enableNetConnect()\n\nawait request('http://example.com')\n// A real request is made\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nmockAgent.enableNetConnect('example-1.com')\nmockAgent.enableNetConnect('example-2.com:8080')\n\nawait request('http://example-1.com')\n// A real request is made\n\nawait request('http://example-2.com:8080')\n// A real request is made\n\nawait request('http://example-3.com')\n// Will throw\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nmockAgent.enableNetConnect(new RegExp('example.com'))\nmockAgent.enableNetConnect((host) => host === 'example.org')\n\nawait request('http://example.com')\n// A real request is made\nCauses every request that is not matched by a mock interceptor to throw,\ndisallowing real HTTP requests.
\nimport { MockAgent, request } from 'undici'\n\nconst mockAgent = new MockAgent()\n\nmockAgent.disableNetConnect()\n\nawait request('http://example.com')\n// Will throw\nEnables call history recording. Once enabled, subsequent calls are registered\nand can be retrieved through mockAgent.getCallHistory(). Call history can\nalso be enabled at construction time with the enableCallHistory option.
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\n\nmockAgent.enableCallHistory()\nDisables call history recording. Subsequent calls are no longer registered.
\nimport { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent({ enableCallHistory: true })\n\nmockAgent.disableCallHistory()\nReturns the call history instance, which records every request made through the\nMockAgent (whether intercepted or not). Call history is not enabled by\ndefault; enable it with the enableCallHistory option or\nmockAgent.enableCallHistory().
import { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent({ enableCallHistory: true })\nsetGlobalDispatcher(mockAgent)\n\nawait request('http://example.com', { query: { item: 1 } })\n\nmockAgent.getCallHistory()?.firstCall()\n// Returns\n// MockCallHistoryLog {\n// body: undefined,\n// headers: undefined,\n// method: 'GET',\n// origin: 'http://example.com',\n// fullUrl: 'http://example.com/?item=1',\n// path: '/',\n// searchParams: { item: '1' },\n// protocol: 'http:',\n// host: 'example.com',\n// port: ''\n// }\nClears the call history, deleting every recorded <MockCallHistoryLog> on the\n<MockCallHistory> instance. It is a no-op when call history has never been\nenabled.
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent({ enableCallHistory: true })\n\nmockAgent.clearCallHistory()\nReturns the interceptors registered on the MockAgent that are still pending.\nAn interceptor is pending when it meets one of the following criteria:
.times(<number>) nor .persist() and has not\nbeen invoked..persist()) and has not been invoked..times(<number>) and has not been invoked <number>\ntimes.import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nmockAgent.disableNetConnect()\n\nmockAgent\n .get('https://example.com')\n .intercept({ method: 'GET', path: '/' })\n .reply(200)\n\nconst pendingInterceptors = mockAgent.pendingInterceptors()\n// Returns [\n// {\n// timesInvoked: 0,\n// times: 1,\n// persist: false,\n// consumed: false,\n// pending: true,\n// path: '/',\n// method: 'GET',\n// body: undefined,\n// headers: undefined,\n// data: {\n// error: null,\n// statusCode: 200,\n// data: '',\n// headers: {},\n// trailers: {}\n// },\n// origin: 'https://example.com'\n// }\n// ]\nThrows an <UndiciError> when the MockAgent has any pending interceptors. The\ncriteria for an interceptor being pending are the same as for\nmockAgent.pendingInterceptors().
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nmockAgent.disableNetConnect()\n\nmockAgent\n .get('https://example.com')\n .intercept({ method: 'GET', path: '/' })\n .reply(200)\n\nmockAgent.assertNoPendingInterceptors()\n// Throws an UndiciError with the following message:\n//\n// 1 interceptor is pending:\n//\n// ┌─────────┬────────┬───────────────────────┬──────┬─────────────┬────────────┬─────────────┬───────────┐\n// │ (index) │ Method │ Origin │ Path │ Status code │ Persistent │ Invocations │ Remaining │\n// ├─────────┼────────┼───────────────────────┼──────┼─────────────┼────────────┼─────────────┼───────────┤\n// │ 0 │ 'GET' │ 'https://example.com' │ '/' │ 200 │ '❌' │ 0 │ 1 │\n// └─────────┴────────┴───────────────────────┴──────┴─────────────┴────────────┴─────────────┴───────────┘\nA read-only property indicating whether mocking is currently active on the\nMockAgent.
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\n\nconsole.log(mockAgent.isMockActive) // true\n\nmockAgent.deactivate()\n\nconsole.log(mockAgent.isMockActive) // false\n