Registry / testing / create-test-server

create-test-server

library3.0.1jsnpmunverified

create-test-server is a utility that creates a minimal Express.js server for robust HTTP and HTTPS testing, operating on randomly chosen ports. It automatically generates self-signed SSL certificates with an associated CA certificate, enabling authenticated SSL requests in test environments. Currently at version 3.0.1, its release cadence follows semantic versioning, with major versions indicating breaking changes. A key differentiator is its approach to testing: instead of fragile HTTP mocking that can break across Node.js versions (e.g., Nock), it advocates for testing against a real, locally running server. It handles JSON, plain text, URL-encoded forms, and buffer bodies by default, making it versatile for various API testing scenarios. The library provides a Promise-based API that integrates seamlessly with modern asynchronous test runners like AVA.

testing http-networking serialization

npm install create-test-server

github ↗package ↗

INSTALL

IMPORT

SIG · CREATE-TEST-SERVER

create-test-server

testingjavascriptv3.0.1

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.

createTestServer (ESM Default)

✓ import createTestServer from 'create-test-server';

✗ import { createTestServer } from 'create-test-server';

For ESM (ECMAScript Modules) environments, `createTestServer` is provided as the default export. Attempting a named import will typically result in an undefined symbol or an error.

createTestServer (CommonJS Direct)

✓ const createTestServer = require('create-test-server');

✗ const { createTestServer } = require('create-test-server');

In CommonJS environments, the module directly exports the `createTestServer` function. Trying to destructure it as a named export will not work as the module itself is the function.

TestServer (Interface)

✓ import type { TestServer } from 'create-test-server';

✗ import { TestServer } from 'create-test-server';

While the core `createTestServer` function is the primary export, for TypeScript users, type definitions are available via `@types/create-test-server` (installed separately). The `TestServer` type represents the object returned by `createTestServer()`, providing type hints for its methods like `get`, `post`, `url`, `sslUrl`, and `close`.

Demonstrates creating a test server, defining a simple GET route that returns text, and a POST route that processes a JSON body. It then uses the `got` library to make requests and `ava` for assertions, showcasing both HTTP and Express-like request handling, followed by proper server cleanup.

import test from 'ava'; import got from 'got'; import createTestServer from 'create-test-server'; test('should respond to a basic GET request with text', async t => { const server = await createTestServer(); server.get('/hello', 'world'); const response = await got(`${server.url}/hello`); t.is(response.body, 'world'); await server.close(); }); test('should handle POST requests with JSON body', async t => { const server = await createTestServer(); server.post('/data', (req, res) => { res.json({ received: req.body }); }); const testData = { message: 'hello from client' }; const response = await got.post(`${server.url}/data`, { json: testData, responseType: 'json' }); t.deepEqual(response.body, { received: testData }); await server.close(); });

Debug

Known issues

breakingDirect access to internal Express application instance or raw HTTP/HTTPS server properties was removed or changed to private in a prior major version for API stability. Rely only on the documented `server` object methods and properties (e.g., `server.get`, `server.url`).

fix

Refactor code to use the exposed methods and properties of the `server` object returned by `createTestServer()`. Avoid accessing `server.app`, `server.http`, or `server.https` directly if these were previously used.

affects: >=2.0

gotchaWhen making HTTPS requests to `create-test-server`, clients like `got` will by default reject self-signed certificates. This requires specific client configuration to either trust the generated CA certificate or explicitly bypass certificate validation.

fix

For authenticated SSL, pass `ca: server.caCert` to your HTTP client and set the `Host` header to match the `certificate` option provided during server creation (e.g., `createTestServer({ certificate: 'foobar.com' })`). Alternatively, for unauthenticated but encrypted connections, set `rejectUnauthorized: false` on your client (e.g., `got(url, { rejectUnauthorized: false })`).

affects: >=1.0

gotchaPorts for HTTP and HTTPS are chosen randomly by default upon each server instantiation. Relying on fixed ports for testing will lead to conflicts or failures.

fix

Always use `server.url` and `server.sslUrl` properties to get the dynamically assigned ports for each test run. Do not hardcode port numbers.

affects: >=1.0

gotchaThe `createTestServer()` function returns a Promise. Forgetting to `await` its resolution will lead to errors as you try to access properties (`.url`, `.get`, etc.) on an unresolved Promise.

fix

Always `await createTestServer()` before interacting with the returned `server` object, especially in asynchronous test functions: `const server = await createTestServer();`.

affects: >=1.0

Errors

Common errors & fixes

TypeError: server.get is not a function

Attempting to call methods on the `server` object before the `createTestServer()` Promise has resolved, meaning `server` is still a Promise, not the resolved server object.

fix

Ensure `createTestServer()` is `await`ed. Example: `const server = await createTestServer(); server.get('/foo', 'bar');`

Error: self-signed certificate in certificate chain

An HTTP client (like `got`) is trying to make an HTTPS request to the test server but does not trust the auto-generated self-signed certificate, rejecting the connection.

fix

When making HTTPS requests, either provide the `server.caCert` to your client and set the `Host` header to match the server's certificate common name, or disable SSL certificate validation in the client (e.g., `rejectUnauthorized: false` for `got`).

ERR_REQUIRE_ESM

Attempting to use `require()` to import `create-test-server` in an environment configured for ESM (e.g., `"type": "module"` in `package.json`), or trying to `import` it with named imports in ESM.

fix

If in ESM, use `import createTestServer from 'create-test-server';`. If in CommonJS, use `const createTestServer = require('create-test-server');`. Ensure your project's module system configuration aligns with your import statements.

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

expressrequiredThe library is built on Express.js to provide its web server functionalities for handling routes and middleware.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lukechilds/create-test-server ↗

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