Registry / testing / fetch-test-server

fetch-test-server

library1.2.0jsnpmunverified

fetch-test-server is a utility library for Node.js integration testing, enabling developers to test their HTTP servers (including frameworks like Express and Koa) using the modern Fetch API. As of version 1.2.0, it leverages native ES6 features and promises, providing an async/await-friendly alternative to callback-based testing libraries such as SuperTest. The library operates by starting the user's HTTP server on a random available port, internally using `node-fetch` to make requests. It intelligently defers server startup until the first request is made, streamlining the test setup process. Its release cadence appears moderate, with recent updates focusing on modern JavaScript features. This package differentiates itself by offering a familiar browser-like API for server interactions directly within Node.js test environments.

testing http-networking web-framework

npm install fetch-test-server

github ↗package ↗

INSTALL

IMPORT

SIG · FETCH-TEST-SERVER

fetch-test-server

testingjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

TestServer

✓ import { TestServer } from 'fetch-test-server'

✗ const TestServer = require('fetch-test-server')

Since v1.1.0, the package uses natively supported ES6 features and is primarily designed for ES Module imports. CommonJS `require()` will not work.

This quickstart demonstrates setting up an Express server and testing its API endpoints using `fetch-test-server` with `async/await` syntax, showing GET and POST requests with JSON bodies and custom headers. It also includes server lifecycle management.

/* file: myapp.js */ import express from 'express'; const app = express(); app.use(express.json()); // For parsing application/json app.get('/user', (req, res) => { res.status(200).json({ name: 'Adrian' }); }); app.post('/users', (req, res) => { res.status(201).json({ status: 'created', data: req.body }); }); export default app; /* file: test.js (run with Mocha or Jest) */ import { assert } from 'chai'; import { TestServer } from 'fetch-test-server'; import app from './myapp.js'; // Ensure .js extension for ESM // Optionally, if your TestServer might be a default export in some setups // import TestServer from 'fetch-test-server'; describe('API Integration Test', () => { let server; before(() => { server = new TestServer(app); }); after(async () => { await server.close(); // Clean up the server after tests }); it('responds to /user with async/await', async () => { const res = await server.fetch('/user'); const body = await res.json(); assert.strictEqual(res.status, 200); assert.strictEqual(body.name, 'Adrian'); }); it('sends JSON body and custom headers with post', async () => { const res = await server.post('/users', { headers: { 'X-Auth': 'secret-token' }, body: { item: 'new-user' }, // Automatically JSON-encoded }); const body = await res.json(); assert.strictEqual(res.status, 201); assert.deepStrictEqual(body.data, { item: 'new-user' }); }); it('allows manual server startup and exposes address', async () => { await server.listen(); assert.match(server.address, /^http:\/\/127\.0\.0\.1:\d+$/); }); }); // To run this example: // npm init -y // npm install --save-dev fetch-test-server express mocha chai

Debug

Known issues

breakingVersion 1.1.0 introduced a rewrite using 'natively supported ES6 features', which implies a transition to ES Modules. This breaks compatibility for projects using CommonJS `require()` syntax.

fix

Migrate your test files and project configuration to use ES Modules. This typically involves changing `require()` to `import` statements and ensuring your `package.json` has `"type": "module"` or using `.mjs` file extensions for your test files.

affects: >=1.1.0

gotchaThe `TestServer` instance does not immediately start listening on a port upon instantiation. The HTTP server only starts when the first request is made via `server.fetch()` or explicitly by calling `server.listen()`.

fix

Be aware that server resources are not consumed until the first request. If you need the server address or explicit control over startup, call `await server.listen()` before making requests or accessing `server.address`.

affects: >=1.0.0

gotchaWhen testing Koa applications, you must pass `app.callback()` to the `TestServer` constructor, not the Koa `Application` instance directly. This is due to Koa's architecture expecting a middleware function for HTTP server integration.

fix

Instead of `new TestServer(app)`, use `new TestServer(app.callback())` for Koa applications.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope at file://<path>/test.js:1:19 at ModuleJob.run (node:internal/modules/esm/module_job:194:25)

Attempting to use CommonJS `require()` in an ES Module environment (or with a version of `fetch-test-server` that is ESM-only).

fix

Switch to ES Module `import` syntax: `import { TestServer } from 'fetch-test-server';`. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions for ES Modules.

TypeError: The 'listener' argument must be of type function. Received an instance of Application

Occurs when passing a Koa `Application` object directly to `TestServer` constructor instead of its `callback()` method.

fix

For Koa apps, instantiate `TestServer` with `new TestServer(app.callback())`.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

node-fetchrequiredInternal implementation of the Fetch API for Node.js environments.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/amacneil/fetch-test-server ↗

packagehttps://www.npmjs.com/package/fetch-test-server ↗