@noodleseed/one 0.22.0 → 0.24.0

package/node_modules/undici/docs/docs/api/MockPool.md

@@ -1,109 +1,209 @@
-# Class: MockPool
+# MockPool
 
-Extends: `undici.Pool`
+<!--introduced_in=v4.0.0-->
+<!--type=module-->
+<!-- source_link=lib/mock/mock-pool.js -->
 
-A mock Pool class that implements the Pool API and is used by MockAgent to intercept real requests and return mocked responses.
+> Stability: 2 - Stable
 
-## `new MockPool(origin, [options])`
+A `MockPool` is a [`Pool`][] that intercepts requests matching registered routes
+and replies with mocked responses instead of contacting the network. It is
+created by a [`MockAgent`][] and exposes the same interception API as
+[`MockClient`][].
 
-Arguments:
+A `MockPool` is not constructed directly in most cases; instead it is obtained
+through [`mockAgent.get(origin)`][]. Once registered as the global dispatcher,
+any request whose origin matches the pool is matched against the mocks it holds.
 
-* **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
+```mjs
 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.
+```cjs
+const { MockAgent } = require('undici')
 
-### 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`.
-* **ignoreTrailingSlash** `boolean` - (optional) - set to `true` if the matcher should also match by ignoring potential trailing slashes in `MockPoolInterceptOptions.path`.
-
-### Return: `MockInterceptor`
+const mockAgent = new MockAgent()
+const mockPool = mockAgent.get('http://localhost:3000')
+```
 
-We can define the behaviour of an intercepted request with the following options.
+## Class: `MockPool`
 
-* **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.
+<!-- YAML
+added: v4.0.0
+-->
 
-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.
+* Extends: {Pool}
 
-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`).
+Extends [`Pool`][] and implements the `Interceptable` interface, allowing
+requests made through it to be matched against registered mocks.
 
-### Parameter: `MockResponseOptions`
+### `new MockPool(origin[, options])`
 
-* **headers** `Record<string, string>` - headers to be included on the mocked reply.
-* **trailers** `Record<string, string>` - trailers to be included on the mocked reply.
+<!-- YAML
+added: v4.0.0
+-->
 
-### Return: `MockScope`
+* `origin` {string} The origin to associate this mock pool with. It should only
+  include the protocol, hostname, and port.
+* `options` {MockPoolOptions} Extends the [`Pool`][] options.
+* Returns: {MockPool}
 
-A `MockScope` is associated with a single `MockInterceptor`. With this, we can configure the default behaviour of an intercepted reply.
+The `agent` option is required and must implement the `Agent` interface;
+otherwise an `InvalidArgumentError` is thrown.
 
-* **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**.
+#### Parameter: `MockPoolOptions`
 
-#### Example - Basic Mocked Request
+Extends: `PoolOptions`
 
-```js
+* `agent` {MockAgent} The agent to associate this mock pool with.
+* `ignoreTrailingSlash` {boolean} Whether trailing slashes should be ignored
+  when matching the path of intercepted requests. **Default:** `false`.
+
+### `mockPool.intercept(options)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {MockPoolInterceptOptions} The matching criteria for the requests to
+  intercept.
+* Returns: {MockInterceptor} The interceptor used to define the mocked reply.
+
+Registers a route on the mock pool and returns a [`MockInterceptor`][] for any
+matching request that uses the same origin as this mock pool. The interceptor is
+then used to define the reply, for example with `reply()` or `replyWithError()`.
+
+Each `intercept()` call is consumed by a single matching request. To match more
+than one request, call `intercept()` once per expected request, or use
+`persist()` or `times()` on the returned [`MockScope`][]. When no registered
+mock matches a request, a real request is attempted unless network connections
+have been disabled on the [`MockAgent`][], in which case a `MockNotMatchedError`
+is thrown.
+
+A request is intercepted only when every defined matcher passes. The accepted
+matcher forms behave as follows:
+
+| Matcher type | Condition to pass            |
+| :----------: | ---------------------------- |
+| `string`     | Exact match against the value |
+| `RegExp`     | The expression must match    |
+| `Function`   | The function must return `true` |
+
+#### Parameter: `MockPoolInterceptOptions`
+
+* `path` {string|RegExp|Function} A matcher for the HTTP request path. The
+  function form has the signature `(path: string) => boolean`. When a `RegExp`
+  or function is used, it matches against the request path including all query
+  parameters in alphabetical order. When a `string` is used, query parameters
+  can instead be supplied through `query`.
+* `method` {string|RegExp|Function} A matcher for the HTTP request method. The
+  function form has the signature `(method: string) => boolean`.
+  **Default:** `'GET'`.
+* `body` {string|RegExp|Function} A matcher for the HTTP request body. The
+  function form has the signature `(body: string) => boolean`.
+* `headers` {Object|Function} A matcher for the HTTP request headers, given
+  either as a map of header name to a `string`, `RegExp`, or
+  `(value: string) => boolean` matcher, or as a single function that receives
+  all headers and returns a `boolean`. When a map is used, the request must
+  match every defined header; extra headers not listed here do not affect
+  matching.
+* `query` {Object} A matcher for the HTTP request query string parameters. Only
+  applies when a `string` was provided for `path`.
+* `ignoreTrailingSlash` {boolean} Whether a trailing slash on `path` is ignored
+  when matching. Inherited from the mock pool's `ignoreTrailingSlash` option
+  when not set.
+
+#### Return: `MockInterceptor`
+
+The reply behaviour of a matching request is defined through the returned
+`MockInterceptor`.
+
+* `reply(statusCode[, data[, responseOptions]])` {Function} Defines the reply
+  for a matching request.
+  * `statusCode` {number} The status code of the mocked reply.
+  * `data` {string|Buffer|Object|Function} The body of the mocked reply.
+    Objects are serialized to JSON; strings and `Buffer`s are sent as-is. The
+    function form has the signature
+    `(opts: MockResponseCallbackOptions) => string | Buffer | Object` and is
+    invoked with the incoming request to compute the reply body.
+  * `responseOptions` {MockResponseOptions} Additional reply options.
+    **Default:** `{}`.
+  * Returns: {MockScope}
+* `reply(callback)` {Function} Defines the reply for a matching request,
+  computing all reply options dynamically rather than just the body.
+  * `callback` {Function} A `(opts: MockResponseCallbackOptions) =>
+    { statusCode, data, responseOptions }` function invoked with the incoming
+    request.
+  * Returns: {MockScope}
+* `replyWithError(error)` {Function} Defines an error for a matching request to
+  throw.
+  * `error` {Error} The error thrown when a request matches.
+  * Returns: {MockScope}
+* `defaultReplyHeaders(headers)` {Function} Sets default headers included on
+  every subsequent reply defined on this interceptor, in addition to any headers
+  set on a specific reply.
+  * `headers` {Object} A map of header name to value.
+  * Returns: {MockInterceptor}
+* `defaultReplyTrailers(trailers)` {Function} Sets default trailers included on
+  every subsequent reply defined on this interceptor, in addition to any
+  trailers set on a specific reply.
+  * `trailers` {Object} A map of trailer name to value.
+  * Returns: {MockInterceptor}
+* `replyContentLength()` {Function} Sets an automatically calculated
+  `content-length` header on every subsequent reply defined on this interceptor.
+  * Returns: {MockInterceptor}
+
+By default, `reply()` and `replyWithError()` define the behaviour for the first
+matching request only; subsequent requests are not affected unless `persist()`
+or `times()` is used on the returned [`MockScope`][].
+
+#### Parameter: `MockResponseCallbackOptions`
+
+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.
+
+#### Parameter: `MockResponseOptions`
+
+* `headers` {Object} Headers to include on the mocked reply.
+* `trailers` {Object} Trailers to include on the mocked reply.
+
+#### Return: `MockScope`
+
+A `MockScope` is associated with a single [`MockInterceptor`][] and configures
+how many times the defined reply is used.
+
+* `delay(waitInMs)` {Function} Delays the associated reply by a set amount of
+  time.
+  * `waitInMs` {number} The delay in milliseconds.
+  * Returns: {MockScope}
+* `persist()` {Function} Makes the associated reply match indefinitely, so every
+  matching request receives the defined response.
+  * Returns: {MockScope}
+* `times(repeatTimes)` {Function} Makes the associated reply match a fixed number
+  of times. This is overridden by `persist()`.
+  * `repeatTimes` {number} The number of matching requests the reply applies to.
+  * Returns: {MockScope}
+
+The following examples show common interception patterns.
+
+```mjs displayName="Basic mocked request"
 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')
+const { statusCode, body } = await request('http://localhost:3000/foo')
 
 console.log('response received', statusCode) // response received 200
 
@@ -112,9 +212,7 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Mocked request using reply data callbacks
-
-```js
+```mjs displayName="Reply with a data callback"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -124,30 +222,21 @@ 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') }))
+  method: 'GET'
+}).reply(200, ({ headers }) => ({ message: headers.message }))
 
-const { statusCode, body, headers } = await request('http://localhost:3000', {
-  headers: {
-    message: 'hello world!'
-  }
+const { statusCode, body } = await request('http://localhost:3000/echo', {
+  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!" }
+  console.log('data', data.toString('utf8')) // {"message":"hello world!"}
 }
 ```
 
-#### Example - Mocked request using reply options callback
-
-```js
+```mjs displayName="Reply with an options callback"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -157,30 +246,24 @@ 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') }})))
+  method: 'GET'
+}).reply(({ headers }) => ({
+  statusCode: 200,
+  data: { message: headers.message }
+}))
 
-const { statusCode, body, headers } = await request('http://localhost:3000', {
-  headers: {
-    message: 'hello world!'
-  }
+const { statusCode, body } = await request('http://localhost:3000/echo', {
+  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!" }
+  console.log('data', data.toString('utf8')) // {"message":"hello world!"}
 }
 ```
 
-#### Example - Basic Mocked requests with multiple intercepts
-
-```js
+```mjs displayName="Multiple intercepts"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -188,36 +271,21 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).reply(200, 'foo')
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
+mockPool.intercept({ path: '/hello', method: 'GET' }).reply(200, 'hello')
 
-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) {
+const fooResult = await request('http://localhost:3000/foo')
+for await (const data of fooResult.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) {
+const helloResult = await request('http://localhost:3000/hello')
+for await (const data of helloResult.body) {
   console.log('data', data.toString('utf8')) // data hello
 }
 ```
 
-#### Example - Mocked request with query body, request headers and response headers and trailers
-
-```js
+```mjs displayName="Match query, body, request headers; reply with headers and trailers"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -238,12 +306,9 @@ mockPool.intercept({
   trailers: { 'Content-MD5': 'test' }
 })
 
-const {
-  statusCode,
-  headers,
-  trailers,
-  body
-} = await request('http://localhost:3000/foo?hello=there&see=ya', {
+const { statusCode, headers, trailers, body } = await request(
+  'http://localhost:3000/foo?hello=there&see=ya',
+  {
     method: 'POST',
     body: 'form1=data1&form2=data2',
     headers: {
@@ -251,21 +316,20 @@ const {
       '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('data', data.toString('utf8')) // {"foo":"bar"}
 }
 
 console.log('trailers', trailers) // { 'content-md5': 'test' }
 ```
 
-#### Example - Mocked request using different matchers
-
-```js
+```mjs displayName="Different matcher forms"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -279,14 +343,11 @@ mockPool.intercept({
   body: (value) => value === 'form=data',
   headers: {
     'User-Agent': 'undici',
-    Host: /^example.com$/
+    Host: /^example\.com$/
   }
 }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', {
+const { statusCode, body } = await request('http://localhost:3000/foo', {
   method: 'GET',
   body: 'form=data',
   headers: {
@@ -303,9 +364,7 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Mocked request with reply with a defined error
-
-```js
+```mjs displayName="Reply with an error"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -319,18 +378,13 @@ mockPool.intercept({
 }).replyWithError(new Error('kaboom'))
 
 try {
-  await request('http://localhost:3000/foo', {
-    method: 'GET'
-  })
+  await request('http://localhost:3000/foo', { method: 'GET' })
 } catch (error) {
-  console.error(error) // TypeError: fetch failed
-  console.error(error.cause) // Error: kaboom
+  console.error(error.message) // kaboom
 }
 ```
 
-#### Example - Mocked request with defaultReplyHeaders
-
-```js
+```mjs displayName="Default reply headers"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -338,10 +392,8 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).defaultReplyHeaders({ foo: 'bar' })
+mockPool.intercept({ path: '/foo', method: 'GET' })
+  .defaultReplyHeaders({ foo: 'bar' })
   .reply(200, 'foo')
 
 const { headers } = await request('http://localhost:3000/foo')
@@ -349,9 +401,7 @@ const { headers } = await request('http://localhost:3000/foo')
 console.log('headers', headers) // headers { foo: 'bar' }
 ```
 
-#### Example - Mocked request with defaultReplyTrailers
-
-```js
+```mjs displayName="Default reply trailers"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -359,10 +409,8 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).defaultReplyTrailers({ foo: 'bar' })
+mockPool.intercept({ path: '/foo', method: 'GET' })
+  .defaultReplyTrailers({ foo: 'bar' })
   .reply(200, 'foo')
 
 const { trailers } = await request('http://localhost:3000/foo')
@@ -370,9 +418,7 @@ const { trailers } = await request('http://localhost:3000/foo')
 console.log('trailers', trailers) // trailers { foo: 'bar' }
 ```
 
-#### Example - Mocked request with automatic content-length calculation
-
-```js
+```mjs displayName="Automatic content-length"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -380,19 +426,16 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET'
-}).replyContentLength().reply(200, 'foo')
+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
+```mjs displayName="Persisted reply"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -400,43 +443,13 @@ 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
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').persist()
 
-// Etc
+await request('http://localhost:3000/foo') // Matches and returns the mock
+await request('http://localhost:3000/foo') // Matches again, indefinitely
 ```
 
-#### Example - Mocked request with times enabled
-
-```js
+```mjs displayName="Reply a fixed number of times"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -444,33 +457,23 @@ 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
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').times(2)
 
-const result3 = await request('http://localhost:3000/foo')
-// Will not match and make attempt a real request
+await request('http://localhost:3000/foo') // Matches and returns the mock
+await request('http://localhost:3000/foo') // Matches and returns the mock
+await request('http://localhost:3000/foo') // No match; a real request is attempted
 ```
 
-#### Example - Mocked request with path callback
-
-```js
+```mjs displayName="Match the path with a function"
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
-import querystring from 'querystring'
+import querystring from 'node:querystring'
 
 const mockAgent = new MockAgent()
 setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-const matchPath = requestPath => {
+const matchPath = (requestPath) => {
   const [pathname, search] = requestPath.split('?')
   const requestQuery = querystring.parse(search)
 
@@ -478,31 +481,26 @@ const matchPath = requestPath => {
     return false
   }
 
-  if (!Object.keys(requestQuery).includes('foo') || requestQuery.foo !== 'bar') {
-    return false
-  }
-
-  return true
+  return requestQuery.foo === 'bar'
 }
 
-mockPool.intercept({
-  path: matchPath,
-  method: 'GET'
-}).reply(200, 'foo')
+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
+await request('http://localhost:3000/foo?foo=bar') // Matches and returns the mock
 ```
 
-### `MockPool.close()`
+### `mockPool.close()`
 
-Closes the mock pool and de-registers from associated MockAgent.
+<!-- YAML
+added: v4.0.0
+-->
 
-Returns: `Promise<void>`
+* Returns: {Promise} Fulfills with `undefined` once the mock pool is closed.
 
-#### Example - clean up after tests are complete
+Closes the mock pool, gracefully waiting for any enqueued requests to complete,
+and removes it from the associated [`MockAgent`][].
 
-```js
+```mjs
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -511,31 +509,45 @@ const mockPool = mockAgent.get('http://localhost:3000')
 await mockPool.close()
 ```
 
-### `MockPool.dispatch(options, handlers)`
+### `mockPool.dispatch(options, handlers)`
+
+<!-- YAML
+added: v4.0.0
+-->
+
+* `options` {DispatchOptions} The request options.
+* `handlers` {DispatchHandler} The handlers invoked over the request lifecycle.
+* Returns: {boolean} `false` if the dispatcher is busy and the caller should
+  wait before dispatching further requests, otherwise `true`.
+
+Dispatches a request, matching it against the registered mocks. This override of
+[`dispatcher.dispatch(options, handlers)`][] is what drives the mocking
+behaviour for every higher-level method such as `request`.
 
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+### `mockPool.request(options[, callback])`
 
-### `MockPool.request(options[, callback])`
+<!-- YAML
+added: v4.0.0
+-->
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+* `options` {DispatchOptions}
+* `callback` {Function} (optional) Invoked with the response when no `Promise`
+  is requested.
+* Returns: {Promise} Fulfills with the mocked response when no `callback` is
+  provided.
 
-#### Example - MockPool request
+Performs a request and resolves it against the registered mocks. Inherited from
+[`Pool`][]; see [`dispatcher.request(options[, callback])`][] for the full
+parameter and return value documentation.
 
-```js
+```mjs
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
-
 const mockPool = mockAgent.get('http://localhost:3000')
-mockPool.intercept({
-  path: '/foo',
-  method: 'GET',
-}).reply(200, 'foo')
+mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
 
-const {
-  statusCode,
-  body
-} = await mockPool.request({
+const { statusCode, body } = await mockPool.request({
   origin: 'http://localhost:3000',
   path: '/foo',
   method: 'GET'
@@ -548,8 +560,32 @@ for await (const data of body) {
 }
 ```
 
-### `MockPool.cleanMocks()`
+### `mockPool.cleanMocks()`
+
+<!-- YAML
+added: v7.11.0
+-->
+
+* Returns: {undefined}
+
+Removes all registered interceptors from the mock pool. Pending mocks defined
+before this call no longer match incoming requests.
 
-This method cleans up all the prepared mocks.
+```mjs
+import { MockAgent } from 'undici'
+
+const mockAgent = new MockAgent()
+const mockPool = mockAgent.get('http://localhost:3000')
+
+mockPool.intercept({ path: '/foo' }).reply(200, 'foo')
+mockPool.cleanMocks()
+```
 
-Returns: `void`
+[`MockAgent`]: MockAgent.md#class-mockagent
+[`MockClient`]: MockClient.md#class-mockclient
+[`MockInterceptor`]: MockPool.md#return-mockinterceptor
+[`MockScope`]: MockPool.md#return-mockscope
+[`Pool`]: Pool.md#class-pool
+[`dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
+[`dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
+[`mockAgent.get(origin)`]: MockAgent.md#mockagentgetorigin