Extends: undici.Dispatcher
A mocked Agent class that implements the Agent API. It allows one to intercept HTTP requests made through undici and return mocked responses instead.
", "signatures": [ { "textRaw": "`new MockAgent([options])`", "name": "MockAgent", "type": "ctor", "params": [ { "name": "options", "optional": true } ], "desc": "Arguments:
\nMockAgentOptions (optional) - It extends the Agent options.Returns: MockAgent
Extends: AgentOptions
agent Agent (optional) - Default: new Agent([options]) - a custom agent encapsulated by the MockAgent.
ignoreTrailingSlash boolean (optional) - Default: false - set the default value for ignoreTrailingSlash for interceptors.
acceptNonStandardSearchParameters boolean (optional) - Default: false - set to true if the matcher should also accept non standard search parameters such as multi-value items specified with [] (e.g. param[]=1¶m[]=2¶m[]=3) and multi-value items which values are comma separated (e.g. param=1,2,3).
This will instantiate the MockAgent. It will not do anything until registered as the agent to use with requests and mock interceptions are added.
\nimport { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nimport { Agent, MockAgent } from 'undici'\n\nconst agent = new Agent()\n\nconst mockAgent = new MockAgent({ agent })\nThis method creates and retrieves MockPool or MockClient instances which can then be used to intercept HTTP requests. If the number of connections on the mock agent is set to 1, a MockClient instance is returned. Otherwise a MockPool instance is returned.
\nFor subsequent MockAgent.get calls on the same origin, the same mock instance will be returned.
Arguments:
\nstring | RegExp | (value) => boolean - a matcher for the pool origin to be retrieved from the MockAgent.| Matcher type | \nCondition to pass | \n
|---|---|
string | \nExact match against string | \n
RegExp | \nRegex must pass | \n
Function | \nFunction must return true | \n
Returns: MockClient | MockPool.
MockAgentOptions | \nMock instance returned | \n
|---|---|
connections === 1 | \nMockClient | \n
connections > 1 | \nMockPool | \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 {\n statusCode,\n body\n} = await request('http://localhost:3000/foo', { dispatcher: mockAgent })\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 {\n statusCode,\n body\n} = await request('http://localhost:3000/foo', { dispatcher: mockPool })\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 {\n statusCode,\n body\n} = await request('http://localhost:3000/foo', { dispatcher: mockClient })\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('http://localhost:3000')\nmockPool.intercept({ path: '/foo' }).reply(200, 'foo')\nmockPool.intercept({ path: '/hello'}).reply(200, 'hello')\n\nconst result1 = await request('http://localhost:3000/foo')\n\nconsole.log('response received', result1.statusCode) // response received 200\n\nfor await (const data of result1.body) {\n console.log('data', data.toString('utf8')) // data foo\n}\n\nconst result2 = await request('http://localhost:3000/hello')\n\nconsole.log('response received', result2.statusCode) // response received 200\n\nfor await (const data of result2.body) {\n console.log('data', data.toString('utf8')) // data hello\n}\nconst { MockAgent, setGlobalDispatcher } = require('undici');\nconst agent = new MockAgent();\nagent.disableNetConnect();\nsetGlobalDispatcher(agent);\ndescribe('Test', () => {\n it('200', async () => {\n const mockAgent = agent.get('http://test.com');\n // your test\n });\n it('200', async () => {\n const mockAgent = agent.get('http://testing.com');\n // your test\n });\n});\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nmockPool.intercept({\n path: '/foo?hello=there&see=ya',\n method: 'POST',\n body: 'form1=data1&form2=data2'\n}).reply(200, { foo: 'bar' }, {\n headers: { 'content-type': 'application/json' },\n trailers: { 'Content-MD5': 'test' }\n})\n\nconst {\n statusCode,\n headers,\n trailers,\n body\n} = await request('http://localhost:3000/foo?hello=there&see=ya', {\n method: 'POST',\n body: 'form1=data1&form2=data2'\n})\n\nconsole.log('response received', statusCode) // response received 200\nconsole.log('headers', headers) // { 'content-type': 'application/json' }\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // '{\"foo\":\"bar\"}'\n}\n\nconsole.log('trailers', trailers) // { 'content-md5': 'test' }\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 {\n statusCode,\n body\n} = 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, 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 {\n statusCode,\n body\n} = 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}\nCloses the mock agent and waits for registered mock pools and clients to also close before resolving.
\nReturns: Promise<void>
import { MockAgent, setGlobalDispatcher } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nawait mockAgent.close()\nImplements Agent.dispatch(options, handlers).
See Dispatcher.request(options [, callback]).
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 {\n statusCode,\n body\n} = 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}\nThis method disables mocking in MockAgent.
\nReturns: void
import { MockAgent, setGlobalDispatcher } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nmockAgent.deactivate()\nThis method enables mocking in a MockAgent instance. When instantiated, a MockAgent is automatically activated. Therefore, this method is only effective after MockAgent.deactivate has been called.
Returns: void
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()\nWhen requests are not matched in a MockAgent intercept, a real HTTP request is attempted. We can control this further through the use of enableNetConnect. This is achieved by defining host matchers so only matching requests will be attempted.
When using a string, it should only include the hostname and optionally, the port. In addition, calling this method multiple times with a string will allow all HTTP requests that match these values.
\nArguments:
\nstring | RegExp | (value) => boolean - (optional)Returns: void
import { 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'))\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((value) => value === 'example.com')\n\nawait request('http://example.com')\n// A real request is made\nThis method causes all requests to throw when requests are not matched in a MockAgent intercept.
\nReturns: void
import { MockAgent, request } from 'undici'\n\nconst mockAgent = new MockAgent()\n\nmockAgent.disableNetConnect()\n\nawait request('http://example.com')\n// Will throw\nThis method returns any pending interceptors registered on a mock agent. A pending interceptor meets one of the following criteria:
\n.times(<number>) nor .persist(), and has not been invoked;.persist()) and has not been invoked;.times(<number>) and has not been invoked <number> of times.Returns: PendingInterceptor[] (where PendingInterceptor is a MockDispatch with an additional origin: string)
const agent = new MockAgent()\nagent.disableNetConnect()\n\nagent\n .get('https://example.com')\n .intercept({ method: 'GET', path: '/' })\n .reply(200)\n\nconst pendingInterceptors = agent.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// ]\nThis method throws if the mock agent has any pending interceptors. A pending interceptor meets one of the following criteria:
\n.times(<number>) nor .persist(), and has not been invoked;.persist()) and has not been invoked;.times(<number>) and has not been invoked <number> of times.const agent = new MockAgent()\nagent.disableNetConnect()\n\nagent\n .get('https://example.com')\n .intercept({ method: 'GET', path: '/' })\n .reply(200)\n\nagent.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// └─────────┴────────┴───────────────────────┴──────┴─────────────┴────────────┴─────────────┴───────────┘\nYou can register every call made within a MockAgent to be able to retrieve the body, headers and so on.
\nThis is not enabled by default.
\nimport { 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// }\nconst mockAgent = new MockAgent()\n\nmockAgent.clearCallHistory()\nconst mockAgent = new MockAgent()\n\nconst mockAgentHistory = mockAgent.getCallHistory()\n\nmockAgentHistory?.calls() // returns an array of MockCallHistoryLogs\nmockAgentHistory?.firstCall() // returns the first MockCallHistoryLogs or undefined\nmockAgentHistory?.lastCall() // returns the last MockCallHistoryLogs or undefined\nmockAgentHistory?.nthCall(3) // returns the third MockCallHistoryLogs or undefined\nmockAgentHistory?.filterCalls({ path: '/endpoint', hash: '#hash-value' }) // returns an Array of MockCallHistoryLogs WHERE path === /endpoint OR hash === #hash-value\nmockAgentHistory?.filterCalls({ path: '/endpoint', hash: '#hash-value' }, { operator: 'AND' }) // returns an Array of MockCallHistoryLogs WHERE path === /endpoint AND hash === #hash-value\nmockAgentHistory?.filterCalls(/\"data\": \"{}\"/) // returns an Array of MockCallHistoryLogs where any value match regexp\nmockAgentHistory?.filterCalls('application/json') // returns an Array of MockCallHistoryLogs where any value === 'application/json'\nmockAgentHistory?.filterCalls((log) => log.path === '/endpoint') // returns an Array of MockCallHistoryLogs when given function returns true\nmockAgentHistory?.clear() // clear the history\n