http-test-server

library3.0.0jsnpmunverified

A simple, promise-based HTTP server for integration testing in Node.js. v3.0.0 provides an async factory function that starts a server on a random port and returns an object with `baseUrl` and `shutdown()` method. It supports automatic shutdown and collects request body as Buffer. Unlike alternatives like `nock` or `supertest`, this uses a real HTTP server, making it suitable for end-to-end API testing. Released with TypeScript definitions. Maintenance mode since 2022.

testing http-networking

npm install http-test-server

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-TEST-SERVER

http-test-server

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

default

✓ import httpTestServer from 'http-test-server'

✗ import { httpTestServer } from 'http-test-server'

The module exports a default async function. Named import will not work.

default

✓ const httpTestServer = require('http-test-server')

✗ const { httpTestServer } = require('http-test-server')

In CommonJS, require returns the default export directly.

ShutdownOptions

✓ import type { ShutdownOptions } from 'http-test-server'

TypeScript users can import `ShutdownOptions` type from the package's types.

Creates a server that echoes the request URL, sends a GET request, and shuts down.

import httpTestServer from 'http-test-server'; import got from 'got'; const server = await httpTestServer((req, res) => { res.end(req.url); }); const { body } = await got(`${server.baseUrl}/hello`); console.log(body); // '/hello' await server.shutdown();

Debug

Known issues

breakingThe server is started asynchronously; you must await the function call. Not doing so leads to undefined behavior.

fix

Use `await httpTestServer(handler)` to obtain the server object.

affects: >=3.0.0

gotchaThe request body is collected as a Buffer via stream-to-promise. It is only available after the handler is called; do not access `req.body` before reading the stream yourself.

fix

Access `req.body` inside the request handler; it will be a Buffer if the client sends a body.

affects: >=3.0.0

deprecatedThe `baseUrl` property includes protocol and port but no trailing slash. Concatenating paths directly may lead to double slashes if path starts with '/'.

fix

Use URL constructor: `new URL('/foo', server.baseUrl).href` to avoid double slashes.

affects: >=3.0.0

gotchaThe server listens on a random port (port 0). That port must be free on the system, but conflicts are unlikely.

fix

No action needed; the OS assignes a free port automatically.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: httpTestServer is not a function

Incorrect import; using named import instead of default.

fix

Use `import httpTestServer from 'http-test-server'` (default import).

Cannot read properties of undefined (reading 'baseUrl')

Not awaiting the httpTestServer call; server object is a promise.

fix

Add `await` before httpTestServer: `const server = await httpTestServer(...)`.

Error: read ECONNRESET

Making requests before server is fully started (race condition).

fix

Ensure the server promise resolves before using server.baseUrl.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

http-shutdownrequiredEnsures graceful shutdown of the HTTP server, preventing hanging sockets in tests.

stream-to-promiserequiredConverts the incoming request stream to a promise that resolves to the full body Buffer.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/kesla/http-test-server ↗

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