{"id":47666,"library":"fetchception","title":"Fetchception","description":"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.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install fetchception","lang":"bash","label":"npm"},{"cmd":"yarn add fetchception","lang":"bash","label":"yarn"},{"cmd":"pnpm add fetchception","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for modelling, inspecting, and diffing HTTP conversations.","package":"messy","optional":false},{"reason":"Provides additional assertion capabilities for HTTP conversations.","package":"unexpected-messy","optional":true}],"imports":[{"note":"ESM import works if the consumer's environment supports it; CommonJS is also supported.","wrong":"const fetchception = require('fetchception')","symbol":"fetchception","correct":"import fetchception from 'fetchception'"},{"note":"Export is default, not named. CommonJS require as shown.","wrong":"const { fetchception } = require('fetchception')","symbol":"fetchception (default export)","correct":"const fetchception = require('fetchception')"},{"note":"TypeScript default import works if esModuleInterop is enabled; otherwise use namespace import.","wrong":"import * as fetchception from 'fetchception'","symbol":"fetchception (type import for TypeScript)","correct":"import fetchception from 'fetchception'"}],"quickstart":{"code":"const fetchception = require('fetchception');\nconst assert = require('assert');\n\nit('should mock fetch', () =>\n  fetchception(\n    [\n      {\n        request: '/api/foo',\n        response: {\n          statusCode: 200,\n          body: { foo: 'bar' },\n        },\n      },\n    ],\n    () => {\n      return fetch('/api/foo')\n        .then((res) => res.json())\n        .then((res) => {\n          assert.strictEqual(res.foo, 'bar');\n        });\n    }\n  )\n);","lang":"javascript","description":"Shows how to mock a fetch call with a single request/response pair inside a test, with automatic cleanup."},"warnings":[{"fix":"Always return the promise from fetchception to guarantee cleanup.","message":"The library overrides the global fetch; ensure it is restored after tests (automatic when using promise-based API).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use an array of request/response objects.","message":"If you need to mock multiple different requests, you must define them in an array; otherwise only the first request matches.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For JSON responses, pass an object (will be serialized) or a string if you want raw response body.","message":"The response body must be a string or object; if you pass a string, it's sent as-is without JSON parsing.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Do not rely on abort logic in tests; mock responses are instantaneous.","message":"fetchception does not support abort controllers or timeout options in mock definitions; those are ignored.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.0.1':14 'advanc':63 'allow':16 'api':9,55 'assert':64 'automat':23,56 'base':31 'call':10 'cleanup':57 'convers':47 'correspond':21 'declar':54 'defin':17 'dif':50 'differenti':52 'expect':18 'fetch':8,27 'fetchcept':1,2 'filecept':35 'global':26 'http':46 'httpception':37 'idea':33 'integr':59 'javascript':65 'key':51 'librari':5 'messi':40,44 'mock':7 'model':48 'request':19 'respons':22 'restor':24 'simpl':53 'test':12,30 'unexpect':43,61 'unexpected-messi':42 'use':39 'version':13","created_at":"2026-06-07T16:52:41.037130+00:00","updated_at":"2026-06-07T16:52:41.037130+00:00","problems":[{"fix":"Install and import a fetch polyfill (e.g., node-fetch) before using fetchception.","cause":"The global fetch is not available in the test environment (Node.js v17- or without node-fetch).","error":"Error: fetch is not defined"},{"fix":"Use default import: const fetchception = require('fetchception');","cause":"Importing fetchception incorrectly (e.g., as a named export instead of default).","error":"TypeError: fetchception is not a function"},{"fix":"Pass an object as response body: response: { body: { foo: 'bar' } } (will be serialized) or use JSON.parse on the string.","cause":"Response body was not parsed as JSON because the mock response body was a string, not an object.","error":"AssertionError [ERR_ASSERTION]: Expected 'foo' to equal 'bar'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"fetchception","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}