@serenity-js/core 3.0.0-rc.9 → 3.0.0

package/src/instance.ts

@@ -1,96 +1,160 @@
-import { Actor } from './screenplay/actor';
+import { SerenityConfig } from './config';
+import { Actor, Clock } from './screenplay';
 import { Serenity } from './Serenity';
-import { SerenityConfig } from './SerenityConfig';
-import { Cast, Clock } from './stage';
+import { Cast } from './stage';
 
 const clock = new Clock();
 
+/**
+ * Serenity object is the root object of the Serenity/JS framework.
+ *
+ * @group Serenity
+ */
 export const serenity = new Serenity(clock);
 
 /**
- * @desc
- *  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.
+ * Configures Serenity/JS. Every call to this function
+ * replaces the previous configuration provided,
+ * so this function should be called exactly once
+ * in your test suite.
  *
- *  This function is an alias for {@link Serenity#configure}.
+ * This function is an alias for {@apilink Serenity.configure}.
  *
- * @param {SerenityConfig} config
- * @return {void}
+ * :::tip configure vs engage
+  * If you want to retain the configuration but reset the {@apilink Cast|cast of actors}, use {@apilink engage} instead.
+ * :::
  *
- * @see {@link Serenity#configure}
+ * @param config
+ *
+ * @group Serenity
  */
 export function configure(config: SerenityConfig): void {
     serenity.configure(config);
 }
 
 /**
- * @desc
- *  Re-configures Serenity/JS with a new {@link Cast} of {@link Actor}s
- *  you'd like to use in any subsequent call to {@link actorCalled}.
+ * Re-configures Serenity/JS with a new {@apilink Cast} of {@apilink Actor|actors}
+ * you want to use in any subsequent calls to {@apilink actorCalled}.
+ *
+ * This function is an alias for {@apilink Serenity.engage},
+ * which provides an alternative to calling {@apilink Actor.whoCan} directly in your tests
+ * and is typically invoked in a "before all" or "before each" hook of your test runner of choice.
+ *
+ * :::tip configure vs engage
+ * Calling {@apilink engage} replaces the currently configured {@apilink Cast|cast of actors},
+ * but doesn't affect any other configuration.
+ * If you want to reset the Serenity/JS configuration completely, use {@apilink configure} instead.
+ * :::
+ *
+ * If your implementation of the {@apilink Cast} interface is stateless,
+ * you can invoke this function just once before your entire test suite is executed, see
+ * - [`beforeAll`](https://jasmine.github.io/api/3.6/global.html#beforeAll) in Jasmine,
+ * - [`before`](https://mochajs.org/#hooks) in Mocha,
+ * - [`BeforeAll`](https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/hooks.md#beforeall--afterall) in Cucumber.js
+ *
+ * However, if your {@apilink Cast} holds state that you want to reset before each scenario,
+ * it's better to invoke `engage` before each test using:
+ * - [`beforeEach`](https://jasmine.github.io/api/3.6/global.html#beforeEach) in Jasmine
+ * - [`beforeEach`](https://mochajs.org/#hooks) in Mocha,
+ * - [`Before`](https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/hooks.md#hooks) in Cucumber.js
+ *
+ * ## Engaging a cast of actors
+ *
+ * ```ts
+ * 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());
+ * ```
+ *
+ * ### Using with Mocha test runner
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ *
+ * beforeEach(() => engage(new Actors()))
+ * ```
+ *
+ * ### Using with Jasmine test runner
+ *
+ * ```typescript
+ * import 'jasmine'
+ *
+ * describe('My feature', () => {
+ *   beforeEach(() => engage(new Actors()))
+ *
+ *
+ * })
+ * ```
+ *
+ * ### Using with Cucumber.js test runner
+ *
+ * Engage `Actors` [before](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md)
+ * each test scenario:
  *
- *  This function is an alias for {@link Serenity#engage},
- *  which provides an alternative to calling {@link Actor#whoCan}
- *  directly in your tests and is typically invoked in a "before all"
- *  or "before each" hook of your test runner of choice.
+ * ```typescript
+ * import { Before } from '@cucumber/cucumber'
  *
- *  If your implementation of the {@link Cast} interface is stateless,
- *  you can invoke this function once before your entire test suite is executed, see
- *  - [`beforeAll`](https://jasmine.github.io/api/3.6/global.html#beforeAll) in Jasmine,
- *  - [`before`](https://mochajs.org/#hooks) in Mocha,
- *  - [`BeforeAll`](https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/hooks.md#beforeall--afterall) in Cucumber.js
+ * Before(() => engage(new Actors()))
+ * ```
  *
- *  However, if your {@link Cast} holds state that you want reset before each scenario,
- *  it's better to invoke `engage` before each test using:
- *  - [`beforeEach`](https://jasmine.github.io/api/3.6/global.html#beforeEach) in Jasmine
- *  - [`beforeEach`](https://mochajs.org/#hooks) in Mocha,
- *  - [`Before`](https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/hooks.md#hooks) in Cucumber.js
+ * Engage `Actors` before scenarios with [specific tags](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/hooks.md#tagged-hooks):
  *
- * @example <caption>Engaging a cast of actors</caption>
- *  import { Actor, Cast } from '@serenity-js/core';
+ * ```typescript
+ * import { Before } from '@cucumber/cucumber'
  *
- *  class Actors implements Cast {
- *      prepare(actor: Actor) {
- *          return actor.whoCan(
- *              // ... abilities you'd like the Actor to have
- *          );
- *      }
- *  }
+ * Before('@web', () => engage(new Actors()))
+ * ```
  *
- * engage(new Actors();
+ * ### Using with Playwright Test runner
  *
- * @example <caption>Usage with Jasmine</caption>
- *  import 'jasmine';
+ * [Serenity/JS Playwright Test module](/api/playwright-test) will configure the cast on your behalf,
+ * so you don't need to call {@apilink engage}.
  *
- *  beforeEach(() => engage(new Actors()));
+ * ```ts
+ * import { describe, it, test } from '@serenity-js/playwright-test'
  *
- * @example <caption>Usage with Cucumber</caption>
- *  import { Before } from 'cucumber';
+ * describe('My feature', () => {
  *
- *  Before(() => engage(new Actors());
+ *   this.use({
+ *     actors: new Actors()
+ *   })
  *
- * @param {Cast} actors
- * @returns {void}
+ *   // test scenarios
  *
- * @see {@link Actor}
- * @see {@link Cast}
+ * })
+ * ```
  *
- * @see {@link Serenity#engage}
+ * ## Learn more
+ * - {@apilink Actor}
+ * - {@apilink Cast}
+ * - {@apilink Serenity.engage}
+ *
+ * @param actors
+ *
+ * @group Serenity
  */
 export function engage(actors: Cast): void {
     serenity.engage(actors);
 }
 
 /**
- * @desc
- *  Instantiates or retrieves an actor {@link Actor}
- *  called `name` if one has already been instantiated.
+ * Instantiates or retrieves an {@apilink Actor}
+ * called `name` if one has already been instantiated.
  *
- *  This method is an alias for {@link Serenity#theActorCalled}.
+ * This method is an alias for {@apilink Serenity.theActorCalled}.
  *
- * @example <caption>Usage with Jasmine</caption>
- *   import 'jasmine';
+ * ## Usage with Mocha
+ *
+ * ```typescript
+ *   import { describe, it } from 'mocha';
  *   import { actorCalled } from '@serenity-js/core';
  *
  *   describe('Feature', () => {
@@ -98,61 +162,86 @@ export function engage(actors: Cast): void {
  *      it('should have some behaviour', () =>
  *          actorCalled('James').attemptsTo(
  *              // ... activities
- *          ));
- *   });
+ *          ))
+ *   })
+ * ```
+ *
+ * ## Usage with Jasmine
  *
- * @example <caption>Usage with Cucumber</caption>
+ * ```typescript
+ *   import 'jasmine';
  *   import { actorCalled } from '@serenity-js/core';
- *   import { Given } from 'cucumber';
  *
- *   Given(/(.*?) is a registered user/, (name: string) =>
- *      actorCalled(name).attemptsTo(
+ *   describe('Feature', () => {
+ *
+ *      it('should have some behaviour', () =>
+ *          actorCalled('James').attemptsTo(
  *              // ... activities
- *          ));
+ *          ))
+ *   })
+ * ```
  *
- * @param {string} name
- *  The name of the actor to instantiate or retrieve
+ * ## Usage with Cucumber
  *
- * @returns {Actor}
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Given } from '@cucumber/cucumber';
  *
- * @see {@link engage}
- * @see {@link Actor}
- * @see {@link Cast}
- * @see {@link Serenity#theActorCalled}
+ * Given(/(.*?) is a registered user/, (name: string) =>
+ *   actorCalled(name).attemptsTo(
+ *     // ... activities
+ *   ))
+ * ```
+ *
+ * ## Learn more
+ *
+ * - {@apilink engage}
+ * - {@apilink Actor}
+ * - {@apilink Cast}
+ * - {@apilink Serenity.theActorCalled}
+ *
+ * @param name
+ *  The name of the actor to instantiate or retrieve
+ *
+ * @group Actors
  */
 export function actorCalled(name: string): Actor {
     return serenity.theActorCalled(name);
 }
 
 /**
- * @desc
- *  Retrieves an actor who was last instantiated or retrieved
- *  using {@link actorCalled}.
+ * Retrieves an actor who was last instantiated or retrieved
+ * using {@apilink actorCalled}.
  *
- *  This function is particularly useful when automating Cucumber scenarios.
+ * This function is particularly useful when automating Cucumber scenarios.
  *
- *  This function is an alias for {@link Serenity#theActorInTheSpotlight}.
+ * This function is an alias for {@apilink Serenity.theActorInTheSpotlight}.
  *
- * @example <caption>Usage with Cucumber</caption>
- *   import { actorCalled } from '@serenity-js/core';
- *   import { Given, When } from 'cucumber';
+ * ## Usage with Cucumber
  *
- *   Given(/(.*?) is a registered user/, (name: string) =>
- *      actorCalled(name).attemptsTo(
- *              // ... activities
- *          ));
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Given, When } from '@cucumber/cucumber';
  *
- *   When(/(?:he|she|they) browse their recent orders/, () =>
- *      actorInTheSpotlight().attemptsTo(
- *              // ... activities
- *          ));
+ * Given(/(.*?) is a registered user/, (name: string) =>
+ *   actorCalled(name).attemptsTo(
+ *     // ... activities
+ *   ))
+ *
+ * When(/(?:he|she|they) browse their recent orders/, () =>
+ *   actorInTheSpotlight().attemptsTo(
+ *     // ... activities
+ *   ))
+ * ```
+ *
+ * ## Learn more
  *
- * @returns {Actor}
+ * - {@apilink engage}
+ * - {@apilink actorCalled}
+ * - {@apilink Actor}
+ * - {@apilink Cast}
  *
- * @see {@link engage}
- * @see {@link actorCalled}
- * @see {@link Actor}
- * @see {@link Cast}
+ * @group Actors
  */
 export function actorInTheSpotlight(): Actor {
     return serenity.theActorInTheSpotlight();

package/src/io/FileFinder.ts

@@ -1,4 +1,5 @@
-import fg = require('fast-glob');
+import fg from 'fast-glob';
+
 import { Path } from './Path';
 
 export class FileFinder {

package/src/io/FileSystem.ts

@@ -1,4 +1,4 @@
-import * as cuid from 'cuid';
+import cuid from 'cuid';
 import * as nodeFS from 'fs';
 import { WriteFileOptions } from 'fs';
 import * as gracefulFS from 'graceful-fs';

package/src/io/Path.ts

@@ -1,7 +1,6 @@
+import filenamify from 'filenamify';
 import { ensure, isDefined, isGreaterThan, property, TinyType } from 'tiny-types';
-
-import filenamify = require('filenamify');
-import path = require('upath');
+import path from 'upath';
 
 export class Path extends TinyType {
     private static readonly Separator = '/';
@@ -51,6 +50,10 @@ export class Path extends TinyType {
         return new Path(path.resolve(this.value, another.value));
     }
 
+    relative(another: Path): Path {
+        return new Path(path.relative(this.value, another.value));
+    }
+
     directory(): Path {
         return new Path(path.dirname(this.value));
     }

package/src/io/asyncMap.ts

@@ -1,9 +1,8 @@
 /**
- * @desc
- *  Maps an Array<Item_Type> to an Array<Result_Type>, one element at a time.
+ * Maps an Array<Item_Type> to an Array<Result_Type>, one element at a time.
  *
- * @param {Array<Item_Type>} items
- * @param {function(item: Item_Type): Promise<Result_Type>} mappingFunction
+ * @param items
+ * @param mappingFunction
  */
 export function asyncMap<Item_Type, Result_Type>(items: Item_Type[], mappingFunction: (item: Item_Type) => Promise<Result_Type> | Result_Type): Promise<Result_Type[]> {
     return items.reduce(
@@ -11,7 +10,9 @@ export function asyncMap<Item_Type, Result_Type>(items: Item_Type[], mappingFunc
             previous.then(async (acc) => {
                 const result = await mappingFunction(item);
 
-                return acc.concat(result);
+                acc.push(result)
+
+                return acc;
             })
         , Promise.resolve([])
     );

package/src/io/commaSeparated.ts

@@ -1,23 +1,22 @@
 /**
- * @desc
- *  Produces a comma-separated list based on the list provided.
+ * Produces a comma-separated list based on the list provided.
  *
- * @param {Array<string>} list
- * @param {function(item: string): string} map
- * @param {string} [acc=''] acc
+ * @param list
+ * @param mappingFunction
+ * @param [acc='']
  *
  * @returns {string}
  */
 export function commaSeparated(
     list: Array<string | { toString: () => string }>,
-    map = item => `${ item }`.trim(),
+    mappingFunction = item => `${ item }`.trim(),
     acc = '',
 ): string {
     switch (list.length) {
         case 0:     return acc;
-        case 1:     return commaSeparated(tail(list), map, `${ acc }${ map(head(list)) }`);
-        case 2:     return commaSeparated(tail(list), map, `${ acc }${ map(head(list)) } and `);
-        default:    return commaSeparated(tail(list), map, `${ acc }${ map(head(list)) }, `);
+        case 1:     return commaSeparated(tail(list), mappingFunction, `${ acc }${ mappingFunction(head(list)) }`);
+        case 2:     return commaSeparated(tail(list), mappingFunction, `${ acc }${ mappingFunction(head(list)) } and `);
+        default:    return commaSeparated(tail(list), mappingFunction, `${ acc }${ mappingFunction(head(list)) }, `);
     }
 }
 

package/src/io/format.ts

@@ -1,49 +1,76 @@
 import { Answerable } from '../screenplay';
-import { inspected } from './inspected';
+import { stringified } from './stringified';
 
 /**
- * @desc
- *  A factory function returning a tag function that produces a human-readable description of a template containing one or more {@link Answerable}s.
+ * {@apilink format} is a factory function returning
+ * a [tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals)
+ * that produces a human-readable description of a template containing
+ * one or more {@apilink Answerable|Answerables}.
  *
- * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals
+ * Typically, you'll want to use {@apilink d} and {@apilink f} shorthands instead:
+ * - the {@apilink d} function works best for generating a **description** of a parameterised {@apilink Activity}
+ * - the {@apilink f} function is better suited for debugging.
  *
- * @example
- *  import { format, Question } from '@serenity-js/core';
+ * ## Using `format`
  *
- *  const someQuestion = () =>
- *      Question.about('some question', actor => 'some value');
+ * ```ts
+ * import { format, Question } from '@serenity-js/core'
  *
- *  format({ markQuestions: true }) `actor answers ${ question() }`;
+ * const someQuestion = () =>
+ *   Question.about('some question', actor => 'some value')
+ *
+ * format({ markQuestions: true }) `actor answers ${ question() }`
  *  // returns: actor answers <<some question>>
  *
- *  format({ markQuestions: false }) `actor answers ${ question() }`;
+ * format({ markQuestions: false }) `actor answers ${ question() }`
+ *  // returns: actor answers some question
+ * ```
+ *
+ * ## Using `d`
+ *
+ * ```ts
+ * import { d, Question } from '@serenity-js/core'
+ *
+ * const someQuestion = () =>
+ *   Question.about('some question', actor => 'some value')
+ *
+ * d`actor answers ${ question() }`
  *  // returns: actor answers <<some question>>
+ * ```
  *
- * @example <caption>Aliasing</caption>
- *  import { format, Question } from '@serenity-js/core';
+ * ## Using `f`
  *
- *  const f = format({ markQuestions: true });
+ * ```ts
+ * import { f, Question } from '@serenity-js/core'
  *
- *  const someQuestion = () =>
- *      Question.about('some question', actor => 'some value');
+ * const someQuestion = () =>
+ *   Question.about('some question', actor => 'some value')
  *
- *  f `actor answers ${ question() }`;
- *  // produces: actor answers <<some question>>
+ * f`actor answers ${ question() }`
+ *  // returns: actor answers <<some question>>
+ *
+ * format({ markQuestions: false }) `actor answers ${ question() }`
+ *  // returns: actor answers <<some question>>
+ * ```
  *
- * @param {object} config
- *  - `markQuestions`: boolean - if set to true, descriptions of questions passed in as arguments will be surrounded with double angled brackets, i.e. `<<description>>`
- * @returns {function(templates: TemplateStringsArray, placeholders: ...Array<Answerable<any>>): string}
+ * @param config
+ *  `markQuestions`: boolean - if set to true, descriptions of questions passed in as arguments will be surrounded with double angled brackets, i.e. `<<description>>`
+ *
+ * @group Questions
  */
 export function format(config: { markQuestions: boolean }): (templates: TemplateStringsArray, ...placeholders: Array<Answerable<any>>) => string {
     return (templates: TemplateStringsArray, ...placeholders: Array<Answerable<any>>): string => {
         return templates
             .map((template, i) => i < placeholders.length
-                ? [ template, inspected(placeholders[i], { inline: true, markQuestions: config.markQuestions }) ]
+                ? [ template, stringified(placeholders[i], { inline: true, markQuestions: config.markQuestions }) ]
                 : [ template ])
-            .reduce((acc, tuple) => acc.concat(tuple))
+            .reduce((acc, tuple) => acc.concat(tuple), [])
             .join('');
     }
 }
 
+/** @group Questions */
 export const f = format({ markQuestions: true });
+
+/** @group Questions */
 export const d = format({ markQuestions: false });

package/src/io/index.ts

@@ -1,19 +1,13 @@
-export * from './AssertionReportDiffer';
 export * from './asyncMap';
 export * from './commaSeparated';
 export * from './Config';
-export * from './ErrorSerialiser';
-export * from './ErrorStackParser';
 export * from './FileFinder';
 export * from './FileSystem';
 export * from './FileSystemLocation';
 export * from './format';
-export * from './formatted';
-export * from './json';
-export * from './ModuleLoader';
-export * from './OutputStream';
+export * from './inspected';
+export * from './inspectedObject';
+export * from './loader';
 export * from './Path';
 export * from './reflection';
-export * from './TestRunnerAdapter';
 export * from './trimmed';
-export * from './Version';