@yanglaofish/fishtools 0.5.1 → 0.5.3

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

@@ -1,210 +1,108 @@
-# MockPool
+# Class: MockPool
 
-<!--introduced_in=v4.0.0-->
-<!--type=module-->
-<!-- source_link=lib/mock/mock-pool.js -->
+Extends: `undici.Pool`
 
-> Stability: 2 - Stable
+A mock Pool class that implements the Pool API and is used by MockAgent to intercept real requests and return mocked responses.
 
-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`][].
+## `new MockPool(origin, [options])`
 
-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.
+Arguments:
 
-```mjs
+* **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')
 ```
 
-```cjs
-const { MockAgent } = require('undici')
+## Instance Methods
 
-const mockAgent = new MockAgent()
-const mockPool = mockAgent.get('http://localhost:3000')
-```
+### `MockPool.intercept(options)`
 
-## Class: `MockPool`
+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.
 
-<!-- YAML
-added: v4.0.0
--->
+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.
 
-* Extends: {Pool}
+| Matcher type | Condition to pass          |
+|:------------:| -------------------------- |
+| `string`     | Exact match against string |
+| `RegExp`     | Regex must pass            |
+| `Function`   | Function must return true  |
 
-Extends [`Pool`][] and implements the `Interceptable` interface, allowing
-requests made through it to be matched against registered mocks.
+Arguments:
 
-### `new MockPool(origin[, options])`
+* **options** `MockPoolInterceptOptions` - Interception options.
 
-<!-- YAML
-added: v4.0.0
--->
+Returns: `MockInterceptor` corresponding to the input options.
 
-* `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}
+### Parameter: `MockPoolInterceptOptions`
 
-The `agent` option is required and must implement the `Agent` interface;
-otherwise an `InvalidArgumentError` is thrown.
+* **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`.
 
-#### Parameter: `MockPoolOptions`
+### Return: `MockInterceptor`
 
-Extends: `PoolOptions`
+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`
 
-* `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. The callback may be asynchronous; a returned promise is awaited
-    and must resolve to the same shape.
-  * 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"
+* **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')
+const {
+  statusCode,
+  body
+} = await request('http://localhost:3000/foo')
 
 console.log('response received', statusCode) // response received 200
 
@@ -213,7 +111,9 @@ for await (const data of body) {
 }
 ```
 
-```mjs displayName="Reply with a data callback"
+#### Example - Mocked request using reply data callbacks
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -223,21 +123,30 @@ const mockPool = mockAgent.get('http://localhost:3000')
 
 mockPool.intercept({
   path: '/echo',
-  method: 'GET'
-}).reply(200, ({ headers }) => ({ message: headers.message }))
+  method: 'GET',
+  headers: {
+    'User-Agent': 'undici',
+    Host: 'example.com'
+  }
+}).reply(200, ({ headers }) => ({ message: headers.get('message') }))
 
-const { statusCode, body } = await request('http://localhost:3000/echo', {
-  headers: { message: 'hello world!' }
+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!"}
+  console.log('data', data.toString('utf8')) // { "message":"hello world!" }
 }
 ```
 
-```mjs displayName="Reply with an options callback"
+#### Example - Mocked request using reply options callback
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -247,25 +156,30 @@ const mockPool = mockAgent.get('http://localhost:3000')
 
 mockPool.intercept({
   path: '/echo',
-  method: 'GET'
-}).reply(({ headers }) => ({
-  statusCode: 200,
-  data: { message: headers.message }
-}))
+  method: 'GET',
+  headers: {
+    'User-Agent': 'undici',
+    Host: 'example.com'
+  }
+}).reply(({ headers }) => ({ statusCode: 200, data: { message: headers.get('message') }})))
 
-const { statusCode, body } = await request('http://localhost:3000/echo', {
-  headers: { message: 'hello world!' }
+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!"}
+  console.log('data', data.toString('utf8')) // { "message":"hello world!" }
 }
 ```
 
-```mjs displayName="Reply with an asynchronous options callback"
-import { readFile } from 'node:fs/promises'
+#### Example - Basic Mocked requests with multiple intercepts
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -274,45 +188,35 @@ setGlobalDispatcher(mockAgent)
 const mockPool = mockAgent.get('http://localhost:3000')
 
 mockPool.intercept({
-  path: '/fixture',
+  path: '/foo',
   method: 'GET'
-}).reply(async ({ path }) => ({
-  statusCode: 200,
-  data: await readFile(new URL('./fixture.json', import.meta.url))
-}))
-
-const { statusCode, body } = await request('http://localhost:3000/fixture')
-
-console.log('response received', statusCode) // response received 200
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // contents of fixture.json
-}
-```
-
-```mjs displayName="Multiple intercepts"
-import { MockAgent, setGlobalDispatcher, request } from 'undici'
+}).reply(200, 'foo')
 
-const mockAgent = new MockAgent()
-setGlobalDispatcher(mockAgent)
+mockPool.intercept({
+  path: '/hello',
+  method: 'GET',
+}).reply(200, 'hello')
 
-const mockPool = mockAgent.get('http://localhost:3000')
+const result1 = await request('http://localhost:3000/foo')
 
-mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo')
-mockPool.intercept({ path: '/hello', method: 'GET' }).reply(200, 'hello')
+console.log('response received', result1.statusCode) // response received 200
 
-const fooResult = await request('http://localhost:3000/foo')
-for await (const data of fooResult.body) {
+for await (const data of result1.body) {
   console.log('data', data.toString('utf8')) // data foo
 }
 
-const helloResult = await request('http://localhost:3000/hello')
-for await (const data of helloResult.body) {
+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
 }
 ```
 
-```mjs displayName="Match query, body, request headers; reply with headers and trailers"
+#### Example - Mocked request with query body, request headers and response headers and trailers
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -333,9 +237,12 @@ 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: {
@@ -343,20 +250,21 @@ const { statusCode, headers, trailers, body } = await request(
       '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' }
 ```
 
-```mjs displayName="Different matcher forms"
+#### Example - Mocked request using different matchers
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -370,11 +278,14 @@ 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: {
@@ -391,7 +302,9 @@ for await (const data of body) {
 }
 ```
 
-```mjs displayName="Reply with an error"
+#### Example - Mocked request with reply with a defined error
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -405,13 +318,17 @@ 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.message) // kaboom
+  console.error(error) // Error: kaboom
 }
 ```
 
-```mjs displayName="Default reply headers"
+#### Example - Mocked request with defaultReplyHeaders
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -419,8 +336,10 @@ 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')
@@ -428,7 +347,9 @@ const { headers } = await request('http://localhost:3000/foo')
 console.log('headers', headers) // headers { foo: 'bar' }
 ```
 
-```mjs displayName="Default reply trailers"
+#### Example - Mocked request with defaultReplyTrailers
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -436,8 +357,10 @@ 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')
@@ -445,7 +368,9 @@ const { trailers } = await request('http://localhost:3000/foo')
 console.log('trailers', trailers) // trailers { foo: 'bar' }
 ```
 
-```mjs displayName="Automatic content-length"
+#### Example - Mocked request with automatic content-length calculation
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -453,16 +378,19 @@ 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' }
 ```
 
-```mjs displayName="Persisted reply"
+#### Example - Mocked request with automatic content-length calculation on an object
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -470,13 +398,19 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').persist()
+mockPool.intercept({
+  path: '/foo',
+  method: 'GET'
+}).replyContentLength().reply(200, { foo: 'bar' })
+
+const { headers } = await request('http://localhost:3000/foo')
 
-await request('http://localhost:3000/foo') // Matches and returns the mock
-await request('http://localhost:3000/foo') // Matches again, indefinitely
+console.log('headers', headers) // headers { 'content-length': '13' }
 ```
 
-```mjs displayName="Reply a fixed number of times"
+#### Example - Mocked request with persist enabled
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -484,23 +418,57 @@ setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-mockPool.intercept({ path: '/foo', method: 'GET' }).reply(200, 'foo').times(2)
+mockPool.intercept({
+  path: '/foo',
+  method: 'GET'
+}).reply(200, 'foo').persist()
+
+const result1 = await request('http://localhost:3000/foo')
+// Will match and return mocked data
 
-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
+const result2 = await request('http://localhost:3000/foo')
+// Will match and return mocked data
+
+// Etc
 ```
 
-```mjs displayName="Match the path with a function"
+#### Example - Mocked request with times enabled
+
+```js
 import { MockAgent, setGlobalDispatcher, request } from 'undici'
-import querystring from 'node:querystring'
 
 const mockAgent = new MockAgent()
 setGlobalDispatcher(mockAgent)
 
 const mockPool = mockAgent.get('http://localhost:3000')
 
-const matchPath = (requestPath) => {
+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)
 
@@ -508,26 +476,31 @@ const matchPath = (requestPath) => {
     return false
   }
 
-  return requestQuery.foo === 'bar'
+  if (!Object.keys(requestQuery).includes('foo') || requestQuery.foo !== 'bar') {
+    return false
+  }
+
+  return true
 }
 
-mockPool.intercept({ path: matchPath, method: 'GET' }).reply(200, 'foo')
+mockPool.intercept({
+  path: matchPath,
+  method: 'GET'
+}).reply(200, 'foo')
 
-await request('http://localhost:3000/foo?foo=bar') // Matches and returns the mock
+const result = await request('http://localhost:3000/foo?foo=bar')
+// Will match and return mocked data
 ```
 
-### `mockPool.close()`
+### `MockPool.close()`
 
-<!-- YAML
-added: v4.0.0
--->
+Closes the mock pool and de-registers from associated MockAgent.
 
-* Returns: {Promise} Fulfills with `undefined` once the mock pool is closed.
+Returns: `Promise<void>`
 
-Closes the mock pool, gracefully waiting for any enqueued requests to complete,
-and removes it from the associated [`MockAgent`][].
+#### Example - clean up after tests are complete
 
-```mjs
+```js
 import { MockAgent } from 'undici'
 
 const mockAgent = new MockAgent()
@@ -536,45 +509,31 @@ const mockPool = mockAgent.get('http://localhost:3000')
 await mockPool.close()
 ```
 
-### `mockPool.dispatch(options, handlers)`
-
-<!-- YAML
-added: v4.0.0
--->
+### `MockPool.dispatch(options, handlers)`
 
-* `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`.
+Implements [`Dispatcher.dispatch(options, handlers)`](Dispatcher.md#dispatcherdispatchoptions-handler).
 
-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`.
+### `MockPool.request(options[, callback])`
 
-### `mockPool.request(options[, callback])`
+See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).
 
-<!-- YAML
-added: v4.0.0
--->
+#### Example - MockPool request
 
-* `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.
-
-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.
-
-```mjs
+```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')
+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'
@@ -586,33 +545,3 @@ for await (const data of body) {
   console.log('data', data.toString('utf8')) // data foo
 }
 ```
-
-### `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.
-
-```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()
-```
-
-[`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