{"id":10682,"library":"create-test-server","title":"Create Test Server","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/lukechilds/create-test-server","tags":["javascript","create","test","server","mock","nock","testing","ci","unit"],"install":[{"cmd":"npm install create-test-server","lang":"bash","label":"npm"},{"cmd":"yarn add create-test-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add create-test-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The library is built on Express.js to provide its web server functionalities for handling routes and middleware.","package":"express","optional":false}],"imports":[{"note":"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.","wrong":"import { createTestServer } from 'create-test-server';","symbol":"createTestServer (ESM Default)","correct":"import createTestServer from 'create-test-server';"},{"note":"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.","wrong":"const { createTestServer } = require('create-test-server');","symbol":"createTestServer (CommonJS Direct)","correct":"const createTestServer = require('create-test-server');"},{"note":"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`.","wrong":"import { TestServer } from 'create-test-server';","symbol":"TestServer (Interface)","correct":"import type { TestServer } from 'create-test-server';"}],"quickstart":{"code":"import test from 'ava';\nimport got from 'got';\nimport createTestServer from 'create-test-server';\n\ntest('should respond to a basic GET request with text', async t => {\n  const server = await createTestServer();\n  server.get('/hello', 'world');\n\n  const response = await got(`${server.url}/hello`);\n  t.is(response.body, 'world');\n\n  await server.close();\n});\n\ntest('should handle POST requests with JSON body', async t => {\n  const server = await createTestServer();\n  server.post('/data', (req, res) => {\n    res.json({ received: req.body });\n  });\n\n  const testData = { message: 'hello from client' };\n  const response = await got.post(`${server.url}/data`, {\n    json: testData,\n    responseType: 'json'\n  });\n\n  t.deepEqual(response.body, { received: testData });\n  await server.close();\n});\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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`).","severity":"breaking","affected_versions":">=2.0"},{"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 })`).","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Always use `server.url` and `server.sslUrl` properties to get the dynamically assigned ports for each test run. Do not hardcode port numbers.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Always `await createTestServer()` before interacting with the returned `server` object, especially in asynchronous test functions: `const server = await createTestServer();`.","message":"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.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `createTestServer()` is `await`ed. Example: `const server = await createTestServer(); server.get('/foo', 'bar');`","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.","error":"TypeError: server.get is not a function"},{"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`).","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.","error":"Error: self-signed certificate in certificate chain"},{"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.","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.","error":"ERR_REQUIRE_ESM"}],"ecosystem":"npm"}