Registry / testing / fetchception

fetchception

JSON →
library2.0.1jsnpmunverified

Fetchception is a library for mocking fetch API calls in tests, version 2.0.1. It allows defining expected requests and corresponding responses, automatically restoring the global fetch after the test. Based on ideas from fileception and httpception, it uses messy and unexpected-messy for HTTP conversation modelling and diffing. Key differentiators: simple declarative API, automatic cleanup, and integration with unexpected for advanced assertions.

testing
npm install fetchception
package ↗
INSTALL
IMPORT
SIG · FETCHCEPTION
F
fetchception
testingjavascriptv2.0.1
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.

fetchception
✓ import fetchception from 'fetchception'
✗ const fetchception = require('fetchception')
ESM import works if the consumer's environment supports it; CommonJS is also supported.
fetchception (default export)
✓ const fetchception = require('fetchception')
✗ const { fetchception } = require('fetchception')
Export is default, not named. CommonJS require as shown.
fetchception (type import for TypeScript)
✓ import fetchception from 'fetchception'
✗ import * as fetchception from 'fetchception'
TypeScript default import works if esModuleInterop is enabled; otherwise use namespace import.

Shows how to mock a fetch call with a single request/response pair inside a test, with automatic cleanup.

const fetchception = require('fetchception'); const assert = require('assert'); it('should mock fetch', () => fetchception( [ { request: '/api/foo', response: { statusCode: 200, body: { foo: 'bar' }, }, }, ], () => { return fetch('/api/foo') .then((res) => res.json()) .then((res) => { assert.strictEqual(res.foo, 'bar'); }); } ) );
Debug
Known issues
gotchaThe library overrides the global fetch; ensure it is restored after tests (automatic when using promise-based API).
fix
Always return the promise from fetchception to guarantee cleanup.
affects: >=1.0.0
gotchaIf you need to mock multiple different requests, you must define them in an array; otherwise only the first request matches.
fix
Always use an array of request/response objects.
affects: >=1.0.0
gotchaThe response body must be a string or object; if you pass a string, it's sent as-is without JSON parsing.
fix
For JSON responses, pass an object (will be serialized) or a string if you want raw response body.
affects: >=1.0.0
deprecatedfetchception does not support abort controllers or timeout options in mock definitions; those are ignored.
fix
Do not rely on abort logic in tests; mock responses are instantaneous.
affects: >=1.0.0
Errors
Common errors & fixes
Error: fetch is not defined
The global fetch is not available in the test environment (Node.js v17- or without node-fetch).
fix
Install and import a fetch polyfill (e.g., node-fetch) before using fetchception.
TypeError: fetchception is not a function
Importing fetchception incorrectly (e.g., as a named export instead of default).
fix
Use default import: const fetchception = require('fetchception');
AssertionError [ERR_ASSERTION]: Expected 'foo' to equal 'bar'
Response body was not parsed as JSON because the mock response body was a string, not an object.
fix
Pass an object as response body: response: { body: { foo: 'bar' } } (will be serialized) or use JSON.parse on the string.
Upgrade
Version history
2.0.1latest on npm
Audit
Dependencies
messyrequiredUsed for modelling, inspecting, and diffing HTTP conversations.
unexpected-messyoptionalProvides additional assertion capabilities for HTTP conversations.
Agent activity
4 hits · last 30 days
node
4
Resources
packagefetchception ↗
fetchception — npm install fetchception · libregistry