Skip to main content

external@serenity-js/local-server

NPM Version Build Status Maintainability Code Coverage Contributors Known Vulnerabilities GitHub stars

Follow Serenity/JS on LinkedIn Watch Serenity/JS on YouTube Join Serenity/JS Community Chat Support Serenity/JS on GitHub

@serenity-js/local-server enables Serenity/JS actors to manage local HTTP or HTTPS test servers.

Features​

  • Supports local servers based on Express, Hapi, Koa, Restify, or raw Node.js.
  • Use it to manage test doubles, mock APIs, or simulate backend services.
  • Works seamlessly with all Serenity/JS test runners

Installation​

npm install --save-dev @serenity-js/core @serenity-js/local-server

See the Serenity/JS Installation Guide.

Quick Start​

import { actorCalled } from '@serenity-js/core'
import {
    ManageALocalServer, StartLocalServer, StopLocalServer
} from '@serenity-js/local-server'
import { CallAnApi, GetRequest, Send } from '@serenity-js/rest'
import { Ensure, equals } from '@serenity-js/assertions'
import axios from 'axios'

import { requestListener } from './listener'                    // (1)

const actor = actorCalled('Apisit').whoCan(
    ManageALocalServer.runningAHttpListener(requestListener),   // (2)
    CallAnApi.using(axios.create()),
)

await actor.attemptsTo(
    StartLocalServer.onRandomPort(),                            // (3)
    Send.a(GetRequest.to(LocalServer.url())),                   // (4)
    Ensure.that(LastResponse.status(), equals(200)),
    Ensure.that(LastResponse.body(), equals('Hello!')),
    StopLocalServer.ifRunning(),                                // (5)
)

In the above example:

  1. Import a requestListener to use in your test.
  2. Give the actor an ability to ManageALocalServer. This enables the interactions to StartLocalServer and StopLocalServer, as well as the LocalServer question.
  3. Start the local server on a random port, specific port, or a random port within your preferred port range.
  4. Use the LocalServer.url() question to retrieve the url of the local server and interact with its HTTP API.
  5. Stop the local server is when the test is complete. Please note that you probably want to StopLocalServer in an afterEach block of your test (or something equivalent) to make sure that the server is correctly shut down even when the test fails.

Explore practical examples and in-depth explanations in the Serenity/JS Handbook.

Creating a server​

ManageALocalServer supports any requestListener accepted by Node's http.createServer or https.createServer.

Below are example implementations of a simple HTTP server that would satisfy the above test.

Raw Node.js​

// listener.js
module.exports.requestListener = (request, response) => {
  response.setHeader('Connection', 'close')
  response.end('Hello World!')
}

Learn more about Node.js.

Express​

// listener.js
const express = require('express')

module.exports.requestListener = express().
    get('/', (req: express.Request, res: express.Response) => {
        res.status(200).send('Hello World!')
    })

Learn more about Express.

HAPI​

// listener.js
const hapi = require('@hapi/hapi')

const server = new hapi.Server()
server.route({ method: 'GET', path: '/', handler: (req, h) => 'Hello World!' })

module.exports.requestListener = server.listener

Learn more about HAPI.

Koa​

// listener.js
const Koa = require('koa')

module.exports.requestListener = new Koa()
    .use(ctx => Promise.resolve(ctx.body = 'Hello World!'))
    .callback()

Learn more about Koa.

Restify​

// listener.js
const restify = require('restify')

const server = restify.createServer(options)

server.get('/', (req, res, next) => {
    res.send('Hello World!')
})

module.exports.requestListener = server

Learn more about Restify.

Documentation​

Contributing​

Contributions of all kinds are welcome! Get started with the Contributing Guide.

Community​

If you enjoy using Serenity/JS, make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

License​

The Serenity/JS code base is licensed under the Apache-2.0 license, while its documentation and the Serenity/JS Handbook are licensed under the Creative Commons BY-NC-SA 4.0 International.

See the Serenity/JS License.

Support​

Support ongoing development through GitHub Sponsors. Sponsors gain access to Serenity/JS Playbooks and priority help in the Discussions Forum.

For corporate sponsorship or commercial support, please contact Jan Molak.

GitHub Sponsors.

Index

Abilities

Activities

Models

Questions

Type Aliases

Type Aliases

externalRequestListener

RequestListener: (request: http.IncomingMessage, response: http.ServerResponse) => void

A requestListener function accepted by Node's http.createServer or https.createServer.

Type declaration

    • (request: http.IncomingMessage, response: http.ServerResponse): void

    • Parameters

      • externalrequest: http.IncomingMessage
      • externalresponse: http.ServerResponse

      Returns void

externalServerWithShutdown

ServerWithShutdown: net.Server & { shutdown: (callback: (error?: Error) => void) => void; forceShutdown: (callback: (error?: Error) => void) => void }

A net.Server with an additional shutdown method.

Page Options