{"id":49464,"library":"supertest-fetch","title":"supertest-fetch","description":"A TypeScript-friendly alternative to Supertest that uses the native Node.js WHATWG Fetch API (available since Node 18). Currently at version 2.0.0 with semantic-release based releases. Key differentiators: no dependency on superagent, avoiding @types/superagent quirks; uses native fetch for better performance and compatibility; supports both ESM and CJS; first-class TypeScript type definitions shipped with the package.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jwalton/node-supertest-fetch","tags":["javascript","supertest","api","test","node","typescript"],"install":[{"cmd":"npm install supertest-fetch","lang":"bash","label":"npm"},{"cmd":"yarn add supertest-fetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add supertest-fetch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Requires Node.js >= 18.0.0 for native fetch support","package":"node","optional":true}],"imports":[{"note":"ESM and CJS both supported; named import is correct. CJS require works but may lose TypeScript types.","wrong":"const makeFetch = require('supertest-fetch')","symbol":"makeFetch","correct":"import { makeFetch } from 'supertest-fetch'"},{"note":"Default import is also available as a convenience, but makeFetch is preferred.","wrong":"","symbol":"default import","correct":"import supertestFetch from 'supertest-fetch'"},{"note":"Type-only import to avoid runtime overhead; only available in TypeScript.","wrong":"const { FetchFunction } = require('supertest-fetch')","symbol":"FetchFunction type","correct":"import type { FetchFunction } from 'supertest-fetch'"}],"quickstart":{"code":"import http from 'http';\nimport { makeFetch } from 'supertest-fetch';\n\nconst server = http.createServer((req, res) => {\n  res.setHeader('content-type', 'application/json');\n  res.end(JSON.stringify({ greeting: 'Hello!' }));\n});\n\nconst fetch = makeFetch(server);\n\ndescribe('my server tests', function () {\n  it('should return a response', async function () {\n    await fetch('/hello')\n      .expectStatus(200)\n      .expectHeader('content-type', 'application/json')\n      .expectBody({ greeting: 'Hello!' });\n  });\n});","lang":"typescript","description":"Creates an HTTP server, wraps it with makeFetch, and tests a simple JSON response using chained assertions."},"warnings":[{"fix":"Upgrade Node to 18+ or use previous version (1.x) that used node-fetch polyfill.","message":"Requires Node.js >= 18.0.0; incompatible with older Node versions that lack native fetch.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Use .expectStatus() explicitly for status code checks.","message":".expect() overload with (statusCode, statusText) is deprecated in favor of .expectStatus(statusCode[, statusText]).","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Explicitly call server.listen() before tests and use makeFetch(server, {keepOpen: true}) to avoid auto-managed port assignment.","message":"If the server is not listening, makeFetch will call listen/close on each call, assigning a random port. This may cause port conflicts if multiple tests run concurrently without proper isolation.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use either .expectBody() for simple assertions or manually read the response for advanced checks, not both.","message":"The returned fetch function behaves like native fetch but adds assertion methods; calling .json() after .expectBody() may cause confusion if the body has already been consumed.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'18':22 '2.0.0':26 'altern':8 'api':18,67 'avail':19 'avoid':39 'base':31 'better':46 'cjs':54 'class':57 'compat':49 'current':23 'definit':60 'depend':36 'differenti':34 'esm':52 'fetch':3,17,44 'first':56 'first-class':55 'friend':7 'javascript':65 'key':33 'nativ':14,43 'node':21,69 'node.js':15 'packag':64 'perform':47 'quirk':41 'releas':30,32 'semant':29 'semantic-releas':28 'ship':61 'sinc':20 'superag':38 'supertest':2,10,66 'supertest-fetch':1 'support':50 'test':68 'type':59 'types/superagent':40 'typescript':6,58,70 'typescript-friend':5 'use':12,42 'version':25 'whatwg':16","created_at":"2026-06-07T17:01:54.781480+00:00","updated_at":"2026-06-07T17:01:54.781480+00:00","problems":[{"fix":"Use `import { makeFetch } from 'supertest-fetch'` in an ESM module or `const { makeFetch } = require('supertest-fetch')` in CJS.","cause":"Missing import or incorrect package name; using require() in ESM context without proper handling.","error":"TypeError: fetch is not a function"},{"fix":"Call server.listen() manually before tests and pass `{keepOpen: true}` option to makeFetch.","cause":"Multiple tests using the same server without keeping it open; each call to fetch() listens on a random port, causing conflicts in parallel runs.","error":"Error: listen EADDRINUSE :::0"},{"fix":"Run `npm install supertest-fetch --save-dev` and ensure Node >= 18.","cause":"Package not installed or wrong import path; or using an older Node version that doesn't resolve ESM exports correctly.","error":"Cannot find module 'supertest-fetch'"}],"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":"https://github.com/jwalton/node-supertest-fetch#readme","github":"https://github.com/jwalton/node-supertest-fetch","docs":null,"changelog":null,"pypi":null,"npm":"supertest-fetch","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}}