supertest-fetch

library2.0.0jsnpmunverified

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.

testing

npm install supertest-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SUPERTEST-FETCH

supertest-fetch

testingjavascriptv2.0.0

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.

makeFetch

✓ import { makeFetch } from 'supertest-fetch'

✗ const makeFetch = require('supertest-fetch')

ESM and CJS both supported; named import is correct. CJS require works but may lose TypeScript types.

default import

✓ import supertestFetch from 'supertest-fetch'

Default import is also available as a convenience, but makeFetch is preferred.

FetchFunction type

✓ import type { FetchFunction } from 'supertest-fetch'

✗ const { FetchFunction } = require('supertest-fetch')

Type-only import to avoid runtime overhead; only available in TypeScript.

Creates an HTTP server, wraps it with makeFetch, and tests a simple JSON response using chained assertions.

import http from 'http'; import { makeFetch } from 'supertest-fetch'; const server = http.createServer((req, res) => { res.setHeader('content-type', 'application/json'); res.end(JSON.stringify({ greeting: 'Hello!' })); }); const fetch = makeFetch(server); describe('my server tests', function () { it('should return a response', async function () { await fetch('/hello') .expectStatus(200) .expectHeader('content-type', 'application/json') .expectBody({ greeting: 'Hello!' }); }); });

Debug

Known issues

breakingRequires Node.js >= 18.0.0; incompatible with older Node versions that lack native fetch.

fix

Upgrade Node to 18+ or use previous version (1.x) that used node-fetch polyfill.

affects: <2.0.0

deprecated.expect() overload with (statusCode, statusText) is deprecated in favor of .expectStatus(statusCode[, statusText]).

fix

Use .expectStatus() explicitly for status code checks.

affects: >=2.0.0

gotchaIf 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.

fix

Explicitly call server.listen() before tests and use makeFetch(server, {keepOpen: true}) to avoid auto-managed port assignment.

affects: >=0.0.0

gotchaThe 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.

fix

Use either .expectBody() for simple assertions or manually read the response for advanced checks, not both.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: fetch is not a function

Missing import or incorrect package name; using require() in ESM context without proper handling.

fix

Use `import { makeFetch } from 'supertest-fetch'` in an ESM module or `const { makeFetch } = require('supertest-fetch')` in CJS.

Error: listen EADDRINUSE :::0

Multiple tests using the same server without keeping it open; each call to fetch() listens on a random port, causing conflicts in parallel runs.

fix

Call server.listen() manually before tests and pass `{keepOpen: true}` option to makeFetch.

Cannot find module 'supertest-fetch'

Package not installed or wrong import path; or using an older Node version that doesn't resolve ESM exports correctly.

fix

Run `npm install supertest-fetch --save-dev` and ensure Node >= 18.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

nodeoptionalRequires Node.js >= 18.0.0 for native fetch support

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/jwalton/node-supertest-fetch ↗

packagesupertest-fetch ↗

homepagehttps://github.com/jwalton/node-supertest-fetch#readme ↗