fetch-mock-cache

Caching mock fetch implementation for all runtimes and frameworks.

Copyright (c) 2023 by Gadi Cohen. MIT Licensed.

!GitHub Workflow Status (with event)
!Coverage

🏁 Introduction

- 💡 Tired of writing mocks?
Skip manually crafting fetch() mocks — just run a real fetch() once and auto cache the result.

- ⚡ Fast feedback loop
Cached responses make tests run much faster — ideal for TDD (Test Driven Development) against real APIs.

- 👥 Team & CI friendly
Commit the cache to your repo so everyone (and your CI) benefits from consistent, speedy tests.

- 🔧 Proven approach
Used by yahoo-finance2 to test 1400+ API calls in < 1s on every commit.

- 💬 Open to ideas
Feature requests and contributions welcome!

NB: if you're still using v1 (formerly jest-fetch-mock-cache),
see the old README
and/or MIGRATING.md for how to upgrade.

Quick Start

Generally your code will look something like this, but, see further below for
the exact code for different runtimes and testing frameworks
.

``ts
// Default for node runtime, see grid below for bun/deno.
import createFetchCache from "fetch-mock-cache";
// See list of possible stores, below.
import Store from "fetch-mock-cache/stores/fs";

const fetchCache = createFetchCache({ Store });

describe("cachingMock", () => {
it("works with a JSON response", async (t) => {
const url = "http://echo.jsontest.com/key/value/one/two";
const expectedResponse = { one: "two", key: "value" };
t.mock.method(globalThis, "fetch", fetchCache);

for (let i = 0; i < 2; i++) {
const response = await fetch(url);
const data = await response.json();
const expectedCacheHeader = i === 0 ? "MISS" : "HIT";
expect(response.headers.get("X-FMC-Cache")).toBe(expectedCacheHeader);
expect(data).toEqual(expectedResponse);
}
});
});
`

- The first time this runs, a _real_ request will be made to
jsontest.com, and the result returned. But, it will also be
saved to cache.

- Subsequent requests will return the cached copy without
making an HTTP request.

- Commit tests/fixtures/http (default) to your repo for
super fast tests in the future for all contributors and CI.

Supported runtimes and test frameworks

Click on the "Quick Start / Example" links to see a working implementation for your framework of choice.

| Runtime | Framework | Status | Quick Start / Example |
| ------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Node 20+ | node:test | !Dynamic YAML Badge | direct or with fetch-mock |
| | jest | !Dynamic YAML Badge | direct or with jest-fetch-mock |
| | vitest | !Dynamic YAML Badge | direct or with vitest-fetch-mock |
| Deno | deno test | !Dynamic YAML Badge | direct |
| Bun | bun:test | !Dynamic YAML Badge | direct, maybe soon bun-bagel |

What's cached

Sample output from the Quick Start code above, when used with NodeFSStore:

`bash
$ cat tests/fixtures/http/echo.jsontest.com\!key\!value\!one\!two
`

`js
{
"request": {
"url": "http://echo.jsontest.com/key/value/one/two"
},
"response": {
"ok": true,
"status": 200,
"statusText": "OK",
"headers": {
"access-control-allow-origin": "*",
"connection": "close",
"content-length": "39",
"content-type": "application/json",
"date": "Fri, 21 Jul 2023 16:59:17 GMT",
"server": "Google Frontend",
"x-cloud-trace-context": "344994371e51195ae21f236e5d7650c4"
},
"bodyJson": {
"one": "two",
"key": "value"
}
}
}
`

JSON bodies are stored as a decoded object in bodyJSON for increased
readability. Text bodies are stored as a string in bodyText, and
binary bodies are stored as a Base64 encoded string in bodyBase64.

Debugging

We use debug for debugging. E.g.:

`bash
$ DEBUG=fetch-mock-cache:* yarn test
yarn run v1.22.19
$ jest
fetch-mock-cache:core Fetching and caching 'http://echo.jsontest.com/key/value/one/two' +0ms
fetch-mock-cache:core Using cached copy of 'http://echo.jsontest.com/key/value/one/two' +177ms
PASS src/index.spec.ts
cachingMock
✓ should work (180 ms)
`

Available Stores

- stores/fs - use your runtime's FileSystem API to
store cached requests to the filesystem, for persistance. These can be
committed to your projects repository / source control for faster future
testing, including for CI.

- stores/memory - keep the cache in memory.
The cache will not persist and will be created again from scratch each
time you run your code.

$3

See also the store "root" class. Don't instantiate
directly; rather extend this class overriding at least fetchContent and
storeContent, and perhaps, idFromRequest, the constructor and others
according to your needs. Here's an example to combine with a database:

`ts
import FMCStore from "fetch-mock-cache/store";
import type { FMCCacheContent, FMCStoreOptions } from "fetch-mock-cache/store";
import db from "./db"; // your existing db

export default class MyStore extends FMCStore {
async fetchContent(req: FMCCacheContent["request"]) {
const _id = await this.idFromRequest(request);
return (await db.collection("fmc").findOne({ _id })).content;
}
async storeContent(content: FMCCacheContent) {
const _id = await this.idFromRequest(content.request);
await db.collection("jfmc").insertOne({ _id, content });
}
}
`

Overriding the Default Caching Behaviour

$3

`ts
// These will be used for the next fetch call ONCE only. However, once()
// may be called multiple times to queue options for multiple future calls.
fetchCache.once({
/ options /
});
`

$3

Generally we don't need to think about cache IDs, as we can reliably
generate them from the Request object (e.g. based on URL and hashes
of the headers, body, etc.).

But sometimes, we may want to specify this manually, e.g.

1. We'd rather use the _test name_ as the id, vs something URL-based.
2. It can't be reliably generated, e.g. formData with a random boundary.

In this case, we can:

`ts
fetchCache.once({ id: "mytest" });
fetch(/ ... /); // or code that uses fetch();
`

Make sure the id is relevant for your store. e.g. if using the fs store,
make sure id is a valid file name (the fs store will still append .json
at the end).

$3

You can also pass the following to fetchCache.once:

`ts
{
id?: string; // as above
/** True (default): use cached response if available; false: always fetch from network.
* You can also provide a promise or function that returns a boolean or promise.
*/
readCache?:
| boolean
| Promise
| ((...args: Parameters) => Promise);
/** If a fetch was performed, should we write it to the cache? Can be a boolean, a
* promise, or a function that returns a boolean or promise. In the case of a promise,
* the write will open occur when the promise resolves, and AFTER the response is
* returned. This allows for more complex patterns, where e.g. you could rely on the
* further processing of the response in other functions before deciding whether to
* cache it or not, but does require some extra care.
*/
writeCache?:
| boolean
| Promise
| ((...args: Parameters) => Promise);
}
`

See below in Tips & Tricks on how you can leverage this to conditionally replace the
cache for failing tests.

Internal and Experimental Features

Internal and experimental features are generally prefixed by an underscore ("_").
You're welcome to use them, however, they are not part of our API contract - as such,
they may change or disappear at any time, _without following semantic versioning_.

Often these are used for new ideas that are still in development, where, we'd like
you to have easy access to them (and appreciate your feedback!), but, they're not
(yet) considered stable.

Current experiments:

None.

Previous experiments:

* _once() has been promoted to _once() after a long, succesful testing period.

Tips & Tricks

$3

1. Let's wrap the it() function to allow a callback after the test

`ts
import { it as _it } from "..."; // your fave library

export const it = function wrappedIt(
suite: string,
fn: (
t: Parameters[0],
onFinish: (cb: (error?: unknown) => void | Promise) => void,
) => void | Promise,
) {
const finishCallbacks = [] as Array<(error?: unknown) => void>;

const onFinish = (cb: (error?: unknown) => void) => {
finishCallbacks.push(cb);
};

const finish = (error?: unknown) => {
for (const cb of finishCallbacks) {
cb(error);
}
};

const wrappedFn = (t: Deno.TestContext) => {
let result: ReturnType;
try {
result = fn(t, onFinish);
} catch (error) {
finish(error);
throw error;
}

if (result === undefined) {
finish();
return undefined;
}

if (result instanceof Promise) {
return result.then(finish).catch((error) => {
finish(error);
throw error;
});
}

throw new Error(
Test "${name}" failed with unexpected result: ${result},
);
};

_it(suite, wrappedFn);
};
`

2. Now do something like this:

`ts
import { it } from "above";
import fetchCache from "wherever-you-set-it-up";

function conditionalCache(onFinish) {
if (process.env.FETCH_CACHE === "recache")
// i.e. if the test fails and has an error, then writeCache resolves to "true"
fetchCache.once({ readCache: false, writeCache: onFinish.then(error => !!error)})
}

it("rewrites the cache on fail", async(_t, onFinish) => {
conditionalCache(onFinish);
const response = await fetch(...);
const result = await response.json();
expect(result).toMatch({
success: true
});
})
`

3. Now, by default, we'll use the cache as normal. However, if you set
FETCH_CACHE="recache", we won't use the cache, and if the test fails,
we'll replace the cached result.

This is super useful for testing if API response (and not your code)
has changed, commit the new responses, and then adapt your code as
necessary. You'd only do this after first making sure all your existing
tests are passing.

TODO

- [x] Cache request headers too and hash them in filename / key / id.
- [ ] Browser-environment support. Please open an issue if you need this, and in what cases. jsdom?
- [ ] Handle and store invalid JSON too?

`

``