diff options
| author | Egor Tensin <egor@tensin.name> | 2026-02-28 21:59:12 +0100 |
|---|---|---|
| committer | Egor Tensin <egor@tensin.name> | 2026-02-28 22:19:57 +0100 |
| commit | 9611c248995ad3bacda1d0a93d0b5e1e6605d162 (patch) | |
| tree | eb3ae35b426e9d72e7cb34e8e9cc0453745a8e17 /node_modules/undici/docs/api/MockPool.md | |
| parent | DEVELOPMENT.md: expand on sources (diff) | |
| download | cleanup-path-9611c248995ad3bacda1d0a93d0b5e1e6605d162.tar.gz cleanup-path-9611c248995ad3bacda1d0a93d0b5e1e6605d162.zip | |
upgrade actions/core to version 2
Diffstat (limited to 'node_modules/undici/docs/api/MockPool.md')
| -rw-r--r-- | node_modules/undici/docs/api/MockPool.md | 547 |
1 files changed, 0 insertions, 547 deletions
diff --git a/node_modules/undici/docs/api/MockPool.md b/node_modules/undici/docs/api/MockPool.md deleted file mode 100644 index 96a986f..0000000 --- a/node_modules/undici/docs/api/MockPool.md +++ /dev/null @@ -1,547 +0,0 @@ -# Class: MockPool - -Extends: `undici.Pool` - -A mock Pool class that implements the Pool API and is used by MockAgent to intercept real requests and return mocked responses. - -## `new MockPool(origin, [options])` - -Arguments: - -* **origin** `string` - It should only include the **protocol, hostname, and port**. -* **options** `MockPoolOptions` - It extends the `Pool` options. - -Returns: `MockPool` - -### Parameter: `MockPoolOptions` - -Extends: `PoolOptions` - -* **agent** `Agent` - the agent to associate this MockPool with. - -### Example - Basic MockPool instantiation - -We can use MockAgent to instantiate a MockPool ready to be used to intercept specified requests. It will not do anything until registered as the agent to use and any mock request are registered. - -```js -import { MockAgent } from 'undici' - -const mockAgent = new MockAgent() - -const mockPool = mockAgent.get('http://localhost:3000') -``` - -## Instance Methods - -### `MockPool.intercept(options)` - -This method defines the interception rules for matching against requests for a MockPool or MockPool. We can intercept multiple times on a single instance, but each intercept is only used once. For example if you expect to make 2 requests inside a test, you need to call `intercept()` twice. Assuming you use `disableNetConnect()` you will get `MockNotMatchedError` on the second request when you only call `intercept()` once. - -When defining interception rules, all the rules must pass for a request to be intercepted. If a request is not intercepted, a real request will be attempted. - -| Matcher type | Condition to pass | -|:------------:| -------------------------- | -| `string` | Exact match against string | -| `RegExp` | Regex must pass | -| `Function` | Function must return true | - -Arguments: - -* **options** `MockPoolInterceptOptions` - Interception options. - -Returns: `MockInterceptor` corresponding to the input options. - -### Parameter: `MockPoolInterceptOptions` - -* **path** `string | RegExp | (path: string) => boolean` - a matcher for the HTTP request path. When a `RegExp` or callback is used, it will match against the request path including all query parameters in alphabetical order. When a `string` is provided, the query parameters can be conveniently specified through the `MockPoolInterceptOptions.query` setting. -* **method** `string | RegExp | (method: string) => boolean` - (optional) - a matcher for the HTTP request method. Defaults to `GET`. -* **body** `string | RegExp | (body: string) => boolean` - (optional) - a matcher for the HTTP request body. -* **headers** `Record<string, string | RegExp | (body: string) => boolean`> - (optional) - a matcher for the HTTP request headers. To be intercepted, a request must match all defined headers. Extra headers not defined here may (or may not) be included in the request and do not affect the interception in any way. -* **query** `Record<string, any> | null` - (optional) - a matcher for the HTTP request query string params. Only applies when a `string` was provided for `MockPoolInterceptOptions.path`. - -### Return: `MockInterceptor` - -We can define the behaviour of an intercepted request with the following options. - -* **reply** `(statusCode: number, replyData: string | Buffer | object | MockInterceptor.MockResponseDataHandler, responseOptions?: MockResponseOptions) => MockScope` - define a reply for a matching request. You can define the replyData as a callback to read incoming request data. Default for `responseOptions` is `{}`. -* **reply** `(callback: MockInterceptor.MockReplyOptionsCallback) => MockScope` - define a reply for a matching request, allowing dynamic mocking of all reply options rather than just the data. -* **replyWithError** `(error: Error) => MockScope` - define an error for a matching request to throw. -* **defaultReplyHeaders** `(headers: Record<string, string>) => MockInterceptor` - define default headers to be included in subsequent replies. These are in addition to headers on a specific reply. -* **defaultReplyTrailers** `(trailers: Record<string, string>) => MockInterceptor` - define default trailers to be included in subsequent replies. These are in addition to trailers on a specific reply. -* **replyContentLength** `() => MockInterceptor` - define automatically calculated `content-length` headers to be included in subsequent replies. - -The reply data of an intercepted request may either be a string, buffer, or JavaScript object. Objects are converted to JSON while strings and buffers are sent as-is. - -By default, `reply` and `replyWithError` define the behaviour for the first matching request only. Subsequent requests will not be affected (this can be changed using the returned `MockScope`). - -### Parameter: `MockResponseOptions` - -* **headers** `Record<string, string>` - headers to be included on the mocked reply. -* **trailers** `Record<string, string>` - trailers to be included on the mocked reply. - -### Return: `MockScope` - -A `MockScope` is associated with a single `MockInterceptor`. With this, we can configure the default behaviour of a intercepted reply. - -* **delay** `(waitInMs: number) => MockScope` - delay the associated reply by a set amount in ms. -* **persist** `() => MockScope` - any matching request will always reply with the defined response indefinitely. -* **times** `(repeatTimes: number) => MockScope` - any matching request will reply with the defined response a fixed amount of times. This is overridden by **persist**. - -#### Example - Basic Mocked Request - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -// MockPool -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 -} -``` - -#### Example - Mocked request using reply data callbacks - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/echo', - method: 'GET', - headers: { - 'User-Agent': 'undici', - Host: 'example.com' - } -}).reply(200, ({ headers }) => ({ message: headers.get('message') })) - -const { statusCode, body, headers } = await request('http://localhost:3000', { - headers: { - message: 'hello world!' - } -}) - -console.log('response received', statusCode) // response received 200 -console.log('headers', headers) // { 'content-type': 'application/json' } - -for await (const data of body) { - console.log('data', data.toString('utf8')) // { "message":"hello world!" } -} -``` - -#### Example - Mocked request using reply options callback - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/echo', - method: 'GET', - headers: { - 'User-Agent': 'undici', - Host: 'example.com' - } -}).reply(({ headers }) => ({ statusCode: 200, data: { message: headers.get('message') }}))) - -const { statusCode, body, headers } = await request('http://localhost:3000', { - headers: { - message: 'hello world!' - } -}) - -console.log('response received', statusCode) // response received 200 -console.log('headers', headers) // { 'content-type': 'application/json' } - -for await (const data of body) { - console.log('data', data.toString('utf8')) // { "message":"hello world!" } -} -``` - -#### Example - Basic Mocked requests with multiple intercepts - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: 'GET' -}).reply(200, 'foo') - -mockPool.intercept({ - path: '/hello', - method: 'GET', -}).reply(200, 'hello') - -const result1 = await request('http://localhost:3000/foo') - -console.log('response received', result1.statusCode) // response received 200 - -for await (const data of result1.body) { - console.log('data', data.toString('utf8')) // data foo -} - -const result2 = await request('http://localhost:3000/hello') - -console.log('response received', result2.statusCode) // response received 200 - -for await (const data of result2.body) { - console.log('data', data.toString('utf8')) // data hello -} -``` - -#### Example - Mocked request with query body, request headers and response headers and trailers - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo?hello=there&see=ya', - method: 'POST', - body: 'form1=data1&form2=data2', - headers: { - 'User-Agent': 'undici', - Host: 'example.com' - } -}).reply(200, { foo: 'bar' }, { - headers: { 'content-type': 'application/json' }, - trailers: { 'Content-MD5': 'test' } -}) - -const { - statusCode, - headers, - trailers, - body -} = await request('http://localhost:3000/foo?hello=there&see=ya', { - method: 'POST', - body: 'form1=data1&form2=data2', - headers: { - foo: 'bar', - 'User-Agent': 'undici', - Host: 'example.com' - } - }) - -console.log('response received', statusCode) // response received 200 -console.log('headers', headers) // { 'content-type': 'application/json' } - -for await (const data of body) { - console.log('data', data.toString('utf8')) // '{"foo":"bar"}' -} - -console.log('trailers', trailers) // { 'content-md5': 'test' } -``` - -#### Example - Mocked request using different matchers - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: /^GET$/, - body: (value) => value === 'form=data', - headers: { - 'User-Agent': 'undici', - Host: /^example.com$/ - } -}).reply(200, 'foo') - -const { - statusCode, - body -} = await request('http://localhost:3000/foo', { - method: 'GET', - body: 'form=data', - headers: { - foo: 'bar', - 'User-Agent': 'undici', - Host: 'example.com' - } -}) - -console.log('response received', statusCode) // response received 200 - -for await (const data of body) { - console.log('data', data.toString('utf8')) // data foo -} -``` - -#### Example - Mocked request with reply with a defined error - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: 'GET' -}).replyWithError(new Error('kaboom')) - -try { - await request('http://localhost:3000/foo', { - method: 'GET' - }) -} catch (error) { - console.error(error) // Error: kaboom -} -``` - -#### Example - Mocked request with defaultReplyHeaders - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: 'GET' -}).defaultReplyHeaders({ foo: 'bar' }) - .reply(200, 'foo') - -const { headers } = await request('http://localhost:3000/foo') - -console.log('headers', headers) // headers { foo: 'bar' } -``` - -#### Example - Mocked request with defaultReplyTrailers - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: 'GET' -}).defaultReplyTrailers({ foo: 'bar' }) - .reply(200, 'foo') - -const { trailers } = await request('http://localhost:3000/foo') - -console.log('trailers', trailers) // trailers { foo: 'bar' } -``` - -#### Example - Mocked request with automatic content-length calculation - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: 'GET' -}).replyContentLength().reply(200, 'foo') - -const { headers } = await request('http://localhost:3000/foo') - -console.log('headers', headers) // headers { 'content-length': '3' } -``` - -#### Example - Mocked request with automatic content-length calculation on an object - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: 'GET' -}).replyContentLength().reply(200, { foo: 'bar' }) - -const { headers } = await request('http://localhost:3000/foo') - -console.log('headers', headers) // headers { 'content-length': '13' } -``` - -#### Example - Mocked request with persist enabled - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: 'GET' -}).reply(200, 'foo').persist() - -const result1 = await request('http://localhost:3000/foo') -// Will match and return mocked data - -const result2 = await request('http://localhost:3000/foo') -// Will match and return mocked data - -// Etc -``` - -#### Example - Mocked request with times enabled - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -mockPool.intercept({ - path: '/foo', - method: 'GET' -}).reply(200, 'foo').times(2) - -const result1 = await request('http://localhost:3000/foo') -// Will match and return mocked data - -const result2 = await request('http://localhost:3000/foo') -// Will match and return mocked data - -const result3 = await request('http://localhost:3000/foo') -// Will not match and make attempt a real request -``` - -#### Example - Mocked request with path callback - -```js -import { MockAgent, setGlobalDispatcher, request } from 'undici' -import querystring from 'querystring' - -const mockAgent = new MockAgent() -setGlobalDispatcher(mockAgent) - -const mockPool = mockAgent.get('http://localhost:3000') - -const matchPath = requestPath => { - const [pathname, search] = requestPath.split('?') - const requestQuery = querystring.parse(search) - - if (!pathname.startsWith('/foo')) { - return false - } - - if (!Object.keys(requestQuery).includes('foo') || requestQuery.foo !== 'bar') { - return false - } - - return true -} - -mockPool.intercept({ - path: matchPath, - method: 'GET' -}).reply(200, 'foo') - -const result = await request('http://localhost:3000/foo?foo=bar') -// Will match and return mocked data -``` - -### `MockPool.close()` - -Closes the mock pool and de-registers from associated MockAgent. - -Returns: `Promise<void>` - -#### Example - clean up after tests are complete - -```js -import { MockAgent } from 'undici' - -const mockAgent = new MockAgent() -const mockPool = mockAgent.get('http://localhost:3000') - -await mockPool.close() -``` - -### `MockPool.dispatch(options, handlers)` - -Implements [`Dispatcher.dispatch(options, handlers)`](Dispatcher.md#dispatcherdispatchoptions-handler). - -### `MockPool.request(options[, callback])` - -See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback). - -#### Example - MockPool request - -```js -import { MockAgent } from 'undici' - -const mockAgent = new MockAgent() - -const mockPool = mockAgent.get('http://localhost:3000') -mockPool.intercept({ - path: '/foo', - method: 'GET', -}).reply(200, 'foo') - -const { - statusCode, - body -} = await mockPool.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 -} -``` |
