API Reference

summary
public
public
public

F actorCalled(name: string): Actor

Instantiates or retrieves an actor Actor called name if one has already been instantiated.

public

Retrieves an actor who was last instantiated or retrieved using actorCalled.

public

F configure(config: SerenityConfig): void

Configures Serenity/JS.

public

F engage(actors: Cast): void

Re-configures Serenity/JS with a new Cast of Actors you'd like to use in any subsequent call to actorCalled.

This function is an alias for Serenity#engage, which provides an alternative to calling Actor#whoCan directly in your tests and is typically invoked in a "before all" or "before each" hook of your test runner of choice.

If your implementation of the Cast interface is stateless, you can invoke this function once before your entire test suite is executed, see

public

errors

summary
public

Thrown to indicate that an assertion has failed.

public

Thrown to indicate that a test framework or test suite configuration error occurs.

public

Thrown to indicate that the Actor attempted to perform a Task or Interaction that hasn't been implemented yet.

public

Thrown to indicate that an Interaction, a Task or a test scenario can't be executed due to a logical error. For example, it's not possible to assert on the last HTTP Response if the request hasn't been performed yet.

public

Base class for custom errors that may occur during execution of a test scenario.

public

Thrown to indicate that the test can't be performed due to an issue with a downstream dependency. For example, it makes no sense to run a full-stack integration test if we already know that the database server is down.

public

Thrown to indicate that an unknown error has occurred.

events

summary
public
public
public
public
public
public
public
public
public
public

Emitted by @serenity-js/cucumber when a business rule is detected.

public
public
public
public
public

Indicates that the test runner will retry running the test scenario upon failure.

public
public
public
public
public
public
public
public
public
public
public
public

Emitted when all the tests have finished running.

public

Emitted when the last test in the test suite has finished running and it's time for any last-minute reporting to take place.

public

Emitted when the very first test is about to start

public
public
public

io

summary
public
public

C Config

this class is experimental.
public
public
public
public
public

Dynamically loads Node modules located relative to cwd.

public

C Path

public

A tiny type describing a version number, like 1.2.3

public
public

An output stream to be injected into StageCrewMemberBuilders configured via SerenityConfig#crew.

public

Describes an adapter needed to run a given type of tests programmatically

public

F commaSeparated(list: Array<string>, map: function(item: string): string, acc: string): string

Produces a comma-separated list based on the list provided.

public

F formatted(templates: TemplateStringsArray, placeholders: Array<Answerable<any>>): string

A tag function returning a human-readable description of a template containing one or more Answerables.

public

F inspected(value: Answerable<any>): string

Provides a human-readable description of the {@link Answerable<T>}.

public

F trimmed(templates: TemplateStringsArray, placeholders: Array<string>): string

A tag function trimming the leading and trailing whitespace from multi-line strings.

io/collections

summary
public

Describes a collection providing a map-like interface.

public

Describes a collection providing a reduce-like interface.

public

F isMappable(maybeCollection: Mappable<Item> | any): boolean

Checks if the value is a Mappable collection of items.

public

T Mapping<V,O>: function(item?: V, index?: number) | O

A mapping function converting one type into another.

io/json

summary
public

F parse(text: *, reviver: *): *

Converts a JavaScript Object Notation (JSON) string into an object.

public

F stringify(value: UNKNOWN, replacer: Function, space: undefined | undefined): string

io/reflection

summary
public

F has(api: object): boolean

Checks if the candidate value "quacks like a duck".

model

summary
public
public
public
public
public
public
public
public

C Name

public
public
public
public
public

Indicates a failure due to external events or systems that compromise the validity of the test.

public

Execution of an Activity or Scene has failed due to an assertion error;

public

Indicates a failure due to an error other than recognised external system and assertion failures

public

The result of the scenario should be ignored, most likely because it's going to be retried.

public

The Activity was not executed because a previous one has failed.

public

Scenario or activity ran as expected.

public

A pending Activity is one that has been specified but not yet implemented.

public
public
public

model/artifacts

summary
public
public

An Artifact describing a HTTP request/response pair.

public
public
public
public

C Photo

public
public

model/tags

summary
public

Tagged with an arbitrary tag that doesn't have any special interpretation such as @regression, @wip, etc.

public
public
public
this class was deprecated.

There are a couple of common use-cases for contexts: running the same test in different browsers, and running the same test on different operating systems.

public

Indicates that execution of a given scene has been retried for the currentRetry-th time.

public
public
public
public
public

C Tag

public

screenplay

summary
public

Directly exercises the Actor's Ability to interact with the System Under Test.

public abstract

Enables the Actor to query the system under test.

public

C Task

Aggregates Interactions so that they represents logical steps of a business process an Actor can perform.

public

An Ability enables the Actor to interact with an external interface of the system under test.

public

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

public

A command object representing an activity that an Actor can perform.

public

T 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.

screenplay/abilities

summary
public abstract

Enables the Actor to TakeNote of an answer to a given Question and to retrieve their Note later.

public

An interface to be implemented by any Ability that needs to free up the resources it uses.

public

An interface to be implemented by any Ability that needs to initialise the resources it uses (i.e.

screenplay/actor

summary
public

C Actor

public

Enables the Actor to answer a Question about the system under test

public

Enables the Actor to have an Ability or Abilities to perform some Activity.

public

Enables the Actor to collect Artifacts while the scenario is being executed

public

Enables the Actor to perform an Activity, such as a Task or an Interaction

public

Enables the Actor to use an Ability to perform some Activity.

screenplay/interactions

summary
public

C Log

Enables the Actor to log arbitrary static values and answers to Questions, so that they can be printed to the terminal by the ConsoleReporter and attached to the HTML report by the SerenityBDDReporter.

public

C See

this class was deprecated. Use the @serenity-js/assertions module instead
public

Enables the Actor to remember an answer to a given Question, and recall it later.

screenplay/questions

summary
public

C Check

A control flow statement that enables the @serenity-js/core/lib/screenplay/actor~Actor either to choose whether or not to perform a series of activities, or to choose which of the two provided series of activities to perform.

public

Defines an expectation to be used with assertions and Questions like List.

public

C List

Filters an Answerable list of items based on the criteria provided.

public

C Note

Enables the Actor to recall an answer to a given Question, recorded using TakeNote.

public

Enables easy access to properties of the value of a given Answerable.

public
this class is experimental.
public

A Question about another Answerable, used to retrieve a transformed version of the value it holds, or to compose Questions.

public

F q(templates: TemplateStringsArray, parameters: Array<Answerable<string|number>>): Question<Promise<string>>

A Screenplay-flavour of a tagged template literal, q is a tag function capable of resolving any Answerable<string | number> you parametrise it with (i.e.

public

T Predicate<A,E>: function(actual: A, expected: E)

screenplay/questions/expectations

summary
public
public
public

screenplay/questions/lists

summary
public

Adapts an Array so that it can be used with List

public

Adapts various types of collections so that they can be used with List.

screenplay/questions/mappings

summary
public

A mapping function converting one type into another.

screenplay/questions/mappings/string

summary
public

F append(values: ...Array<Answerable<string>>): AnswerMappingFunction<string, string>

Appends the values to the end of the original string and returns a new string.

public

F normalize(form: Answerable<string>): AnswerMappingFunction<string, string>

Returns the String value result of normalizing the string into the normalization form named by form as specified in Unicode Standard Annex #15, Unicode Normalization Forms.

public

F replace(pattern: Answerable<string|RegExp>, replacement: Answerable<string|function>): MappingFunction<string, string>

Returns a new string with some or all matches of a pattern replaced by a replacement.

public

F slice(startIndex: Answerable<number>, endIndex: Answerable<number>): AnswerMappingFunction<string, string>

Extracts the part of the string between the startIndex and endIndex indexes, or to the end of the string if endIndex is undefined.

public

F split(separator: Answerable<string|RegExp>, limit: Answerable<number>): AnswerMappingFunction<string, string>

Divides a string into an ordered list of substrings, puts these substrings into an array, and returns the array.

public

F toLocaleLowerCase(locales: Answerable<string|string[]>): AnswerMappingFunction<string, string>

Returns the calling string value converted to upper case, according to any locale-specific case mappings.

public

F toLocaleUpperCase(locales: Answerable<string|string[]>): AnswerMappingFunction<string, string>

Returns a string where all alphabetic characters have been converted to uppercase, taking into account the host environment's current locale.

public

F toLowerCase(): AnswerMappingFunction<string, string>

Converts all the alphabetic characters in a string to lowercase.

public

F toNumber(): AnswerMappingFunction<string, string>

Converts a string to a number.

public

F toUpperCase(): AnswerMappingFunction<string, string>

Converts all the alphabetic characters in a string to uppercase.

public

F trim(): AnswerMappingFunction<string, string>

Removes whitespace from both ends of a string.

screenplay/tasks

summary
public

C Loop

Enables the Actor to iterate over a list of items produced by any Answerable.

public

T LoopBuilder: Object

stage

summary
public

C Clock

A Clock tells the time.

public

C Stage

The place where Actors perform.

public
public

I Cast

Describes the Actors available to take part in the performance.

public
this class was deprecated. Please use the Cast instead

Prepares the Actor for the performance.

public

A StageCrewMember that can listen and react to DomainEvents

public

You can think of the StageCrewMember as an in-memory micro-service that reacts to DomainEvents from the StageManager.

public

Use a StageCrewMemberBuilder to configure complex StageCrewMember objects.

public

Dependencies injected by Serenity into StageCrewMemberBuilder#build

public
this class was deprecated. Please use serenity.actor() and serenity.actorInTheSpotlight() instead

Makes the Stage object setup in your test runner configuration visible to test steps or test scenarios.

stage/crew/artifact-archiver

summary
public

Stores any Artifacts emitted via ArtifactGenerated events on the FileSystem

stage/crew/stream-reporter

summary
public

Serialises all the DomainEvent objects it receives and streams them as ndjson to the output stream.