{
  "type": "module",
  "source": "doc/api/api-mockcallhistory.md",
  "modules": [
    {
      "textRaw": "MockCallHistory",
      "name": "mockcallhistory",
      "introduced_in": "v7.5.0",
      "type": "module",
      "stability": 2,
      "stabilityText": "Stable",
      "desc": "<p>A <code>MockCallHistory</code> records the configuration of every request intercepted by a\n<a href=\"MockAgent.html#class-mockagent\"><code>MockAgent</code></a> for which call history is enabled. Each recorded request is\nstored as a <a href=\"MockCallHistoryLog.html#class-mockcallhistorylog\"><code>MockCallHistoryLog</code></a>, and the <code>MockCallHistory</code> exposes helpers\nto read and filter those logs in tests.</p>\n<p>Instances are not created directly. Enable call history on a <a href=\"MockAgent.html#class-mockagent\"><code>MockAgent</code></a> and\nretrieve the history with <code>mockAgent.getCallHistory()</code>:</p>\n<pre><code class=\"language-mjs\">import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent({ enableCallHistory: true })\nconst callHistory = mockAgent.getCallHistory()\n</code></pre>\n<p>Call history can also be enabled after construction:</p>\n<pre><code class=\"language-mjs\">import { MockAgent } from 'undici'\n\nconst mockAgent = new MockAgent()\nmockAgent.enableCallHistory()\nconst callHistory = mockAgent.getCallHistory()\n</code></pre>",
      "classes": [
        {
          "textRaw": "Class: `MockCallHistory`",
          "name": "MockCallHistory",
          "type": "class",
          "meta": {
            "added": [
              "v7.5.0"
            ],
            "changes": []
          },
          "desc": "<p>Tracks the configuration of intercepted requests as an ordered collection of\n<a href=\"MockCallHistoryLog.html#class-mockcallhistorylog\"><code>MockCallHistoryLog</code></a> entries.</p>\n<p>A <code>MockCallHistory</code> is iterable. Use it with a <code>for...of</code> loop, the spread\noperator, or any constructor that accepts an iterable:</p>\n<pre><code class=\"language-mjs\">for (const log of mockAgent.getCallHistory()) {\n  // ...\n}\n\nconst logs = [...mockAgent.getCallHistory()]\nconst logSet = new Set(mockAgent.getCallHistory())\n</code></pre>",
          "methods": [
            {
              "textRaw": "`mockCallHistory.calls()`",
              "name": "calls",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] All recorded logs, in the order the requests were intercepted.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] All recorded logs, in the order the requests were intercepted."
                  }
                }
              ],
              "desc": "<p>Returns every recorded <a href=\"MockCallHistoryLog.html#class-mockcallhistorylog\"><code>MockCallHistoryLog</code></a> as an array.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.calls()\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.firstCall()`",
              "name": "firstCall",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog|undefined} The first recorded log, or `undefined` when no request has been recorded.",
                    "name": "return",
                    "type": "MockCallHistoryLog|undefined",
                    "desc": "The first recorded log, or `undefined` when no request has been recorded."
                  }
                }
              ],
              "desc": "<p>Returns the first recorded <a href=\"MockCallHistoryLog.html#class-mockcallhistorylog\"><code>MockCallHistoryLog</code></a>.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.firstCall()\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.lastCall()`",
              "name": "lastCall",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog|undefined} The last recorded log, or `undefined` when no request has been recorded.",
                    "name": "return",
                    "type": "MockCallHistoryLog|undefined",
                    "desc": "The last recorded log, or `undefined` when no request has been recorded."
                  }
                }
              ],
              "desc": "<p>Returns the last recorded <a href=\"MockCallHistoryLog.html#class-mockcallhistorylog\"><code>MockCallHistoryLog</code></a>.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.lastCall()\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.nthCall(position)`",
              "name": "nthCall",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`position` {number} The 1-based position of the log to return. Must be a positive integer.",
                      "name": "position",
                      "type": "number",
                      "desc": "The 1-based position of the log to return. Must be a positive integer."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog|undefined} The log at `position`, or `undefined` when no log exists at that position.",
                    "name": "return",
                    "type": "MockCallHistoryLog|undefined",
                    "desc": "The log at `position`, or `undefined` when no log exists at that position."
                  }
                }
              ],
              "desc": "<p>Returns the <a href=\"MockCallHistoryLog.html#class-mockcallhistorylog\"><code>MockCallHistoryLog</code></a> at the given 1-based <code>position</code>. The index\nis 1-based for readability, so <code>nthCall(1)</code> is equivalent to <code>firstCall()</code>.</p>\n<p>Throws an <a href=\"Errors.html#class-invalidargumenterror\"><code>InvalidArgumentError</code></a> when <code>position</code> is not a number, not an\ninteger, or not positive. Use <code>firstCall()</code> or <code>lastCall()</code> instead of passing a\nnon-positive value.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.nthCall(3) // the third recorded log\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCalls(criteria[, options])`",
              "name": "filterCalls",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {Function|RegExp|Object} The filter to apply.When a {Function} is given, it is used as the predicate of `Array.prototype.filter` and receives each `MockCallHistoryLog`; logs for which it returns a truthy value are kept.When a {RegExp} is given, a log is kept when the expression matches its `mockCallHistoryLog.toString()` representation.When an {Object} is given, each property is a request field to filter on and each value is a filter parameter. An empty object returns every log.`protocol` {string|RegExp|null|undefined} Filters by request protocol.`host` {string|RegExp|null|undefined} Filters by request host.`port` {string|RegExp|null|undefined} Filters by request port.`origin` {string|RegExp|null|undefined} Filters by request origin.`path` {string|RegExp|null|undefined} Filters by request path.`hash` {string|RegExp|null|undefined} Filters by request hash.`fullUrl` {string|RegExp|null|undefined} Filters by request full URL.`method` {string|RegExp|null|undefined} Filters by request method.",
                      "name": "criteria",
                      "type": "Function|RegExp|Object",
                      "desc": "The filter to apply.When a {Function} is given, it is used as the predicate of `Array.prototype.filter` and receives each `MockCallHistoryLog`; logs for which it returns a truthy value are kept.When a {RegExp} is given, a log is kept when the expression matches its `mockCallHistoryLog.toString()` representation.When an {Object} is given, each property is a request field to filter on and each value is a filter parameter. An empty object returns every log.`protocol` {string|RegExp|null|undefined} Filters by request protocol.`host` {string|RegExp|null|undefined} Filters by request host.`port` {string|RegExp|null|undefined} Filters by request port.`origin` {string|RegExp|null|undefined} Filters by request origin.`path` {string|RegExp|null|undefined} Filters by request path.`hash` {string|RegExp|null|undefined} Filters by request hash.`fullUrl` {string|RegExp|null|undefined} Filters by request full URL.`method` {string|RegExp|null|undefined} Filters by request method."
                    },
                    {
                      "textRaw": "`options` {Object} Adjusts the filtering behavior. Only applied when `criteria` is an object. (optional)",
                      "name": "options",
                      "type": "Object",
                      "desc": "Adjusts the filtering behavior. Only applied when `criteria` is an object. (optional)",
                      "options": [
                        {
                          "textRaw": "`operator` {string} How to combine multiple object properties. `'OR'` keeps a log matching any criterion; `'AND'` keeps a log matching every criterion. The value is case-insensitive. **Default:** `'OR'`.",
                          "name": "operator",
                          "type": "string",
                          "default": "`'OR'`",
                          "desc": "How to combine multiple object properties. `'OR'` keeps a log matching any criterion; `'AND'` keeps a log matching every criterion. The value is case-insensitive."
                        }
                      ],
                      "optional": true
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The matching logs. Duplicates produced by an `'OR'` combination are removed.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The matching logs. Duplicates produced by an `'OR'` combination are removed."
                  }
                }
              ],
              "desc": "<p>A convenience method for applying one or several filters at once. It is a more\nexpressive alternative to the per-field helpers below.</p>\n<p>Throws an <a href=\"Errors.html#class-invalidargumenterror\"><code>InvalidArgumentError</code></a> when <code>criteria</code> is not a function, regular\nexpression, or object, or when <code>options.operator</code> is neither <code>'OR'</code> nor <code>'AND'</code>.</p>\n<pre><code class=\"language-mjs\">const callHistory = mockAgent.getCallHistory()\n\ncallHistory?.filterCalls((log) =>\n  log.hash === '#hash' &#x26;&#x26; log.headers?.authorization !== undefined)\n\ncallHistory?.filterCalls(/\"errors\": \"wrong body\"/)\n\n// Logs with a hash containing `my-hash` OR a path equal to `/endpoint`.\ncallHistory?.filterCalls({ hash: /my-hash/, path: '/endpoint' })\n\n// Logs with a hash containing `my-hash` AND a path equal to `/endpoint`.\ncallHistory?.filterCalls(\n  { hash: /my-hash/, path: '/endpoint' },\n  { operator: 'AND' }\n)\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCallsByProtocol(criteria)`",
              "name": "filterCallsByProtocol",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {string|RegExp|null|undefined} See filter parameter.",
                      "name": "criteria",
                      "type": "string|RegExp|null|undefined",
                      "desc": "See filter parameter."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The logs whose protocol matches `criteria`.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The logs whose protocol matches `criteria`."
                  }
                }
              ],
              "desc": "<p>Filters the recorded logs by request protocol.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.filterCallsByProtocol(/https/)\nmockAgent.getCallHistory()?.filterCallsByProtocol('https:')\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCallsByHost(criteria)`",
              "name": "filterCallsByHost",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {string|RegExp|null|undefined} See filter parameter.",
                      "name": "criteria",
                      "type": "string|RegExp|null|undefined",
                      "desc": "See filter parameter."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The logs whose host matches `criteria`.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The logs whose host matches `criteria`."
                  }
                }
              ],
              "desc": "<p>Filters the recorded logs by request host.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.filterCallsByHost(/localhost/)\nmockAgent.getCallHistory()?.filterCallsByHost('localhost:3000')\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCallsByPort(criteria)`",
              "name": "filterCallsByPort",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {string|RegExp|null|undefined} See filter parameter.",
                      "name": "criteria",
                      "type": "string|RegExp|null|undefined",
                      "desc": "See filter parameter."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The logs whose port matches `criteria`.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The logs whose port matches `criteria`."
                  }
                }
              ],
              "desc": "<p>Filters the recorded logs by request port.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.filterCallsByPort(/3000/)\nmockAgent.getCallHistory()?.filterCallsByPort('3000')\nmockAgent.getCallHistory()?.filterCallsByPort('')\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCallsByOrigin(criteria)`",
              "name": "filterCallsByOrigin",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {string|RegExp|null|undefined} See filter parameter.",
                      "name": "criteria",
                      "type": "string|RegExp|null|undefined",
                      "desc": "See filter parameter."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The logs whose origin matches `criteria`.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The logs whose origin matches `criteria`."
                  }
                }
              ],
              "desc": "<p>Filters the recorded logs by request origin.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.filterCallsByOrigin(/http:\\/\\/localhost:3000/)\nmockAgent.getCallHistory()?.filterCallsByOrigin('http://localhost:3000')\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCallsByPath(criteria)`",
              "name": "filterCallsByPath",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {string|RegExp|null|undefined} See filter parameter.",
                      "name": "criteria",
                      "type": "string|RegExp|null|undefined",
                      "desc": "See filter parameter."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The logs whose path matches `criteria`.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The logs whose path matches `criteria`."
                  }
                }
              ],
              "desc": "<p>Filters the recorded logs by request path.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.filterCallsByPath(/api\\/v1\\/graphql/)\nmockAgent.getCallHistory()?.filterCallsByPath('/api/v1/graphql')\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCallsByHash(criteria)`",
              "name": "filterCallsByHash",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {string|RegExp|null|undefined} See filter parameter.",
                      "name": "criteria",
                      "type": "string|RegExp|null|undefined",
                      "desc": "See filter parameter."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The logs whose hash matches `criteria`.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The logs whose hash matches `criteria`."
                  }
                }
              ],
              "desc": "<p>Filters the recorded logs by request hash.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.filterCallsByHash(/hash/)\nmockAgent.getCallHistory()?.filterCallsByHash('#hash')\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCallsByFullUrl(criteria)`",
              "name": "filterCallsByFullUrl",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {string|RegExp|null|undefined} See filter parameter.",
                      "name": "criteria",
                      "type": "string|RegExp|null|undefined",
                      "desc": "See filter parameter."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The logs whose full URL matches `criteria`.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The logs whose full URL matches `criteria`."
                  }
                }
              ],
              "desc": "<p>Filters the recorded logs by request full URL. The full URL contains the\nprotocol, host, port, path, query parameters, and hash.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.filterCallsByFullUrl(/https:\\/\\/localhost:3000\\/\\?query=value#hash/)\nmockAgent.getCallHistory()?.filterCallsByFullUrl('https://localhost:3000/?query=value#hash')\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.filterCallsByMethod(criteria)`",
              "name": "filterCallsByMethod",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [
                    {
                      "textRaw": "`criteria` {string|RegExp|null|undefined} See filter parameter.",
                      "name": "criteria",
                      "type": "string|RegExp|null|undefined",
                      "desc": "See filter parameter."
                    }
                  ],
                  "return": {
                    "textRaw": "Returns: {MockCallHistoryLog}[] The logs whose method matches `criteria`.",
                    "name": "return",
                    "type": "MockCallHistoryLog",
                    "desc": "[] The logs whose method matches `criteria`."
                  }
                }
              ],
              "desc": "<p>Filters the recorded logs by request method.</p>\n<pre><code class=\"language-mjs\">mockAgent.getCallHistory()?.filterCallsByMethod(/POST/)\nmockAgent.getCallHistory()?.filterCallsByMethod('POST')\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory.clear()`",
              "name": "clear",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [],
                  "return": {
                    "textRaw": "Returns: {undefined}",
                    "name": "return",
                    "type": "undefined"
                  }
                }
              ],
              "desc": "<p>Removes every recorded <a href=\"MockCallHistoryLog.html#class-mockcallhistorylog\"><code>MockCallHistoryLog</code></a>. This is performed\nautomatically when <code>mockAgent.close()</code> is called.</p>\n<pre><code class=\"language-mjs\">mockAgent.clearCallHistory()\n// Equivalent to:\nmockAgent.getCallHistory()?.clear()\n</code></pre>"
            },
            {
              "textRaw": "`mockCallHistory[Symbol.iterator]()`",
              "name": "[Symbol.iterator]",
              "type": "method",
              "meta": {
                "added": [
                  "v7.5.0"
                ],
                "changes": []
              },
              "signatures": [
                {
                  "params": [],
                  "return": {
                    "textRaw": "Returns: {Generator} A generator yielding each recorded `MockCallHistoryLog` in order.",
                    "name": "return",
                    "type": "Generator",
                    "desc": "A generator yielding each recorded `MockCallHistoryLog` in order."
                  }
                }
              ],
              "desc": "<p>Makes a <code>MockCallHistory</code> iterable, yielding the same logs returned by\n<code>calls()</code>. This enables <code>for...of</code> iteration, the spread operator, and\nconstructing other iterables from a history.</p>\n<pre><code class=\"language-mjs\">const callHistory = mockAgent.getCallHistory()\n\nfor (const log of callHistory) {\n  console.log(log.method, log.fullUrl)\n}\n\nconst logs = [...callHistory]\n</code></pre>"
            }
          ]
        }
      ],
      "modules": [
        {
          "textRaw": "Filter parameter",
          "name": "filter_parameter",
          "type": "module",
          "desc": "<p>The per-field <code>filterCallsBy*</code> helpers and the object form of <code>filterCalls()</code>\naccept a filter parameter that is matched against the corresponding field of each\n<a href=\"MockCallHistoryLog.html#class-mockcallhistorylog\"><code>MockCallHistoryLog</code></a>:</p>\n<ul>\n<li>A <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Data_structures#string_type\"><code>&#x3C;string></code></a> keeps a log only when the field is strictly equal to the value.</li>\n<li><code>null</code> keeps a log only when the field is strictly equal to <code>null</code>.</li>\n<li><code>undefined</code> keeps a log only when the field is strictly equal to <code>undefined</code>.</li>\n<li>A <a href=\"https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp\"><code>&#x3C;RegExp></code></a> keeps a log only when the expression matches the field.</li>\n</ul>\n<p>Any other value throws an <a href=\"Errors.html#class-invalidargumenterror\"><code>InvalidArgumentError</code></a>.</p>",
          "displayName": "Filter parameter"
        }
      ]
    }
  ]
}