Functions

Static Public Summary
public

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

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

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

public

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

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

public

configure(config: SerenityConfig): void

Configures Serenity/JS.

public

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

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

inspected(value: Answerable<any>): string

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

public

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

Checks if the value is a Mappable collection of items.

public

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

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

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

public

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

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

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

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

stringify(value: any, replacer: function(this: any, key: string, value: any): any, space: string | number): *

Converts a JavaScript value to a JavaScript Object Notation (JSON) string.

public

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

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

toLowerCase(): AnswerMappingFunction<string, string>

Converts all the alphabetic characters in a string to lowercase.

public

toNumber(): AnswerMappingFunction<string, string>

Converts a string to a number.

public

toUpperCase(): AnswerMappingFunction<string, string>

Converts all the alphabetic characters in a string to uppercase.

public

trim(): AnswerMappingFunction<string, string>

Removes whitespace from both ends of a string.

public

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

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

Static Public

public actorCalled(name: string): Actor source

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

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

This method is an alias for Serenity#theActorCalled.

Params:

NameTypeAttributeDescription
name string

The name of the actor to instantiate or retrieve

Returns:

Actor

Examples:

Usage with Jasmine
  import 'jasmine';
  import { actorCalled } from '@serenity-js/core';

  describe('Feature', () => {

     it('should have some behaviour', () =>
         actorCalled('James').attemptsTo(
             // ... activities
         ));
  });
Usage with Cucumber
  import { actorCalled } from '@serenity-js/core';
  import { Given } from 'cucumber';

  Given(/(.*?) is a registered user/, (name: string) =>
     actorCalled(name).attemptsTo(
             // ... activities
         ));

public actorInTheSpotlight(): Actor source

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

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

This function is particularly useful when automating Cucumber scenarios.

This function is an alias for Serenity#theActorInTheSpotlight.

Returns:

Actor

Examples:

Usage with Cucumber
  import { actorCalled } from '@serenity-js/core';
  import { Given, When } from 'cucumber';

  Given(/(.*?) is a registered user/, (name: string) =>
     actorCalled(name).attemptsTo(
             // ... activities
         ));

  When(/(?:he|she|they) browse their recent orders/, () =>
     actorInTheSpotlight().attemptsTo(
             // ... activities
         ));

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

import {append} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

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

Params:

NameTypeAttributeDescription
values ...Array<Answerable<string>>

The values to append to the end of the string.

Returns:

AnswerMappingFunction<string, string>

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

import {commaSeparated} from '@serenity-js/core/lib/io'

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

Params:

NameTypeAttributeDescription
list Array<string>
map function(item: string): string
acc string
  • optional
  • default: ''

acc

Returns:

string

public configure(config: SerenityConfig): void source

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

Configures Serenity/JS. Every call to this function replaces the previous configuration provided, so this function should called be exactly once in your test suite.

This function is an alias for Serenity#configure.

Params:

NameTypeAttributeDescription
config SerenityConfig

Returns:

void

public engage(actors: Cast): void source

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

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

Params:

NameTypeAttributeDescription
actors Cast

Returns:

void

Examples:

Engaging a cast of actors
 import { Actor, Cast } from '@serenity-js/core';

 class Actors implements Cast {
     prepare(actor: Actor) {
         return actor.whoCan(
             // ... abilities you'd like the Actor to have
         );
     }
 }

engage(new Actors();
Usage with Jasmine
 import 'jasmine';

 beforeEach(() => engage(new Actors()));
Usage with Cucumber
 import { Before } from 'cucumber';

 Before(() => engage(new Actors());

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

import {formatted} from '@serenity-js/core/lib/io'

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

Params:

NameTypeAttributeDescription
templates TemplateStringsArray
placeholders Array<Answerable<any>>

Returns:

string

public inspected(value: Answerable<any>): string source

import {inspected} from '@serenity-js/core/lib/io'

Provides a human-readable description of the {@link Answerable<T>}. Similar to util~inspect.

Params:

NameTypeAttributeDescription
value Answerable<any>

Returns:

string

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

import {isMappable} from '@serenity-js/core/lib/io/collections'

Checks if the value is a Mappable collection of items.

Params:

NameTypeAttributeDescription
maybeCollection Mappable<Item> | any

Returns:

boolean

Examples:

An Array
 import { Mappable } from '@serenity-js/core/lib/io';

 Mappable.isMappable([ 1, 2, 3 ]) === true
Protractor's ElementArrayFinder
 import { Mappable } from '@serenity-js/core/lib/io';
 import { element } from 'protractor';

 Mappable.isMappable(element.all(by.tagName('li')) === true

public normalize(form: Answerable<string>): AnswerMappingFunction<string, string> source

import {normalize} from '@serenity-js/core/lib/screenplay/questions/mappings/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.

Params:

NameTypeAttributeDescription
form Answerable<string>
  • optional

One of "NFC", "NFD", "NFKC", or "NFKD", specifying the Unicode Normalization Form. If omitted or undefined, "NFC" is used. These values have the following meanings: "NFC" - Canonical Decomposition, followed by Canonical Composition. "NFD" - Canonical Decomposition. "NFKC" - Compatibility Decomposition, followed by Canonical Composition. "NFKD" - Compatibility Decomposition.

Returns:

AnswerMappingFunction<string, string>

public parse(text: *, reviver: *): * source

import {parse} from '@serenity-js/core/lib/io/json'

Converts a JavaScript Object Notation (JSON) string into an object. Supports objects with cyclic references.

Params:

NameTypeAttributeDescription
text *

A valid JSON string.

reviver *

A function that transforms the results. This function is called for each member of the object. If a member contains nested objects, the nested objects are transformed before the parent object is.

Returns:

*

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

import {q} from '@serenity-js/core/lib/screenplay/questions'

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. a Question).

Params:

NameTypeAttributeDescription
templates TemplateStringsArray
parameters Array<Answerable<string|number>>

Returns:

Question<Promise<string>>

Examples:

Interpolating `Questions`
 import { q, actorCalled } from '@serenity-js/core';
 import { Send, DeleteRequest } from '@serenity-js/rest';

 actorCalled('Alice').attemptsTo(
     Send.a(DeleteRequest.to(
         q `/articles/${ Text.of(Article.id()) }`
     ))
 )
Using a custom description
 import { q, actorCalled } from '@serenity-js/core';
 import { Send, DeleteRequest } from '@serenity-js/rest';

 actorCalled('Alice').attemptsTo(
     Send.a(DeleteRequest.to(
         q `/articles/${ Text.of(Article.id()) }`.describedAs('/articles/:id')
     ))
 )

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

import {replace} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

Returns a new string with some or all matches of a pattern replaced by a replacement. The pattern can be a string or a RegExp, and the replacement can be a string or a function to be called for each match. If pattern is a string, only the first occurrence will be replaced.

Params:

NameTypeAttributeDescription
pattern Answerable<string|RegExp>
replacement Answerable<string|function>

Returns:

MappingFunction<string, string>

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

import {slice} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

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

Params:

NameTypeAttributeDescription
startIndex Answerable<number>

The zero-based index at which to begin extraction.

If negative, it is treated as str.length + startIndex. For example, if startIndex is -3, it is treated as str.length - 3

If startIndex is greater than or equal to str.length, an empty string is returned.

endIndex Answerable<number>
  • optional

The zero-based index before which to endIndex extraction. The character at this index will not be included.

If endIndex is omitted or undefined, or greater than str.length, slice() extracts to the endIndex of the string.

If negative, it is treated as str.length + endIndex. For example, if endIndex is -3, it is treated as str.length - 3.

Returns:

AnswerMappingFunction<string, string>

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

import {split} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

Divides a string into an ordered list of substrings, puts these substrings into an array, and returns the array. The division is done by searching for a pattern; where the pattern is provided as the first parameter in the method's call.

Params:

NameTypeAttributeDescription
separator Answerable<string|RegExp>

The pattern describing where each split should occur. The separator can be a simple string or it can be a regular expression.

limit Answerable<number>
  • optional

A non-negative integer specifying a limit on the number of substrings to be included in the array. If provided, splits the string at each occurrence of the specified separator, but stops when limit entries have been placed in the array. Any leftover text is not included in the array at all.

Returns:

AnswerMappingFunction<string, string>

public stringify(value: any, replacer: function(this: any, key: string, value: any): any, space: string | number): * source

import {stringify} from '@serenity-js/core/lib/io/json'

Converts a JavaScript value to a JavaScript Object Notation (JSON) string. Supports objects with cyclic references.

Params:

NameTypeAttributeDescription
value any

A JavaScript value, usually an object or array, to be converted.

replacer function(this: any, key: string, value: any): any
  • optional

A function that transforms the results.

space string | number
  • optional

Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.

Returns:

*

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

import {toLocaleLowerCase} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

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

Params:

NameTypeAttributeDescription
locales Answerable<string|string[]>
  • optional

The locale parameter indicates the locale to be used to convert to lower case according to any locale-specific case mappings. If multiple locales are given in an Array, the best available locale is used. The default locale is the host environment’s current locale.

Returns:

AnswerMappingFunction<string, string>

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

import {toLocaleUpperCase} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

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

Params:

NameTypeAttributeDescription
locales Answerable<string|string[]>
  • optional

The locale parameter indicates the locale to be used to convert to lower case according to any locale-specific case mappings. If multiple locales are given in an Array, the best available locale is used. The default locale is the host environment’s current locale.

Returns:

AnswerMappingFunction<string, string>

public toLowerCase(): AnswerMappingFunction<string, string> source

import {toLowerCase} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

Converts all the alphabetic characters in a string to lowercase.

Returns:

AnswerMappingFunction<string, string>

public toNumber(): AnswerMappingFunction<string, string> source

import {toNumber} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

Converts a string to a number.

Returns:

AnswerMappingFunction<string, string>

public toUpperCase(): AnswerMappingFunction<string, string> source

import {toUpperCase} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

Converts all the alphabetic characters in a string to uppercase.

Returns:

AnswerMappingFunction<string, string>

public trim(): AnswerMappingFunction<string, string> source

import {trim} from '@serenity-js/core/lib/screenplay/questions/mappings/string'

Removes whitespace from both ends of a string. Whitespace in this context is all the whitespace characters (space, tab, no-break space, etc.) and all the line terminator characters (LF, CR, etc.).

Returns:

AnswerMappingFunction<string, string>

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

import {trimmed} from '@serenity-js/core/lib/io'

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

Params:

NameTypeAttributeDescription
templates TemplateStringsArray
placeholders Array<string>

Returns:

string