Create Test Server

3.0.1 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: server.get is not a function
```
cause 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
```
cause 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
```
cause 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.

Warnings

breaking Direct 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.
gotcha When 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 })`).
gotcha Ports 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.
gotcha The `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();`.

Install

npm install create-test-server npm
yarn add create-test-server yarn
pnpm add create-test-server pnpm

Imports

createTestServer (ESM Default)
wrong:
```
import { createTestServer } from 'create-test-server';
```
correct:
```
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)
wrong:
```
const { createTestServer } = require('create-test-server');
```
correct:
```
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)
wrong:
```
import { TestServer } from 'create-test-server';
```
correct:
```
import type { 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`.

Quickstart

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();
});

view raw JSON →