Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



Simple promise to wait for server ready inside a mocha specification

License:MIT npm Vulnerabilities Build

server-listening is just a little helper utility to reduce the amount of boilerplate code needed to startup servers when running mocha specifications.

A) Setup

Install package:

$ npm install --save-dev server-listening

Import package:

import { serverListening } from 'server-listening';

Or if using the older CommonJS format:

const { serverListening } = require('server-listening');  //deprecated

B) Usage

The original low-level API is described below.Β  For the newer high-level API to start a web server (localhost) and load a web page (jsdom), see start-web-server.spec.js and load-web-page.spec.js (for similar functionality using Puppeteer instead, see the puppeteer-browser-ready project).

1. Mocha specification file

import { server } from '../server.js';
before(() => serverListening.ready(server));
after(() =>  serverListening.close(server));

Example usage:

2. setPort() options

The setPort(options) function is just a handy way to set the environment variable for the HTTP port.Β  This function is for convenience and is not required.

serverListening.setPort({ port: 9000 });
Option Meaning Default
port Port number for server (0 means choose an unused port). 0
name Environment variable name to store port number. 'port'

3. Leveraging promises

The ready(server) and close(server) functions return a promise, enabling chaining of operations.

For example, a port variable could be set after the server is ready using:

let port;
before(() => serverListening.ready(server).then(() => port = server.address().port));

4. jsdom support

The two helper functions jsdomOnLoad() and jsdomCloseWindow() can be used with the JSDOM.fromURL() function to load a web page before the mocha tests run and then close the window when the tests are finished.

// Imports
import { assertDeepStrictEqual } from 'assert-deep-strict-equal';
import { serverListening } from 'server-listening';
import { JSDOM } from 'jsdom';

// Setup
const url = '';
const jsdomOptions = { resources: 'usable', runScripts: 'dangerously' };
let dom;
const loadWebPage = () => JSDOM.fromURL(url, jsdomOptions)
   .then((jsdom) => dom = jsdom);
const closeWebPage = () => serverListening.jsdomCloseWindow(dom);

describe('The web page', () => {

   it('has the correct URL -> ' + url, () => {
      const actual =   { url: dom.window.location.href };
      const expected = { url: url };
      assertDeepStrictEqual(actual, expected);

   it('has exactly one header, main, and footer', () => {
      const $ = dom.window.$;
      const actual =   {
         header: $('body >header').length,
         main:   $('body >main').length,
         footer: $('body >footer').length,
      const expected = { header: 1, main: 1, footer: 1 };
      assertDeepStrictEqual(actual, expected);


describe('The document content', () => {

   it('has a πŸš€ traveling to πŸͺ!', () => {
      const html = dom.window.document.documentElement.outerHTML;
      const actual =   { 'πŸš€': !!html.match(/πŸš€/g), 'πŸͺ': !!html.match(/πŸͺ/g) };
      const expected = { 'πŸš€': true,                'πŸͺ': true };
      assertDeepStrictEqual(actual, expected);


Above mocha test will output:

  The web page
    βœ“ has the correct URL ->
    βœ“ has exactly one header, main, and footer

  The document content
    βœ“ has a πŸš€ traveling to πŸͺ!

Example of loading a web page into jsdom from a local node server:

5. TypeScript declarations

The TypeScript Declaration File file is server-listening.d.ts in the dist folder.

The declarations provide type information about the API, such as the options for calling serverListening.setPort()::

type ServerListeningOptions = {
   port?:  number,  //0 = find unused port
   name?:  string,  //environment variable to pass port number

C) Hello World Example

To try out server-listening locally, enter the following terminal commands:

$ git clone
$ cd server-listening/hello-world
$ npm install
$ npm test


You can also run the server locally:

$ npm start

and then use a browser to view the 'Hello, World!' message at: http://localhost:3300

server-listening is open source under the MIT License.