externalManageALocalServer

An Ability that enables an Actor to manage a local Node.js server.

Managing a raw Node.js server

import { actorCalled } from '@serenity-js/core'
import { CallAnApi, GetRequest, Send } from '@serenity-js/rest'
import { ManageALocalServer, LocalTestServer, StartLocalTestServer, StopLocalTestServer } from '@serenity-js/local-server'
import { Ensure, equals } from '@serenity-js/assertions'

import * as axios from 'axios'
import * as http from 'http'

const server = http.createServer(function (request, response) {
  response.setHeader('Connection', 'close');
  response.end('Hello!');
})

await actorCalled('Apisit')
  .whoCan(
    ManageALocalServer.using(server),
    CallAnApi.using(axios.create()),
  )
  .attemptsTo(
    StartLocalTestServer.onRandomPort(),
    Send.a(GetRequest.to(LocalServer.url())),
    Ensure.that(LastResponse.status(), equals(200)),
    Ensure.that(LastResponse.body<string>(), equals('Hello!')),
    StopLocalTestServer.ifRunning(),
  )

Learn more

• Anatomy of an HTTP transaction
• Node.js HTTP server

Hierarchy

• Ability
  • ManageALocalServer

Index

Constructors

• constructor

Methods

• runningAHttpListener
• runningAHttpsListener
• toJSON
• abilityType
• listen
• mapInstance

Constructors

externalconstructor

• new ManageALocalServer(protocol: SupportedProtocols, server: Server): ManageALocalServer

• Overrides Ability.constructor

  @see

  https://www.npmjs.com/package/http-shutdown

  ---

  Parameters

  • externalprotocol: SupportedProtocols

    Protocol to be used when communicating with the running server; http or https

  • externalserver: Server

    A Node.js server requestListener, with support for server shutdown.

  Returns ManageALocalServer

Methods

staticexternalrunningAHttpListener

• runningAHttpListener(listener: RequestListener | Server): ManageALocalServer

• An Ability to manage a Node.js HTTP server using the provided requestListener.

  ---

  Parameters

  • externallistener: RequestListener | Server

  Returns ManageALocalServer

staticexternalrunningAHttpsListener

• runningAHttpsListener(listener: RequestListener | Server<typeof IncomingMessage, typeof ServerResponse>, options?: ServerOptions<typeof IncomingMessage, typeof ServerResponse>): ManageALocalServer

• An Ability to manage a Node.js HTTPS server using the provided server requestListener.

  @see

  https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener

  ---

  Parameters

  • externallistener: RequestListener | Server<typeof IncomingMessage, typeof ServerResponse>

  • externaloptions: ServerOptions<typeof IncomingMessage, typeof ServerResponse> = {}

    Accepts an options object from tls.createServer(), tls.createSecureContext() and http.createServer().

  Returns ManageALocalServer

externaltoJSON

• toJSON(): SerialisedAbility

• Inherited from Ability.toJSON

  Returns a JSON representation of the ability and its current state, if available. The purpose of this method is to enable reporting the state of the ability in a human-readable format, rather than to serialise and deserialise the ability itself.

  ---

  Returns SerialisedAbility

externalabilityType

• abilityType(): AbilityType<Ability>

• Inherited from Ability.abilityType

  Returns the most abstract type of this Ability instance, specifically the first class in the inheritance hierarchy that directly extends the Ability class.

  import { Ability } from '@serenity-js/core';
  
  class MyAbility extends Ability {}
  class MySpecialisedAbility extends MyAbility {}
  
  new MyAbility().abilityType();            // returns MyAbility
  new MySpecialisedAbility().abilityType(); // returns MyAbility

  ---

  Returns AbilityType<Ability>

externallisten

• listen(preferredPort?: number, highestPort?: number): Promise<void>

• Starts the server on the first free port between preferredPort and highestPort, inclusive.

  ---

  Parameters

  • externaloptionalpreferredPort: number = 8000

    Lower bound of the preferred port range

  • externaloptionalhighestPort: number = 65535

    highestPort Upper bound of the preferred port range

  Returns Promise<void>

externalmapInstance

• mapInstance<T>(fn: (server: ServerWithShutdown, protocol?: SupportedProtocols) => T): T

• Provides access to the server requestListener

  ---

  Type parameters

  • T

  Parameters

  • externalfn: (server: ServerWithShutdown, protocol?: SupportedProtocols) => T

  Returns T