Functions

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

This method is an alias for Serenity#theActorCalled.

Examples:

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

  describe('Feature', () => {

     it('should have some behaviour', () =>
         actorCalled('James').attemptsTo(
             // ... activities
         ));
  });

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

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

See:

• engage
• Actor
• Cast
• Serenity#theActorCalled

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.

Examples:

  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
         ));

See:

• engage
• actorCalled
• Actor
• Cast

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

Tests:

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

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat

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

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.

See:

• Serenity#configure

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

• beforeAll in Jasmine,
• before in Mocha,

• BeforeAll in Cucumber.js

  However, if your Cast holds state that you want reset before each scenario, it's better to invoke engage before each test using:

• beforeEach in Jasmine
• beforeEach in Mocha,
• Before in Cucumber.js

Examples:

 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();

 import 'jasmine';

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

 import { Before } from 'cucumber';

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

See:

• Actor
• Cast
• Serenity#engage

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

Tests:

• `formatted` tag function
• `formatted` tag function produces a human-readable description when given a template with multiple parameters

Checks if the candidate value "quacks like a duck". In particular, it checks if the candidate:

• is not null
• is not undefined
• has expected methods or fields (evaluated via typeof)

Examples:

 const looksLikeADuck = has({
     name:   'string',
     quack:  'function',
 })

 const daisy = {
     name: 'Daisy',
     quack: () => 'quack',
 }

 looksLikeADuck(daisy) // true

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

Checks if the value is a Mappable collection of items.

Examples:

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

 Mappable.isMappable([ 1, 2, 3 ]) === true

 import { Mappable } from '@serenity-js/core/lib/io';
 import { element } from 'protractor';

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

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.

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize

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

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

Examples:

 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()) }`
     ))
 )

 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')
     ))
 )

Tests:

• q
• q returns the original string value if no parameters are provided
• q provides a sensible description of the question being asked
• q can have the default description overridden

See:

• Question

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.

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace

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

Tests:

• slice extracts the part of the string from `startIndex` to `endIndex`

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring

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.

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split

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

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleLowerCase

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

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleUpperCase

Converts all the alphabetic characters in a string to lowercase.

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase

Converts a string to a number.

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number

Converts all the alphabetic characters in a string to uppercase.

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase

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

See:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trim

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

Tests:

• `trimmed` tag function trims the leading and trailing whitespace
• `trimmed` tag function leaves the space between the lines if required
• `trimmed` tag function trims padded multi-line string