https://github.com/mapado/metch-fock
A `fetch` mock library
https://github.com/mapado/metch-fock
Last synced: 4 months ago
JSON representation
A `fetch` mock library
- Host: GitHub
- URL: https://github.com/mapado/metch-fock
- Owner: mapado
- License: mit
- Created: 2023-10-09T19:36:32.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-19T09:45:20.000Z (10 months ago)
- Last Synced: 2025-09-28T03:45:14.753Z (8 months ago)
- Language: TypeScript
- Size: 106 KB
- Stars: 0
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# metch-fock
A `fetch` mock library.
It will replace the fetch implementation by a custom one matching your response.
It does work with Node 18+ `fetch` implementation. (See [Considered alternatives](#considered-alternatives)).
## Installation
Install it with your package manager
```sh
# npm
npm i -D metch-fock
#yarn
yarn add --dev metch-fock
#pnpm
pnpm add -D metch-fock
```
## Usage
Imagine that function:
```ts
/**
* This is a really simple function, you might have something way more complicated in your codebase.
* The only important thing is that it will call the `fetch` method.
*/
async function doFetchWithToken(input, options) {
const options = addToken(options);
return fetch(input, options);
}
```
You need to implement a `beforeEach` and `afterEach` method.
The first one will be used to block all network `fetch` call to avoid calling distant urls when running your tests.
The second one will reset the mock stack. If you don't do that, the second test will match the mock of the first test, you don't want that.
```ts
import { blockAllCalls, fetchMock, resetMocks } from 'metch-fock';
describe('some test file', () => {
beforeEach(() => {
// block all network calls
blockAllCalls();
});
afterEach(() => {
// empty the mock call stack
resetMocks();
});
test('a test that will match every call', () => {
const expected = new Response('OK');
fetchMock(() => true, expected);
const r1 = await doFetchWithToken('https://match.shrug/test');
expect(r1).toBe(expected);
});
test('some test', () => {
const expected = new Response('OK');
fetchMock.get('https://match.get/test', expected);
fetchMock.put(/https:\/\/match.put\//, expected);
fetchMock.post.startsWith('https://match.post/', expected);
const r1 = await doFetchWithToken('https://match.get/test');
expect(r1).toBe(expected);
const r2 = await doFetchWithToken('https://match.put/test', {
method: 'PUT',
});
expect(r2).toBe(expected);
const r3 = await doFetchWithToken('https://match.post/test', {
method: 'POST',
});
expect(r3).toBe(expected);
});
test('some test with a complex matcher', () => {
const expected = new Response('OK');
fetchMock((input, options): boolean => {
// you have access to all parameters of `fetch` function here, you can return anything you want
return options?.headers?.Authorization === 'Bearer some-token';
}, expected);
const r1 = await doFetchWithToken('https://match.shrug/test', {
headers: { Authorization: 'Bearer some-token' },
});
expect(r1).toBe(expected);
});
});
```
## API
Main matcher function, with all the flexibility you want:
```ts
function fetchMock(
matcher: (
input: URL | RequestInfo,
options: RequestInit | undefined,
) => boolean,
response: Response,
): void;
```
Helpers for simple test writing:
```ts
function fetchMock.get(url: string | RegExp, response: Response): void;
function fetchMock.post(url: string | RegExp, response: Response): void;
function fetchMock.put(url: string | RegExp, response: Response): void;
function fetchMock.patch(url: string | RegExp, response: Response): void;
function fetchMock.delete(url: string | RegExp, response: Response): void;
// foreach methods, there are string helper too
function fetchMock..startsWith(url: string, response: Response): void;
function fetchMock..endsWith(url: string, response: Response): void;
function fetchMock..includes(url: string, response: Response): void;
```
Utility functions:
```ts
function getInputUrl(input: URL | RequestInfo): string;
function getOptionMethod(options: RequestInit | undefined): string;
```
## Considered alternatives
Why I did this library ? You can read [the full blog post here](https://julien.deniau.me/posts/2023-10-10-metck-fock).
- We were using [`nock`](https://github.com/nock/nock) for a long time (and still are in some of our projects), but nock [is currently not compatible with Node 18+ native fetch implementation](https://github.com/nock/nock/issues/2397)
- [`fetch-mock`](https://github.com/wheresrhys/fetch-mock), but no commit since Sep 2021, and does not work with [node 18+ fetch](https://github.com/wheresrhys/fetch-mock/issues/658) either
- [@mswjs/interceptors](https://github.com/mswjs/interceptors) seems really overkill for a mocking system (but it does seems really powerful for middleware, proxy, etc.)
- [undici MockAgent](https://undici.nodejs.org/#/docs/best-practices/mocking-request) does seems to work only with undici.