fetch-mocked

library0.0.33jsnpmunverified

A test framework integrated fetch mocking solution written as a native ESModule, compatible with Jest, Vitest, and other test frameworks that support a similar API (getMockImplementation, mockImplementation, mock.calls, mock.results, mock.lastCall). Version 0.0.33 is the latest stable release, with ongoing development. Unlike other fetch mocking libraries, fetch-mocked is a pure ESModule with no CommonJS dependencies, making it fully compatible with native ESModule projects. It provides an enriched mock function that integrates assertions and mock utilities from the test framework, along with polyfills for fetch, Request, Response, and Headers using node-fetch.

testing

npm install fetch-mocked

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-MOCKED

fetch-mocked

testingjavascriptv0.0.33

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mockFetch

✓ import { mockFetch } from 'fetch-mocked';

✗ const mockFetch = require('fetch-mocked');

ESM-only; CommonJS require is not supported.

polyfillFetch

✓ import { polyfillFetch } from 'fetch-mocked';

Use only if not using the test setup file; must be called before any fetch declarations.

MockedFetch

✓ import { MockedFetch } from 'fetch-mocked';

✗ import type { MockedFetch } from 'fetch-mocked';

MockedFetch is a type export, but the library ships types, so either syntax works.

Demonstrates basic setup and usage of mockFetch with Vitest, including lifecycle hooks and a test that mocks a fetch call and verifies behavior.

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; import { mockFetch } from 'fetch-mocked'; let mockedFetch: ReturnType<typeof mockFetch>; beforeEach(() => { mockedFetch = mockFetch(vi.fn); }); afterEach(() => { mockedFetch.mockReset(); }); it('should mock a successful JSON response', async () => { mockedFetch.mockResolvedValueOnce({ data: 'test' }); const response = await fetch('https://api.example.com/data'); const body = await response.json(); expect(body).toEqual({ data: 'test' }); expect(mockedFetch).toHaveBeenCalledTimes(1); expect(mockedFetch).toHaveBeenCalledWith('https://api.example.com/data'); });

Debug

Known issues

gotchamockFetch expects a factory function (e.g., vi.fn, jest.fn) not a mock instance. Passing vi.fn() returns a new mock each call, which breaks the intended enrichment.

fix

Pass the factory function itself: mockFetch(vi.fn) not mockFetch(vi.fn()).

affects: >=0.0.0

gotchaThe testSetup.mjs file must be loaded before any test files that import fetch-mocked. If using vitest, the setupFiles config must point to the correct path.

fix

Ensure setupFiles (vitest) or setupFilesAfterEnv (jest) includes './node_modules/fetch-mocked/testSetup.mjs'.

affects: >=0.0.0

deprecatedThe `responseType` option is global but can be overridden per mock. Misuse can lead to unexpected body transformations (e.g., setting responseType to 'blob' when the mock body is JSON).

fix

Set responseType globally only if consistent across all mocks; otherwise, pass it in individual mock options.

affects: >=0.0.0

gotchaThe library uses node-fetch under the hood; if your environment already polyfills fetch, it may conflict. The polyfillFetch function should only be called once.

fix

If using the setup file, do not manually call polyfillFetch. If already polyfilled, consider disabling the setup file.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'fetch-mocked/testSetup.mjs' from 'jest.config.js'

The path to the setup file is incorrect or fetch-mocked is not installed.

fix

Run 'npm install fetch-mocked -D' and verify the path in your jest config matches the installation path.

TypeError: jest.fn is not a function

Passed jest.fn() instead of jest.fn to mockFetch.

fix

Use mockFetch(jest.fn) (no parentheses) to pass the factory function.

ReferenceError: fetch is not defined

The polyfill was not loaded before the test runs, or the environment does not have native fetch.

fix

Add the setup file or import and call polyfillFetch() at the top of your test file.

Type error: 'mockResolvedValueOnce' does not exist on type '(...args: any[]) => any'

TypeScript not recognizing the enriched mock return type.

fix

Import MockedFetch type and cast if needed: const mockedFetch = mockFetch(vi.fn) as MockedFetch;

Upgrade

Version history

0.0.33latest on npm

Audit

Dependencies

node-fetchrequiredUsed internally to polyfill fetch and related classes in Node.js test environment

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/badbatch/fetch-mocked ↗

packagefetch-mocked ↗

homepagehttps://github.com/badbatch/fetch-mocked ↗