Fetch Mock

https://github.com/wheresrhys/fetch-mock
Admin
Fetch Mock is a comprehensive library for mocking HTTP requests made using the fetch API, supporting...
Tokens:12,539
Snippets:209
Trust Score:8.8
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install @fetch-mock/vitest

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/vitest.md

Install the package as a development dependency.

```shell
npm i -D @fetch-mock/vitest
```

--------------------------------

### Install dependencies

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/README.md

Run this command to install all project dependencies.

```bash
$ yarn
```

--------------------------------

### Start local development server

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/README.md

Launches a local server with live reloading for development.

```bash
$ yarn start
```

--------------------------------

### Install @fetch-mock/jest

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/jest.md

Install the package as a development dependency.

```shell
npm i -D @fetch-mock/jest
```

--------------------------------

### Query Parameter Matching Examples

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/matcher.md

Examples demonstrating how query objects are matched against request query strings, including support for arrays and undefined values.

```js
{query: "q": "cute+kittenz"}
```

```js
{query: "tags": ["cute", "kittenz"]}
```

```js
{query: "q": undefined, inform: true}
```

--------------------------------

### Setup fetch-mock with Vitest

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/vitest.md

Import the fetchMock instance and optionally enable global mock management.

```javascript
import fetchMock, { manageFetchMockGlobally } from '@fetch-mock/vitest';

manageFetchMockGlobally(); // optional
```

--------------------------------

### Install fetch-mock via npm

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/installation.md

Use this command to add fetch-mock as a development dependency in your project.

```bash
npm install --save-dev fetch-mock
```

--------------------------------

### End to End Route Example

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Demonstrates setting up specific routes and verifying the response using an expectation.

```javascript
fetchMock.route('begin:http://it.at.here/api', 403).route(
	{
		url: 'begin:http://it.at.here/api',
		headers: {
			authorization: 'Basic dummy-token',
		},
	},
	200,
);

callApi('/endpoint', 'dummy-token').then((res) => {
	expect(res.status).to.equal(200);
});
```

--------------------------------

### Before manual adjustment

Source: https://github.com/wheresrhys/fetch-mock/blob/main/packages/codemods/README.md

Initial setup using fetch-mock sandbox() directly within a jest.mock call.

```js
jest.mock('node-fetch', () => require('fetch-mock').sandbox());

const nodeFetch = require('node-fetch');

it('runs a test', () => {
	nodeFetch.get('http://a.com', 200);
	myAPI.call();
	expect(nodeFetch.called()).toBe(true);
});
```

--------------------------------

### After manual adjustment

Source: https://github.com/wheresrhys/fetch-mock/blob/main/packages/codemods/README.md

Refactored setup that explicitly assigns fetch and related classes to the fetch-mock configuration.

```js
const fetchMock = require('fetch-mock');

jest.mock('node-fetch', () => {
	const nodeFetch = jest.requireActual('node-fetch');
	// only needed if your application makes use of Response, Request
	// or Headers classes directly
	Object.assign(fetchMock.config, {
		fetch: nodeFetch,
		Response: nodeFetch.Response,
		Request: nodeFetch.Request,
		Headers: nodeFetch.Headers,
	});
	return fetchMock.fetchHandler;
});
const nodeFetch = require('node-fetch');

it('runs a test', () => {
	fetchMock.get('http://a.com', 200);
	myAPI.call();
	expect(fetchMock.called()).toBe(true);
});
```

--------------------------------

### Body Matching Examples

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/matcher.md

Examples of matching request bodies using JSON objects or FormData instances.

```js
{body: { "key1": "value1", "key2": "value2" }}
new FormData(document.querySelector('#login'))
```

--------------------------------

### Setup fetch-mock with Jest

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/jest.md

Import the wrapper and optionally hook it into Jest's global mock management.

```js
import fetchMock, { manageFetchMockGlobally } from '@fetch-mock/jest';
import { jest } from '@jest/globals';

manageFetchMockGlobally(jest); // optional
```

--------------------------------

### Dynamic response function examples

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/response.md

Examples of functions that return status codes based on request properties.

```js
({url, options}) => options.headers.Authorization ? 200 : 403
```

```js
({request}) => request.headers.get('Authorization') ?  200 : 403
```

--------------------------------

### Combine URL and Method Matchers

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/matcher.md

Example of combining a URL prefix matcher with an HTTP method requirement.

```js
{
	url: "begin: https://my.site",
	method: 'post'
}
```

--------------------------------

### Response Configurations

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Examples of different response types including strings, status codes, objects, errors, promises, and functions.

```javascript
fetchMock
  .route('*', 'ok')
  .route('*', 404)
  .route('*', {results: []})
  .route('*', {throws: new Error('Bad kitty')})
  .route('*', new Promise(res => setTimeout(res, 1000, 404)))
  .route('*', (url, opts) => {
    status: 302,
    headers: {
      Location: url.replace(/^http/, 'https')
    },
  }))
```

--------------------------------

### Custom Function Matcher Examples

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/matcher.md

These functions demonstrate how to inspect headers from either the options object or the Request instance to determine if a route should match.

```javascript
(url, {headers}) => !!headers.Authorization
```

```javascript
(_, _, request) => !!request.headers.get('Authorization')
```

--------------------------------

### Unsupported sandbox assignment pattern

Source: https://github.com/wheresrhys/fetch-mock/blob/main/packages/codemods/README.md

Example of a complex assignment pattern that the codemod cannot identify as a fetch-mock instance.

```javascript
jest.mock('node-fetch', () => require('fetch-mock').sandbox())
```

--------------------------------

### Unsupported direct usage pattern

Source: https://github.com/wheresrhys/fetch-mock/blob/main/packages/codemods/README.md

Example of a pattern that the codemod cannot automatically modify because the instance is not assigned to a variable.

```javascript
require('fetch-mock').mock('a', 'b')
```

--------------------------------

### .anyOnce(response, options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Creates a route that responds to any single request.

```APIDOC
## .anyOnce(response, options)

### Description
Creates a route that responds to any single request.

### Parameters
- **response** (any) - The response to return.
- **options** (object) - Configuration options for the route.
```

--------------------------------

### Mock request and execute

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/quickstart.md

Configure a mock with specific matchers and options, then execute the request.

```javascript
import { makeRequest } from './make-request';
import fetchMock from 'fetch-mock';

// Mock the fetch() global to return a response
fetchMock.mockGlobal().get(
	'http://httpbin.org/my-url',
	{ hello: 'world' },
	{
		delay: 1000, // fake a slow network
		headers: {
			user: 'me', // only match requests with certain headers
		},
	},
);

const data = await makeRequest();
console.log('got data', data);

// Unmock
fetchMock.unmockGlobal();
```

--------------------------------

### Import fetch-mock in Deno

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/installation.md

Use the npm: prefix to import fetch-mock within a Deno environment.

```js
import fetchMock from 'npm:fetch-mock@12.3.0';
```

--------------------------------

### .any()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Creates a route that will return a response to any fetch request.

```APIDOC
## .any(response, options)

### Description
Shorthand for mock() which creates a route that matches any fetch request.

### Parameters
- **response** (any) - Required - The response to return.
- **options** (object) - Optional - Configuration options for the route.
```

--------------------------------

### Import fetch-mock in ES modules

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/installation.md

Standard import syntax for projects using ES modules.

```js
import fetchMock from 'fetch-mock';
```

--------------------------------

### Build static content

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/README.md

Compiles the website into static files located in the build directory.

```bash
$ yarn build
```

--------------------------------

### Import fetch-mock

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/quickstart.md

Import the library using either ES modules or CommonJS syntax.

```javascript
import fetchMock from 'fetch-mock';
```

```javascript
const fetchMock = require('fetch-mock');
```

--------------------------------

### Execute project development commands

Source: https://github.com/wheresrhys/fetch-mock/blob/main/CLAUDE.md

Common CLI commands for building, testing, and linting the monorepo packages.

```bash
# Build all packages
npm run build

# Build a single package
npm run build -w packages/fetch-mock

# Lint (auto-fixes)
npm run lint

# Type-check
npm run types:check

# Run tests (Vitest, interactive UI) — excludes jest-specific tests
npm test

# Run tests in CI mode (no UI, with coverage and junit output)
npm run test:ci

# Run tests in browser (Chromium via Playwright)
npm run test:browser

# Run Jest-specific package tests
npm run test:jest

# Run a single test file
npx vitest packages/fetch-mock/src/__tests__/FetchMock/routing.test.js

# Run import compatibility checks
npm run compat:module -w import-compat
```

--------------------------------

### Create an independent fetch-mock instance

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/resetting.md

Demonstrates creating a new instance where routes are cloned but call history is reset.

```js
fetchMock.route('http://my.site', 200);
fetchMock.fetchHandler('http://my.site');

const newFM = fetchMock.createInstance();

newFM.routes.routes; // Array[1]
newFM.callHistory.calls(); // Array[0]
```

--------------------------------

### Mocking fetch in Jest with @fetch-mock/core

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/blog/2024-07-20-new-beginnings.md

Demonstrates how to integrate the core fetch-mock handler with Jest's mocking system.

```js
import fetchMock from '@fetch-mock/core'
jest.mock(global, 'fetch', fetchMock.fetchHandler)

it('works just fine', () => {
	fetchMock.route('http://here.com', 200);
	await expect (fetch('http://here.com')).resolves
})
```

--------------------------------

### Import fetch-mock in CommonJS

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/installation.md

Standard require syntax for projects using CommonJS.

```js
const fetchMock = require('fetch-mock');
```

--------------------------------

### Run mocked script

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/quickstart.md

Execute the script using Node.js.

```bash
$ node mocked.js
'got data' { hello: 'world' }
```

--------------------------------

### fetchMock.fetchHandler(url, requestInit)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/mocking-and-spying.md

A mock implementation of fetch that records calls in fetchMock.callHistory. Requires routes to be defined via .route() or .catch() to return responses.

```APIDOC
## fetchMock.fetchHandler(url, requestInit)

### Description
A mock implementation of fetch. By default it will error unless routes are added using .route() or .catch(). All calls are recorded in fetchMock.callHistory.
```

--------------------------------

### HTTP Method Shorthands

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Shorthand methods for creating routes that respond to specific HTTP methods.

```APIDOC
## .get(), .post(), .put(), .delete(), .head(), .patch()

### Description
Shorthands for mock() that create routes that only respond to requests using a particular HTTP method.

## .getOnce(), .postOnce(), .putOnce(), .deleteOnce(), .headOnce(), .patchOnce()

### Description
Creates a route that only responds to a single request using a particular HTTP method.
```

--------------------------------

### Response Configuration Options

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/response.md

The fetch-mock library allows configuring responses using various types, including Response objects, status codes, strings, objects, promises, and functions.

```APIDOC
## Response Configuration

### Response Object
- `{Response}`: A standard Web API Response instance returned unaltered.

### Status Code
- `{Int}`: Returns a Response with the specified status code and default statusText.

### String Response
- `{String}`: Returns a 200 OK Response with the provided string as the body.

### Response Config Object
- **body** (String|Object|BodyInit) - Optional - The response body content.
- **status** (Int) - Optional - The HTTP status code.
- **headers** (Object) - Optional - Key-value pairs for response headers.
- **redirectUrl** (String) - Optional - Sets the URL of origin and sets `redirected: true`.
- **throws** (Error) - Optional - Forces the fetch promise to reject with the provided error.

### Object Response
- `{Object}`: If not matching the config schema, the object is stringified as JSON and `Content-Type: application/json` is set.

### Promise
- `{Promise}`: A promise that resolves to any of the supported response types.

### Function
- `{Function}`: A function receiving a `CallLog` that returns any of the supported response types.
```

--------------------------------

### .createInstance()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/resetting.md

Creates a standalone, independent instance of fetch-mock.

```APIDOC
## .createInstance()

### Description
Can be used to create a standalone instance of fetch mock that is completely independent of other instances. It can be used as an alternative to resetting an existing instance or to fork a previous instance.
```

--------------------------------

### .sticky()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Creates a route that persists even when restore(), reset(), or resetbehavior() are called.

```APIDOC
## .sticky(matcher, response)

### Description
Shorthand for mock() which creates a route that persists through reset operations. Useful for global fixtures.
```

--------------------------------

### Configure JSDOM environment

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/jest.md

Create a custom test environment to ensure fetch-related globals are available in JSDOM.

```js
import { TestEnvironment } from 'jest-environment-jsdom';

export default class CustomTestEnvironment extends TestEnvironment {
	async setup() {
		await super.setup();

		this.global.Request = Request;
		this.global.Response = Response;
		this.global.ReadableStream = ReadableStream;
	}
}
```

--------------------------------

### Deploy to GitHub Pages

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/README.md

Commands to deploy the website to the gh-pages branch, supporting both SSH and HTTPS authentication methods.

```bash
$ USE_SSH=true yarn deploy
```

```bash
$ GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Single Options Object Configuration

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Combine matchers, options, and response into a single configuration object passed as the first parameter.

```javascript
fetchMock.route({
	url: 'http://my.site',
	repeat: 2
	response: 200
})
```

--------------------------------

### String-based Matchers

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Demonstrates various string-based matching patterns including glob-like prefixes and wildcards.

```javascript
fetchMock
	.route('http://it.at.here/route', 200)
	.route('begin:http://it', 200)
	.route('end:here/route', 200)
	.route('path:/route', 200)
	.route('*', 200);
```

--------------------------------

### Mocking global fetch with @fetch-mock/core

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/blog/2024-07-21-introducing-core.md

Demonstrates the updated approach to mocking global fetch by separating the fetch handler from the mock object, avoiding conflicts with testing frameworks like Jest.

```javascript
jest.mock(global, 'fetch', fetchMock.sandbox());
fetch.mock('http://my.site', 200);
```

```javascript
jest.mock(global, 'fetch', fetchMock.fetchHandler);
fetchMock.mock('http://my.site', 200);
```

--------------------------------

### Mock global fetch

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/quickstart.md

Replace the global fetch implementation with fetch-mock.

```javascript
fetchMock.mockGlobal();
```

--------------------------------

### Create Custom Authorization Matcher

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Define a reusable matcher to verify authorization headers based on a boolean input.

```javascript
fetchMock
	.addMatcher({
		name: 'isAuthorized',
		matcher:
			({ isAuthorized }) =>
			(url, options) => {
				const actuallyIsAuthorized = options.headers && options.headers.auth;
				return isAuthorized ? actuallyIsAuthorized : !actuallyIsAuthorized;
			},
	})
	.mock({ isAuthorized: true }, 200)
	.mock({ isAuthorized: false }, 401);
```

--------------------------------

### Implement removed convenience methods

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/upgrade-guide.md

Use the repeat option to replicate the behavior of removed once-only routing methods.

```javascript
get(url, response, {repeat: 1})
```

```javascript
get('*', response, {repeat: 1})
```

--------------------------------

### Define routes

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/quickstart.md

Chain multiple route definitions to handle different URLs and HTTP methods.

```javascript
fetchMock
	.get('http://good.com/', 200, 'good get')
	.post('http://good.com/', 400, 'good post')
	.get('http://bad.com/', 500, 'bad get');
```

--------------------------------

### spyGlobal()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/mocking-and-spying.md

Globally mocks fetch and sets it to spy mode.

```APIDOC
## spyGlobal()

### Description
Equivalent to calling .mockGlobal() followed by .spy().
```

--------------------------------

### Mock a simple HTTP request

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/index.md

Configures a global mock for a specific URL returning a 200 status code.

```js
import fetchMock from 'fetch-mock';
fetchMock.mockGlobal().route('http://example.com', 200);
const res = await fetch('http://example.com');
assert(res.ok);
```

--------------------------------

### Set global configuration options

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/configuration.md

Directly modify the fetchMock.config object to change default behavior for all mock instances.

```javascript
const fetchMock = require('fetch-mock');
fetchMock.config.matchPartialBody = false;
```

--------------------------------

### Configure custom fetch implementations

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/configuration.md

Override default fetch, Headers, Request, and Response objects by assigning them to the fetchMock.config object.

```javascript
import { default as fetch, Headers, Request, Response } from 'node-fetch';

import fetchMock from 'fetch-mock';

fetchMock.config = Object.assign(fetchMock.config, {
	Request,
	Response,
	Headers,
	fetch,
});
```

--------------------------------

### spy(matcher, name)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/mocking-and-spying.md

Configures a route to fallback to the original fetch implementation.

```APIDOC
## spy(matcher, name)

### Description
Falls back to the fetch implementation set in fetchMock.config.fetch for a specific route. If no arguments are provided, it falls back to the native fetch implementation for all requests.
```

--------------------------------

### .once()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Creates a route that can only mock a single request.

```APIDOC
## .once(matcher, response)

### Description
Shorthand for mock() which creates a route that will only match and mock a single request.
```

--------------------------------

### Use Vitest expect extensions

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/vitest.md

Use the extended expect matchers to verify fetch calls in your tests.

```javascript
expect(fetchMock).toHaveFetched(filter, options); // .toHaveBeenCalled()/.toHaveBeenCalledWith()
expect(fetchMock).toHaveLastFetched(filter, options); // .toHaveBeenLastCalledWith()
expect(fetchMock).toHaveNthFetched(n, filter, options); //  .toHaveBeenNthCalled()/.toHaveBeenNthCalledWith()
expect(fetchMock).toHaveFetchedTimes(n, filter, options); // .toHaveBeenCalledTimes()
expect(fetchMock).toBeDone(filter);
```

--------------------------------

### fetchMock.route(matcher, response, options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Adds a route to the fetchHandler's router. This method is chainable and allows for complex request matching and response configuration.

```APIDOC
## fetchMock.route(matcher, response, options)

### Description
Adds a route to the fetchHandler's router. A route defines rules for matching fetch requests and configuration for generating the corresponding response.

### Parameters
- **matcher** (String|Regex|Function|Object) - Required - Determines which calls to fetch should be handled by this route.
- **response** (String|Object|Function|Promise|Response) - Required - The response to send when a call is matched.
- **options** (Object|String) - Optional - Configuration for matching and response behavior. If a string is provided, it is used as the route name.

### Usage Example
```js
fetchMock
  .route('http://my.site', 401)
  .route('http://my.site', 200, { headers: { auth: true } });
```
```

--------------------------------

### Define request function

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/quickstart.md

A sample function that performs a fetch request.

```javascript
export async function makeRequest() {
	const res = await fetch('http://example.com/my-url', {
		headers: {
			user: 'me',
		},
	});
	return res.json();
}
```

--------------------------------

### Expect Extensions

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/vitest.md

Custom Vitest expectation matchers for fetchMock.

```APIDOC
## Expect Extensions

### Description
Convenience methods added to Vitest's expect object for asserting fetch calls.

### Methods
- **expect(fetchMock).toHaveFetched(filter, options)**
- **expect(fetchMock).toHaveLastFetched(filter, options)**
- **expect(fetchMock).toHaveNthFetched(n, filter, options)**
- **expect(fetchMock).toHaveFetchedTimes(n, filter, options)**
- **expect(fetchMock).toBeDone(filter)**

### Notes
- Methods can be prefixed with .not for negative assertions.
- 'Fetched' can be replaced with 'Got', 'Posted', 'Put', 'Deleted', 'FetchedHead', or 'Patched' to scope to specific HTTP methods.
```

--------------------------------

### Mock a request with express-style parameters

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/index.md

Uses express-style routing to match requests and verify calls using a named identifier.

```js
import fetchMock from 'fetch-mock';

fetchMock
  .mockGlobal()
  .route({
    express: '/api/users/:user'
    expressParams: {user: 'kenneth'}
  }, {
    userData: {
      email: 'kenneth@example.com'
    }
  }, 'userDataFetch');

const res = await fetch('http://example.com/api/users/kenneth');
assert(fetchMock.callHistory.called('userDataFetch'))
const data = await res.json();
assertEqual(data.userData.email, 'kenneth@example.com')
```

--------------------------------

### .catch()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Specifies the response for fetch calls that do not match any defined routes.

```APIDOC
## .catch(response)

### Description
Specifies how to respond to calls to fetch that don't match any routes. If no argument is passed, unmatched calls receive a 200 response.

### Parameters
- **response** (any) - Optional - A response compatible with .route().
```

--------------------------------

### Merging Matchers and Options

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Matchers and options can be distributed across the first and third parameters, which is useful for defining similar routes concisely.

```javascript
fetchMock
	.route('http://my.site', 401)
	.route('http://my.site', 200, { headers: { auth: true } });
```

--------------------------------

### manageFetchMockGlobally()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/vitest.md

Hooks fetchMock into Vitest's global mock management functions.

```APIDOC
## manageFetchMockGlobally()

### Description
Hooks fetchMock up to Vitest's global mock management so that vi.clearAllMocks(), vi.resetAllMocks(), vi.restoreAllMocks(), and vi.unstubAllGlobals() trigger the corresponding fetchMock methods.
```

--------------------------------

### manageFetchMockGlobally(jest)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/jest.md

Integrates fetchMock with Jest's global mock management functions.

```APIDOC
## manageFetchMockGlobally(jest)

### Description
Hooks fetchMock up to jest's global mock management so that jest.clearAllMocks(), jest.resetAllMocks(), and jest.restoreAllMocks() trigger the corresponding fetchMock methods.
```

--------------------------------

### mockGlobal()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/mocking-and-spying.md

Replaces the global fetch implementation with the mock handler.

```APIDOC
## mockGlobal()

### Description
Replaces globalThis.fetch with the fetchMock fetchHandler.
```

--------------------------------

### Define a sticky route

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Creates a persistent route that survives calls to restore(), reset(), or resetbehavior(). Useful for global test fixtures.

```js
fetchMock.sticky(/config-hub.com/, require('./fixtures/start-up-config.json'));
```

--------------------------------

### fetchMock.callHistory.calls(filter, options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/CallHistory.md

Returns an array of all calls matching the given filter and options.

```APIDOC
## .calls(filter, options)

### Description
Returns an array of all calls matching the given filter and options. Each call is returned as a CallLog object.

### Parameters
- **filter** (undefined|boolean|string|RegExp|function|Object) - Optional - Criteria to filter calls (e.g., true for matched, false for unmatched, route name, or matcher).
- **options** (Object) - Optional - Options compatible with the route API to further filter the list of calls.
```

--------------------------------

### Partial Body Matching Configuration

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/matcher.md

Configuration to ignore unspecified properties when matching a request body.

```js
{
	body: { "key1": "value1"},
	matchPartialBody: true
}
```

--------------------------------

### Define Custom HTTP Method Shorthand

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Extend the fetch-mock instance with a custom method shorthand by wrapping the mock function.

```javascript
fetchMock.purge = function (matcher, response, options) {
	return this.mock(
		matcher,
		response,
		Object.assign({}, options, { method: 'PURGE' }),
	);
};
```

--------------------------------

### fetchMock.mockReset()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/vitest.md

Clears call history and removes all routes except sticky routes.

```APIDOC
## fetchMock.mockReset({includeSticky: boolean})

### Description
Clears all call history from the mocked fetch implementation and removes all routes (including fallback routes) with the exception of sticky routes.

### Parameters
- **includeSticky** (boolean) - Optional - If true, removes sticky routes as well.
```

--------------------------------

### Create Custom GraphQL Matcher

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Define a matcher to inspect GraphQL request bodies for specific variables.

```javascript
fetchMock
  .addMatcher({
    name: 'graphqlVariables',
    matcher: ({graphqlVariables}) => (url, options) => {
        if (!/\/graphql$/.test(url)) {
            return false;
        }
        const body = JSON.parse(options.body)
        return body.variables && Object.keys(body.variables).length === Object.keys(body.graphqlVariables).length && Object.entries(graphqlVariables).every(([key, val]) => body.variables[key] === val)
    }
  })
  .mock({graphqlVariables: {owner: 'wheresrhys'}}, {data: {account: {
    name: 'wheresrhys',
    repos: [ ... ]
    }}})
```

--------------------------------

### unmockGlobal()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/mocking-and-spying.md

Restores the original global fetch implementation.

```APIDOC
## unmockGlobal()

### Description
Restores globalThis.fetch to its original state.
```

--------------------------------

### Match Express Parameters

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/matcher.md

Use the express: keyword combined with a params object to filter by specific parameter values.

```js
{
	url: "express:/:section/user/:user",
	params: {"section": "feed", "user": "geoff"}
}
```

--------------------------------

### TypeScript RouteConfigWrapper

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Use the RouteConfigWrapper class to avoid TypeScript errors when passing a configuration object to .route().

```typescript
import fetchMock, { RouteConfigWrapper } from 'fetch-mock';

fetchMock.route(
	new RouteConfigWrapper({
		url: 'glob:*/api/v1/monitoring/metricsForRuntimes?*',
		query: {},
		response: Promise.resolve(allMetricsData),
		delay: 2000,
	}),
);
```

--------------------------------

### Expect Extensions

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/jest.md

Custom Jest matchers for verifying fetch calls.

```APIDOC
## Expect Extensions

### Description
These matchers are added to jest automatically and are available on any expect call passed fetchMock. They support the .not helper.

### Methods
- expect(fetchMock).toHaveFetched(filter, options)
- expect(fetchMock).toHaveLastFetched(filter, options)
- expect(fetchMock).toHaveNthFetched(n, filter, options)
- expect(fetchMock).toHaveFetchedTimes(n, filter, options)
- expect(fetchMock).toBeDone(filter)

### Notes
'Fetched' can be replaced with 'Got', 'Posted', 'Put', 'Deleted', 'FetchedHead', or 'Patched' to scope to specific HTTP methods.
```

--------------------------------

### .hardReset(options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/resetting.md

Removes all behavior and state added to fetch-mock, including routes, history, and global mocks.

```APIDOC
## .hardReset(options)

### Description
Removes all the behavior and state that's been added so far. It runs .removeRoutes(), .clearHistory() and .unmockGlobal().

### Parameters
- **options** (object) - Optional - Pass {includeSticky: true} to force even sticky routes to be removed.
```

--------------------------------

### Analyze call history

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/Usage/quickstart.md

Verify that specific routes were called and inspect call metadata.

```javascript
assert(fetchMock.callHistory.called('good get'));
assert(
	fetchMock.callHistory.lastCall('good get').queryParams.get('search'),
	'needle',
);
```

--------------------------------

### .addMatcher(options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Registers a custom matcher for use in route definitions.

```APIDOC
## .addMatcher(options)

### Description
Allows adding custom, reusable matchers to fetch-mock.

### Parameters
- **name** (String) - The name of the matcher.
- **usesBody** (Boolean) - Whether the matcher requires access to the request body.
- **matcher** (Function) - A function that returns a matcher function (NormalizedRequest) => Boolean.
```

--------------------------------

### fetchMock.mockRestore()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/vitest.md

Resets the mock and restores the global fetch implementation.

```APIDOC
## fetchMock.mockRestore({includeSticky: boolean})

### Description
Calls mockReset() and additionally restores global fetch to its unmocked implementation.

### Parameters
- **includeSticky** (boolean) - Optional - If true, removes sticky routes as well.
```

--------------------------------

### fetchMock.callHistory.lastCall(filter, options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/CallHistory.md

Returns the CallLog for the last call to fetch matching the given filter and options.

```APIDOC
## .lastCall(filter, options)

### Description
Returns the CallLog for the last call to fetch matching the given filter and options.

### Parameters
- **filter** (undefined|boolean|string|RegExp|function|Object) - Optional - Criteria to filter calls.
- **options** (Object) - Optional - Options compatible with the route API to further filter the list of calls.
```

--------------------------------

### fetchMock.callHistory.called(filter, options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/CallHistory.md

Returns a Boolean indicating whether any calls to fetch matched the given filter and options.

```APIDOC
## .called(filter, options)

### Description
Returns a Boolean indicating whether any calls to fetch matched the given filter and options.

### Parameters
- **filter** (undefined|boolean|string|RegExp|function|Object) - Optional - Criteria to filter calls.
- **options** (Object) - Optional - Options compatible with the route API to further filter the list of calls.
```

--------------------------------

### Route Name as Third Parameter

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Pass a string as the third parameter to name a route for easier inspection or removal.

```javascript
fetchMock.route('*', 200, 'catch-all')
```

--------------------------------

### Combine Multiple URL Matchers

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/matcher.md

Group multiple URL matching criteria within a single object.

```js
{
	url: {
		begin: 'https',
		path: '/could/be/any/host'
	}
}
```

--------------------------------

### fetchMock.callHistory.done(routeNames)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/CallHistory.md

Returns a Boolean indicating whether fetch was called the expected number of times.

```APIDOC
## .done(routeNames)

### Description
Returns a Boolean indicating whether fetch was called the expected number of times (or has been called at least once if repeat is not defined for the route).

### Parameters
- **routeNames** (string|string[]) - Optional - A single name or an array of names to check only certain routes.
```

--------------------------------

### fetchMock.callHistory.flush(waitForBody)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/CallHistory.md

Returns a Promise that resolves once all fetches handled by fetch-mock have resolved.

```APIDOC
## .flush(waitForBody)

### Description
Returns a Promise that resolves once all fetches handled by fetch-mock have resolved. Useful for testing code where the returned promise cannot be accessed directly.

### Parameters
- **waitForBody** (boolean) - Optional - If true, the promise will wait for all body parsing methods to resolve.
```

--------------------------------

### Function Matcher Signature

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/matcher.md

A custom function matcher is a function that accepts the url, options, and an optional Request object, returning a boolean to indicate if the route should respond.

```APIDOC
## Function Matcher

### Description
Custom function used to determine if a route should respond to a request. Return `true` to match the request.

### Signature
`Function(url, options, [Request]) -> Boolean`

### Arguments
- **url** (string) - The URL fetch was called with.
- **options** (object) - The options fetch was called with.
- **Request** (Request) - Optional. The original Request instance if fetch was called with one.

### Usage Example
```javascript
// Match based on Authorization header
(url, {headers}) => !!headers.Authorization

// Match using Request object
(_, _, request) => !!request.headers.get('Authorization')
```
```

--------------------------------

### .removeRoutes(options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/resetting.md

Removes some or all of the routes that have been added to fetch-mock.

```APIDOC
## .removeRoutes(options)

### Description
This method removes some or all of the routes that have been added to fetch mock.

### Parameters
- **names** (array) - Optional - An array of named routes to remove. If no value is passed then all routes compatible with the other options passed are removed.
- **includeSticky** (boolean) - Optional - A boolean indicating whether or not to remove sticky routes.
- **includeFallback** (boolean) - Optional - A boolean indicating whether or not to remove the fallback route (added using .catch()).
```

--------------------------------

### .clearHistory()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/resetting.md

Clears all data recorded for fetch's calls.

```APIDOC
## .clearHistory()

### Description
Clears all data recorded for fetch's calls.
```

--------------------------------

### fetchMock.mockClear()

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/wrappers/vitest.md

Clears all call history from the mocked fetch implementation.

```APIDOC
## fetchMock.mockClear()

### Description
Clears all call history from the mocked fetch implementation.
```

--------------------------------

### Send JSON response without automatic header

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/response.md

Manually stringify an object to avoid the default application/json header.

```js
fetchMock.route('http://a.com', JSON.stringify({ prop: 'value' }));
```

--------------------------------

### Complex Matchers

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/route/index.md

Use regular expressions, functions, or objects to define advanced matching criteria for requests.

```javascript
fetchMock
	.route(/.*\.here.*/, 200)
	.route((url, opts) => opts.method === 'patch', 200)
	.route('express:/:type/:id', 200, {
		params: {
			type: 'shoe',
		},
	})
	.route(
		{
			headers: { Authorization: 'Bearer 123' },
			method: 'POST',
		},
		200,
	);
```

--------------------------------

### modifyRoute(routeName, options)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Modifies an existing route's behavior.

```APIDOC
## modifyRoute(routeName, options)

### Description
Modifies a route's behaviour, overwriting any options passed into the named route when first created. To remove an option, pass in null.
```

--------------------------------

### removeRoute(routeName)

Source: https://github.com/wheresrhys/fetch-mock/blob/main/docs/docs/API/more-routing-methods.md

Removes a previously defined route.

```APIDOC
## removeRoute(routeName)

### Description
Removes a route by its name.
```
Tokens:
Raw