A MockPool is a Pool that intercepts requests matching registered routes\nand replies with mocked responses instead of contacting the network. It is\ncreated by a MockAgent and exposes the same interception API as\nMockClient.
A MockPool is not constructed directly in most cases; instead it is obtained\nthrough [mockAgent.get(origin)][]. Once registered as the global dispatcher,\nany request whose origin matches the pool is matched against the mocks it holds.
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nconst mockPool = mockAgent.get('http://localhost:3000')\nconst { MockAgent } = require('undici')\n\nconst mockAgent = new MockAgent()\nconst mockPool = mockAgent.get('http://localhost:3000')\n<Pool>Extends Pool and implements the Interceptable interface, allowing\nrequests made through it to be matched against registered mocks.
The agent option is required and must implement the Agent interface;\notherwise an InvalidArgumentError is thrown.
Extends: PoolOptions
agent <MockAgent> The agent to associate this mock pool with.ignoreTrailingSlash <boolean> Whether trailing slashes should be ignored\nwhen matching the path of intercepted requests. Default: false.Registers a route on the mock pool and returns a MockInterceptor for any\nmatching request that uses the same origin as this mock pool. The interceptor is\nthen used to define the reply, for example with reply() or replyWithError().
Each intercept() call is consumed by a single matching request. To match more\nthan one request, call intercept() once per expected request, or use\npersist() or times() on the returned MockScope. When no registered\nmock matches a request, a real request is attempted unless network connections\nhave been disabled on the MockAgent, in which case a MockNotMatchedError\nis thrown.
A request is intercepted only when every defined matcher passes. The accepted\nmatcher forms behave as follows:
\n| Matcher type | \nCondition to pass | \n
|---|---|
string | \nExact match against the value | \n
RegExp | \nThe expression must match | \n
Function | \nThe function must return true | \n
path <string> | <RegExp> | <Function> A matcher for the HTTP request path. The\nfunction form has the signature (path: string) => boolean. When a RegExp\nor function is used, it matches against the request path including all query\nparameters in alphabetical order. When a string is used, query parameters\ncan instead be supplied through query.method <string> | <RegExp> | <Function> A matcher for the HTTP request method. The\nfunction form has the signature (method: string) => boolean.\nDefault: 'GET'.body <string> | <RegExp> | <Function> A matcher for the HTTP request body. The\nfunction form has the signature (body: string) => boolean.headers <Object> | <Function> A matcher for the HTTP request headers, given\neither as a map of header name to a string, RegExp, or\n(value: string) => boolean matcher, or as a single function that receives\nall headers and returns a boolean. When a map is used, the request must\nmatch every defined header; extra headers not listed here do not affect\nmatching.query <Object> A matcher for the HTTP request query string parameters. Only\napplies when a string was provided for path.ignoreTrailingSlash <boolean> Whether a trailing slash on path is ignored\nwhen matching. Inherited from the mock pool's ignoreTrailingSlash option\nwhen not set.The reply behaviour of a matching request is defined through the returned\nMockInterceptor.
reply(statusCode[, data[, responseOptions]]) <Function> Defines the reply\nfor a matching request.\nstatusCode <number> The status code of the mocked reply.data <string> | <Buffer> | <Object> | <Function> The body of the mocked reply.\nObjects are serialized to JSON; strings and Buffers are sent as-is. The\nfunction form has the signature\n(opts: MockResponseCallbackOptions) => string | Buffer | Object and is\ninvoked with the incoming request to compute the reply body.responseOptions <MockResponseOptions> Additional reply options. Default: {}.<MockScope>reply(callback) <Function> Defines the reply for a matching request,\ncomputing all reply options dynamically rather than just the body.\ncallback <Function> A (opts: MockResponseCallbackOptions) => { statusCode, data, responseOptions } function invoked with the incoming\nrequest.<MockScope>replyWithError(error) <Function> Defines an error for a matching request to\nthrow.\nerror <Error> The error thrown when a request matches.<MockScope>defaultReplyHeaders(headers) <Function> Sets default headers included on\nevery subsequent reply defined on this interceptor, in addition to any headers\nset on a specific reply.\nheaders <Object> A map of header name to value.<MockInterceptor>defaultReplyTrailers(trailers) <Function> Sets default trailers included on\nevery subsequent reply defined on this interceptor, in addition to any\ntrailers set on a specific reply.\ntrailers <Object> A map of trailer name to value.<MockInterceptor>replyContentLength() <Function> Sets an automatically calculated content-length header on every subsequent reply defined on this interceptor.\n<MockInterceptor>By default, reply() and replyWithError() define the behaviour for the first\nmatching request only; subsequent requests are not affected unless persist()\nor times() is used on the returned MockScope.
The argument passed to the reply() data and options callbacks.
path <string> The path of the intercepted request.method <string> The method of the intercepted request.headers <Object> | <Headers> The headers of the intercepted request.origin <string> The origin of the intercepted request.body <string> | <null> The body of the intercepted request.headers <Object> Headers to include on the mocked reply.trailers <Object> Trailers to include on the mocked reply.A MockScope is associated with a single MockInterceptor and configures\nhow many times the defined reply is used.
delay(waitInMs) <Function> Delays the associated reply by a set amount of\ntime.\nwaitInMs <number> The delay in milliseconds.<MockScope>persist() <Function> Makes the associated reply match indefinitely, so every\nmatching request receives the defined response.\n<MockScope>times(repeatTimes) <Function> Makes the associated reply match a fixed number\nof times. This is overridden by persist().\nrepeatTimes <number> The number of matching requests the reply applies to.<MockScope>The following examples show common interception patterns.
\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')\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, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nmockPool.intercept({\n path: '/echo',\n method: 'GET'\n}).reply(200, ({ headers }) => ({ message: headers.message }))\n\nconst { statusCode, body } = await request('http://localhost:3000/echo', {\n headers: { message: 'hello world!' }\n})\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // {\"message\":\"hello world!\"}\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: '/echo',\n method: 'GET'\n}).reply(({ headers }) => ({\n statusCode: 200,\n data: { message: headers.message }\n}))\n\nconst { statusCode, body } = await request('http://localhost:3000/echo', {\n headers: { message: 'hello world!' }\n})\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n console.log('data', data.toString('utf8')) // {\"message\":\"hello world!\"}\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({ path: '/foo', method: 'GET' }).reply(200, 'foo')\nmockPool.intercept({ path: '/hello', method: 'GET' }).reply(200, 'hello')\n\nconst fooResult = await request('http://localhost:3000/foo')\nfor await (const data of fooResult.body) {\n console.log('data', data.toString('utf8')) // data foo\n}\n\nconst helloResult = await request('http://localhost:3000/hello')\nfor await (const data of helloResult.body) {\n console.log('data', data.toString('utf8')) // data hello\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 headers: {\n 'User-Agent': 'undici',\n Host: 'example.com'\n }\n}).reply(200, { foo: 'bar' }, {\n headers: { 'content-type': 'application/json' },\n trailers: { 'Content-MD5': 'test' }\n})\n\nconst { statusCode, headers, trailers, body } = await request(\n 'http://localhost:3000/foo?hello=there&see=ya',\n {\n method: 'POST',\n body: 'form1=data1&form2=data2',\n headers: {\n foo: 'bar',\n 'User-Agent': 'undici',\n Host: 'example.com'\n }\n }\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('http://localhost:3000')\n\nmockPool.intercept({\n path: '/foo',\n method: /^GET$/,\n body: (value) => value === 'form=data',\n headers: {\n 'User-Agent': 'undici',\n Host: /^example\\.com$/\n }\n}).reply(200, 'foo')\n\nconst { statusCode, body } = await request('http://localhost:3000/foo', {\n method: 'GET',\n body: 'form=data',\n headers: {\n foo: 'bar',\n 'User-Agent': 'undici',\n Host: 'example.com'\n }\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('http://localhost:3000')\n\nmockPool.intercept({\n path: '/foo',\n method: 'GET'\n}).replyWithError(new Error('kaboom'))\n\ntry {\n await request('http://localhost:3000/foo', { method: 'GET' })\n} catch (error) {\n console.error(error.message) // kaboom\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({ path: '/foo', method: 'GET' })\n .defaultReplyHeaders({ foo: 'bar' })\n .reply(200, 'foo')\n\nconst { headers } = await request('http://localhost:3000/foo')\n\nconsole.log('headers', headers) // headers { foo: 'bar' }\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nmockPool.intercept({ path: '/foo', method: 'GET' })\n .defaultReplyTrailers({ foo: 'bar' })\n .reply(200, 'foo')\n\nconst { trailers } = await request('http://localhost:3000/foo')\n\nconsole.log('trailers', trailers) // trailers { foo: 'bar' }\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nmockPool.intercept({ path: '/foo', method: 'GET' })\n .replyContentLength()\n .reply(200, 'foo')\n\nconst { headers } = await request('http://localhost:3000/foo')\n\nconsole.log('headers', headers) // headers { 'content-length': '3' }\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nmockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').persist()\n\nawait request('http://localhost:3000/foo') // Matches and returns the mock\nawait request('http://localhost:3000/foo') // Matches again, indefinitely\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nmockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').times(2)\n\nawait request('http://localhost:3000/foo') // Matches and returns the mock\nawait request('http://localhost:3000/foo') // Matches and returns the mock\nawait request('http://localhost:3000/foo') // No match; a real request is attempted\nimport { MockAgent, setGlobalDispatcher, request } from 'undici'\nimport querystring from 'node:querystring'\n\nconst mockAgent = new MockAgent()\nsetGlobalDispatcher(mockAgent)\n\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nconst matchPath = (requestPath) => {\n const [pathname, search] = requestPath.split('?')\n const requestQuery = querystring.parse(search)\n\n if (!pathname.startsWith('/foo')) {\n return false\n }\n\n return requestQuery.foo === 'bar'\n}\n\nmockPool.intercept({ path: matchPath, method: 'GET' }).reply(200, 'foo')\n\nawait request('http://localhost:3000/foo?foo=bar') // Matches and returns the mock\nCloses the mock pool, gracefully waiting for any enqueued requests to complete,\nand removes it from the associated MockAgent.
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nawait mockPool.close()\nDispatches a request, matching it against the registered mocks. This override of\ndispatcher.dispatch(options, handlers) is what drives the mocking\nbehaviour for every higher-level method such as request.
Performs a request and resolves it against the registered mocks. Inherited from\nPool; see [dispatcher.request(options[, callback])][] for the full\nparameter and return value documentation.
import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nconst mockPool = mockAgent.get('http://localhost:3000')\nmockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')\n\nconst { statusCode, body } = await mockPool.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}\nRemoves all registered interceptors from the mock pool. Pending mocks defined\nbefore this call no longer match incoming requests.
\nimport { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nconst mockPool = mockAgent.get('http://localhost:3000')\n\nmockPool.intercept({ path: '/foo' }).reply(200, 'foo')\nmockPool.cleanMocks()\n[dispatcher.request(options[, callback])]: Dispatcher.md#dispatcherrequestoptions-callback\n[mockAgent.get(origin)]: MockAgent.md#mockagentgetorigin