Serenity/JS

Serenity/JS is an innovative open-source framework designed to make acceptance and regression testing of complex software systems faster, more collaborative and easier to scale.

⭐️ Get started with Serenity/JS!

• Serenity/JS web testing tutorial
• Serenity/JS Handbook and Getting Started guides
• API documentation
• Serenity/JS Project Templates on GitHub

👋 Join the Serenity/JS Community!

• Meet other Serenity/JS developers and maintainers on the Serenity/JS Community chat channel,
• Find answers to your Serenity/JS questions on the Serenity/JS Forum,
• Learn how to contribute to Serenity/JS,
• Support the project and gain access to Serenity/JS Playbooks by becoming a Serenity/JS GitHub Sponsor!

Serenity/JS Local Server

@serenity-js/local-server enables Serenity/JS Actors to manage local HTTP or HTTPS test servers powered by Express, Hapi, Koa, Restify or raw Node.js.

Installation

To install this module, run the following command in your computer terminal:

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

To learn more about Serenity/JS and how to use it on your project, follow the Serenity/JS Getting Started guide.

Example test

import { actorCalled } from '@serenity-js/core'
import {
    ManageALocalServer, StartLocalTestServer, StopLocalTestServer
} 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.using(requestListener),                          (2)
    CallAnApi.using(axios.create()),
)

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

In the above example:

1. A requestListener to be tested is imported.
2. The Actor is given an Ability to ManageALocalServer. This enables the Interaction to StartLocalTestServer and StopLocalTestServer, as well as the LocalServer Question.
3. The local server is started on a random port, although you can specify a port range if you prefer.
4. The url of the local server is retrieved and used to test an interaction with its HTTP API.
5. The local server is stopped when the test is complete. Please note that you probably want to StopLocalTestServer 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.

Creating a server

Any requestListener that Node's http.createServer or https.createServer would accept can be used with ManageALocalServer.

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.

📣 Stay up to date

New features, tutorials, and demos are coming soon! Follow Serenity/JS on LinkedIn, subscribe to Serenity/JS channel on YouTube and join the Serenity/JS Community Chat to stay up to date! Please also make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

💛 Support Serenity/JS

If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!