Skip to main content

Minimal Express server for tests, simpler

Works with
It is unknown whether this package works with Bun
It is unknown whether this package works with Cloudflare Workers
This package works with Node.js
It is unknown whether this package works with Deno
JSR Score
64%
Published
2 months ago (3.2.0)

@osa413/create-test-server

Minimal Express server for tests, simpler

[Build Status] [Coverage Status] npm npm

Fork of @lukechilds's create-test-server that removes HTTPS requirement and adds some fresh ingredients.

Supports both legacy (Jest) and modern (vitest) test runners.

Original project inspired by the createServer() helper function in the Got tests.

A simple interface for creating a preconfigured Express instance listening for HTTP traffic.

Install

npm i -D @osa413/create-test-server

Usage

Forward slash at the beginning of endpoint name is important

import createTestServer from "@osa413/create-test-server";

const server = await createTestServer();
console.log(server.url);
// http://localhost:5486

// This is just an Express route
// You could use any Express middleware too
// **Forward slash at the beginning of endpoint name is important**
server.get('/foo', (req, res) => {
  res.send('bar');
});

// You can return a body directly too
// **Forward slash at the beginning of endpoint name is important**
server.get('/foo', () => 'bar');
server.get('/foo', 'bar');

// server.url + '/foo' will respond with 'bar'

The following Content-Type headers will be parsed and exposed via req.body:

  • JSON (application/json)
  • Text (text/plain)
  • URL-encoded form (application/x-www-form-urlencoded)
  • Buffer (application/octet-stream)

You can change body parsing behaviour with the bodyParser option.

You can use createTestServer() with your favourite test runners, such as Jest or Vitest.

You can create a separate server per test:

import {test, expect} from 'vitest';
import axios from 'axios';
import createTestServer from "@osa413/create-test-server";

test(async () => {
  const server = await createTestServer();
  server.get('/foo', 'bar');

  const response = await axios.get(`${server.url}/foo`);
  expect(response.body).toEqual('bar');

  await server.close();
});

Or share a server across multiple tests:

let server;

beforeAll(async () => {
  server = await createTestServer();
  server.get('/foo', 'bar');
});

test(async () => {
  const response = await axios.get(`${server.url}/foo`);
  expect(response.body).toEqual('bar');
});

test(async () => {
  const response = await axios.get(`${server.url}/foo`);
  expect(response.statusCode).toEqual(200);
});

afterAll(async () => {
  await server.close();
});

You can also easily stop/restart the server. Notice how a new port is used when we listen again:

const server = await createTestServer();
console.log(server.port);
// 56711

await server.close();
console.log(server.port);
// undefined

await server.listen();
console.log(server.port);
// 56804

API

createTestServer([options])

Returns a Promise which resolves to an (already listening) server.

options

Type: object

options.bodyParser

Type: object | boolean
Default: undefined

Body parser options object to be passed to body-parser methods.

If set to false then all body parsing middleware will be disabled.

server

Express instance resolved from createTestServer()

This is just a normal Express instance with a few extra properties.

server.url

Type: string, undefined

The url you can reach the HTTP server on.

e.g: 'http://localhost:5486'

undefined while the server is not listening.

server.port

Type: number, undefined

The port number you can reach the HTTP server on.

e.g: 5486

undefined while the server is not listening.

server.http

Type: http.server

The underlying HTTP server instance.

server.listen()

Type: function

Returns a Promise that resolves when the HTTP server is listening.

Once the server is listening, server.url will be updated.

Please note, this function doesn't take a port argument, it uses a new randomised port each time. Also, you don't need to manually call this after creating a server, it will start listening automatically.

server.close()

Type: function

Returns a Promise that resolves when the HTTP server has stopped listening.

Once the servers have stopped listening, server.url will be set to undefined.

Add Package

deno add @osa413/create-test-server

Import symbol

import * as mod from "@osa413/create-test-server";

Add Package

npx jsr add @osa413/create-test-server

Import symbol

import * as mod from "@osa413/create-test-server";

Add Package

yarn dlx jsr add @osa413/create-test-server

Import symbol

import * as mod from "@osa413/create-test-server";

Add Package

pnpm dlx jsr add @osa413/create-test-server

Import symbol

import * as mod from "@osa413/create-test-server";

Add Package

bunx jsr add @osa413/create-test-server

Import symbol

import * as mod from "@osa413/create-test-server";