Skip to main content

external@serenity-js/core

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/core provides foundational building blocks of the Serenity/JS ecosystem, enabling clean, expressive, and highly maintainable test automation based on the Screenplay Pattern. This package provides APIs and extension points used across all Serenity/JS modules.

Features​

  • Core APIs for implementing the Screenplay Pattern in automated tests.
  • Actor lifecycle and abilities management for clear, maintainable test orchestration.
  • Flexible integration points with test runners and reporting tools.
  • TypeScript-first design with strong typing for safer and more predictable test code.

Installation​

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

See the Serenity/JS Installation Guide.

Quick Start​

import { actorCalled } from '@serenity-js/core'

await actorCalled('Alice')
    .whoCan(
        // Add abilities
    )
    .attemptsTo(
        // Add tasks and interactions
    )

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

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

Actors

Errors

Expectations

Notes

Questions

Screenplay Pattern

Serenity

Stage

Time

Abilities

externalAbilityType

AbilityType<A>: abstract new (...args: any[]) => A & { as: any; abilityType: any }

An interface describing the static access method that every Ability class needs to provide in order to be accessible from within the interactions.

Retrieving an ability from an interaction

import { Ability, Answerable, actorCalled, Interaction, the } from '@serenity-js/core';

class MakePhoneCalls extends Ability {
  static using(phone: Phone) {
    return new MakePhoneCalls(phone);
  }

  protected constructor(private readonly phone: Phone) {
  }

  // some method that allows us to interact with the external interface of the system under test
  dial(phoneNumber: string): Promise<void> {
    // ...
  }
}

const Call = (phoneNumber: Answerable<string>) =>
  Interaction.where(the`#actor calls ${ phoneNumber }`, async actor => {
    await MakePhoneCalls.as(actor).dial(phoneNumber)
  });

await actorCalled('Connie')
  .whoCan(MakePhoneCalls.using(phone))
  .attemptsTo(
    Call(phoneNumber),
  )

Learn more

Type parameters

Expectations

externalPredicate

Predicate<Actual>: (actor: AnswersQuestions, actual: Answerable<Actual>) => Promise<ExpectationOutcome> | ExpectationOutcome

Type parameters

  • Actual

Type declaration

Questions

externalAnswerable

Answerable<T>: Question<Promise<T>> | Question<T> | Promise<T> | T

A union type that provides a convenient way to represent any value that can be resolved by Actor.answer.

Type parameters

  • T

externalAnswered

Answered<T>: T extends null | undefined ? T : T extends Question<Promise<infer A>> | Question<infer A> | Promise<infer A> ? Awaited<A> : T

Describes the type of answer a given Answerable would resolve to when given to Actor.answer.

Answered<Answerable<T>> === T

Type parameters

  • T

externalQuestionAdapterFieldDecorator

QuestionAdapterFieldDecorator<Original_Type>: { [ Field in keyof Omit<Original_Type, keyof QuestionStatement<Original_Type>> ]: Original_Type[Field] extends (...args: infer OriginalParameters) => infer OriginalMethodResult ? Field extends replace | replaceAll ? (searchValue: Answerable<string | RegExp>, replaceValue: Answerable<string>) => QuestionAdapter<string> : (...args: { [ P in keyof OriginalParameters ]: Answerable<Awaited<OriginalParameters[P]>> }) => QuestionAdapter<Awaited<OriginalMethodResult>> : Original_Type[Field] extends number | bigint | boolean | string | symbol | object ? QuestionAdapter<Awaited<Original_Type[Field]>> : any }

Describes an object recursively wrapped in QuestionAdapter proxies, so that:

Type parameters

  • Original_Type

externalQuestionAdapter

QuestionAdapter<Answer_Type>: Question<Promise<Answer_Type>> & Interaction & { isPresent: any } & QuestionAdapterFieldDecorator<Answer_Type>

A union type representing a proxy object returned by Question.about.

QuestionAdapter proxies the methods and fields of the wrapped object recursively, allowing them to be used as either a Question or an Interaction.

Type parameters

  • Answer_Type

externalMetaQuestionAdapter

MetaQuestionAdapter<Context_Type, Answer_Type>: QuestionAdapter<Answer_Type> & MetaQuestion<Context_Type, QuestionAdapter<Answer_Type>>

An extension of QuestionAdapter, that in addition to proxying methods and fields of the wrapped object can also act as a MetaQuestion.

Type parameters

  • Context_Type
  • Answer_Type

externalRecursivelyAnswered

RecursivelyAnswered<T>: T extends null | undefined ? T : T extends Question<Promise<infer A>> | Question<infer A> | Promise<infer A> ? RecursivelyAnswered<Awaited<A>> : T extends object ? { [ K in keyof T ]: RecursivelyAnswered<T[K]> } : T

Describes a recursively resolved plain JavaScript object with answerable properties.

Typically, used in conjunction with Question.fromObject.

Using RecursivelyAnswered

import {
  actorCalled, notes, q, Question, QuestionAdapter, WithAnswerableProperties
} from '@serenity-js/core';

interface RequestConfiguration {
  headers: Record<string, string>;
}

const requestConfiguration: WithAnswerableProperties<RequestConfiguration> = {
  headers: {
    Authorization: q`Bearer ${ notes().get('authDetails').token }`
  }
}

const question: QuestionAdapter<RequestConfiguration> =
  Question.fromObject<RequestConfiguration>(requestConfiguration)

const answer = await actorCalled('Annie').answer(question);

const a1: RequestConfiguration = answer;
const a2: RecursivelyAnswered<WithAnswerableProperties<RequestConfiguration>> = answer;

// RequestConfiguration === RecursivelyAnswered<WithAnswerableProperties<RequestConfiguration>>

Type parameters

  • T

externalWithAnswerableProperties

WithAnswerableProperties<T>: T extends null | undefined ? T : T extends Question<Promise<infer A>> | Question<infer A> | Promise<infer A> ? Answerable<A> : T extends object ? { [ K in keyof T ]: WithAnswerableProperties<T[K]> } : Answerable<T>

Describes a plain JavaScript object with Answerable properties. Typically, used in conjunction with RecursivelyAnswered and Question.fromObject.

import {
  actorCalled, notes, q, Question, QuestionAdapter, WithAnswerableProperties
} from '@serenity-js/core';

interface RequestConfiguration {
  headers: Record<string, string>;
}

const requestConfiguration: WithAnswerableProperties<RequestConfiguration> = {
  headers: {
    Authorization: q`Bearer ${ notes().get('authDetails').token }`
  }
}

const question: QuestionAdapter<RequestConfiguration> =
    Question.fromObject<RequestConfiguration>(requestConfiguration)

const answer: RequestConfiguration = await actorCalled('Annie').answer(question);

Type parameters

  • T

Serenity

externalClassDescription

ClassDescription: string | [string] | [string, any]

ClassDescription describes the Node module ID and optionally:

  • a named export that you want to import
  • a parameter that should be passed to the static fromJSON method if the imported type provides it.

ClassDescription is used to describe the stage crew members passed to SerenityConfig.

The most basic class description is the name of a Node module that must provide a default export. For example, below definition would be interpreted as a request to import the default export from the @serenity-js/serenity-bdd module and instantiate it using its no-arg constructor:

import { configure } from '@serenity-js/core'

configure({
  crew: [
    `@serenity-js/serenity-bdd`
  ]
})

Class description can also include a named export to be imported. For example, below definition would be interpreted as a request to import the SerenityBDDReporter type from @serenity-js/serenity-bdd and instantiate it using its no-arg constructor:

import { configure } from '@serenity-js/core'

configure({
  crew: [
    `@serenity-js/serenity-bdd:SerenityBDDReporter`
  ]
})

However, not all types have no-arg constructors. In those cases, a type offering a static fromJSON(configParam) method can be described using a tuple where the first item describes the Node module and optionally the class name, and the second item describes the configParam.

import { configure } from '@serenity-js/core'

configure({
  crew: [
    [ `@serenity-js/core:ArtifactArchiver`, { outputDirectory: './target/site/serenity' } ]
  ]
})

Note that the class description could also describe a local Node module. This can be useful when you're writing a custom StageCrewMember implementation. For example, ./my-reporter:MyReporter would be interpreted as a request to load the MyReporter type from ./my-reporter file, located relative to the working directory of the current Node.js process.

externalconstserenity

serenity: Serenity = ...

Serenity object is the root object of the Serenity/JS framework.

Page Options