Executable Specifications

Serenity

constructs a Stage and connects it with a provided Cast

enables propagation of DomainEvents triggered by Actors' Activities and StageCrewMembers

allows for external parties, such as test runner adapters, to announce DomainEvents

RuntimeError

subclass

is recognised as an instance of its type

has a message

retains the stacktrace

when propagating errors

includes the stack trace of the original errors

Config

when wrapping a plain-old configuration object

enables access to its fields

tells if a given field exists, but is undefined

when transforming the values

transforms values using transformation functions provided for each field

conditionally

transforms a value when a condition is met

does not transform the value when a condition is not met

getAsList

returns an empty list when the value

is undefined

is null

returns a list when the value

is already a list

is not a list

respects the transformation function, if it is defined

when extracting the configuration object

returns the value equal to the underlying config object, when no transformations are used

applies any transformations

ErrorSerialiser

serialises an Error object to JSON

deserialises a serialised Error object from JSON

serialises a custom Error object to JSON

deserialises a serialised custom Error object from JSON

deserialises the error object from a stack trace alone (Cucumber event protocol)

deserialises the error object from a string (Cucumber event protocol)

FileFinder

returns a list with an exact match

returns a list with exact matches

supports glob patterns

supports globstar patterns

FileSystem

when storing JSON files

stores a JSON file in a desired location

tells the absolute path to a JSON file once it is saved

when storing pictures

stores a base64-encoded picture at a desired location

tells the absolute path to a JSON file once it is saved

when removing

individual files

removes the file

directories

removes the directory recursively

when generating temp file paths

uses a randomly generated file name and .tmp suffix

allows for the prefix to be overridden

allows for the suffix to be overridden

FileSystemLocation

ModuleLoader

returns the version number of a given package

returns the version of the npm-resolved package if the local package could not be found

complains if neither a local version or the npm-resolved version could be found

when checking if a given module is available to be required

returns true if the module is available

returns false if the module is not available

Path

when used across different operating systems

produces the same result no matter what path it's instantiated with

exposes the normalised path string

splits the same

can be serialised and deserialised

can join path components into a single path

can be instantiated from path segments

can split an absolute path

can split a relative path

can resolve two paths

knows the root directory

Version

represents a comparable version number

grants access to the major version number

provides a sensible description

commaSeparated

returns an empty string for an empty list

formatted tag function

produces a human-readable description when given a template with multiple parameters

cycle

when used with primitives

stringify

parse

when used with acyclic objects

stringify

parse

when used with cyclic objects

JSON.stringify

should fail because of a circular reference in a round robin list

should fail because of a circular reference in simple nested object

should fail because of a circular reference in complex nested object

should fail because of a cycles in object with parallel references

stringify

should serialise a round robin list data structure

should serialise a simple nested object

should serialise a complex nested object

should serialise an object with parallel references

parse

should deserialise a round robin list data structure

should deserialise a simple nested object

should deserialise a complex nested object

should deserialise an object with parallel references

trimmed tag function

trims the leading and trailing whitespace

leaves the space between the lines if required

trims padded multi-line string

Artifact

Photo

can be serialised

can be de-serialised

allows for its value to be extracted as a Buffer

can be instantiated from a Buffer

JSONData

can be serialised

can be de-serialised

allows for its value to be extracted as a JSON value

Duration

represents a duration of time that

when performing computations

allows for durations to be added

when comparing

ScenarioParameters

can be instantiated using a plain-old JavaScript object

can be serialised to JSON

can be deserialised from JSON

Tag

Timestamp

instantiation

can be instantiated with an arbitrary Date

defaults to current time if no argument is provided

serialisation

is serialised to an ISO-8601-compliant string

can be deserialised from an ISO-8601-compliant string

arithmetic

allows for calculating a difference between two timestamps

allows for computing another timestamp, relative to the original one

conversion

can be converted to a numeric unix timestamp

can be created from a numeric unix timestamp

Outcome

non-error outcome

outcome indicating an error

Interaction

when defining an interaction

provides a convenient factory method for synchronous interactions

provides a convenient factory method for asynchronous interactions

when handling errors

rejects the promise when the interaction function rejects a promise

rejects the promise when the interaction function throws an error

can optionally emit an artifact to be attached to the report or stored

Question

provides a convenient way to define a custom question that

returns a static value

returns a Promise of a value

has a description

allows for a custom description to override the default one

when mapping the answer

works with a static value

works with a promise

works with a static list of values

works with a promised list

works with a mappable collection (Array, ElementArrayFinder, etc.)

Task

provides a convenient factory method for defining tasks

provides a way to describe a collection of activities

generates a pending task if no activities are provided

TakeNotes

usingAnEmptyNotepad

enables the actor to take note of an answer to a given question and recall it later

enables the actor to take note of an answer to a given question under a custom name

usingASharedNotepad

enables the actor to take note of an answer to a given question and recall it later

Actor

can be identified by their name

provides a developer-friendly toString

has Abilities allowing them to perform Activities and interact with a given interface of the system under test

performs composite Tasks recursively to accomplish their Business Goals

asks Questions about the state of the system

fulfills the promise should the question be answered as expected

rejects the promise should the answer differ from what was expected

when using abilities

admits if it does not have the Ability necessary to accomplish a given Interaction

complains if given the same ability twice

that have to be initialised

initialises them upon the first call to attemptsTo

DomainEvent handling

announces the events that activities it performs

notifies when an activity begins and ends

Interactions

See

when used with async questions

allows the actor to verify a condition

rejects the promise if the condition is not met

when used with sync questions

allows the actor to verify a condition

rejects the promise if the condition is not met

Check

(if branch)

makes the actor execute the activities when the expectation is met

makes the actor ignore the activities when the expectation is not met

(if/else branches)

makes the actor execute the activities when the expectation is met

makes the actor execute the alternative activities when the expectation is not met

reporting

provides a description of the check

provides a description of the check while correctly cleaning the output from new line characters

Expectation

thatActualShould()

provides a way to easily create custom expectation that

to()

provides a way to alias and compose expectations

resolves to ExpectationMet when the expectation is met and the message alias

resolves with ExpectationNotMet when the expectation is not met and the original message for any unmet expectations

Note

enables the actor to recall the answer to a given question

enables the actor to recall the answer on a given subject

complains if no answer to a given question has ever been remembered

complains if no answer on a given subject has ever been remembered

Property

when wrapping an Answerable<object>

complains when the property

when generating MetaQuestions

complains when the property

helps to filter lists of objects

TransformAnswer

transforms answers to Array<Answerable<T>> to another type

transforms answers to questions of different types to another type

provides a sensible default description

allows for the default description to be changed

ArrayListAdapter

count()

items()

first()

last()

get(index)

List

when wrapping an Array

provides a sensible description when it

and using filters

lets you narrow down the list of items to those that match the filter

lets you narrow down the list of items to those that match the filter

lets you narrow down the list of items to those that match several filters

describes the filters applied

append

allows for a string to be appended to the original answer

allows for a Promise<string> to be appended to the original answer

allows for a Question<string> to be appended to the original answer

allows for a Question<Promise<string>> to be appended to the original answer

normalize

replace

slice

extracts the part of the string from startIndex to endIndex

split

can limit the number of substrings returned

toLocaleLowerCase

toLocaleUpperCase

toLowerCase

toUpperCase

trim

q

returns the original string value if no parameters are provided

provides a sensible description of the question being asked

can have the default description overridden

Loop

Stage

provides both the more verbose and more concise way of accessing the actors

when instantiating actors

instantiates a new actor when their name is called for the first time

returns an existing actor if it has already been instantiated before

when referencing a recently retrieved actor

retrieves the current actor, if there is any

provides both the more verbose and more concise way of accessing the actors in the spotlight

when instantiating and dismissing the actors

performing a single scene

dismisses actors instantiated after SceneStarts when SceneFinished

re-instantiates actors dismissed when the SceneFinished

performing across multiple scenes

dismisses actors instantiated before SceneStarts when TestRunFinishes

retains instances of actors instantiated before the SceneStarts

when correlating activities

assigns sceneIds

returns a default sceneId when activities are performed outside of a test runner

assigns activityIds

complains if an activityId is attempted to be retrieved before is has been assigned

when an error occurs

complains when instantiated with no Cast

complains when instantiated with no StageManager

complains if the Cast does not provide a way to instantiate a given actor

complains if the Cast does not provide a way to prepare a given actor and mentions the type of the Cast, when available

complains if the Cast throws an error during actor instantiation

complains if the Cast throws an error during actor instantiation and mentions the type of the Cast, when available

StageManager

broadcasts the domain event it receives to all the registered subscribers

keeps track of the work in progress

provides details should the work in progress fail to complete

provides details should the work in progress fail with an error

ArtifactArchiver

stores the artifacts generated by other stage crew members

notifies the StageManager when an artifact is saved so that the promise of a stage cue can be fulfilled

notifies the StageManager when an artifact cannot be saved so that the promise of a stage cue can be rejected

correctly saves the test report to a unique file

correctly saves PNG content to a file

ignores them

notifies the StageManager when the artifact is correctly archived

when instantiated using a factory method

joins the path segments provided so that the developer doesn't need to worry about cross-OS compatibility of the path

complains if the destination is not provided

StreamReporter

prints the events it receives to output stream