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

package/src/Serenity.ts

@@ -1,44 +1,62 @@
 import { ensure, isDefined, isInstanceOf, property } from 'tiny-types';
 
-import { ConfigurationError } from './errors';
+import { OutputStream } from './adapter';
+import { SerenityConfig } from './config';
+import { ConfigurationError, ErrorFactory, ErrorOptions, NoOpDiffFormatter, RuntimeError } from './errors';
 import { DomainEvent } from './events';
-import { formatted, has, OutputStream } from './io';
-import { CorrelationId, Duration, Timestamp } from './model';
-import { Actor } from './screenplay/actor/Actor';
-import { SerenityConfig } from './SerenityConfig';
+import { ClassDescriptionParser, ClassLoader, d, has, ModuleLoader, Path } from './io';
+import { ActivityDetails, CorrelationId } from './model';
+import { Actor, Clock, Duration, Timestamp } from './screenplay';
 import { StageCrewMember, StageCrewMemberBuilder } from './stage';
 import { Cast } from './stage/Cast';
-import { Clock } from './stage/Clock';
 import { Extras } from './stage/Extras';
 import { Stage } from './stage/Stage';
 import { StageManager } from './stage/StageManager';
 
+/**
+ * @group Serenity
+ */
 export class Serenity {
-    private static defaultCueTimeout    = Duration.ofSeconds(5);
-    private static defaultActors        = new Extras();
+    private static defaultCueTimeout            = Duration.ofSeconds(5);
+    private static defaultInteractionTimeout    = Duration.ofSeconds(5);
+    private static defaultActors                = new Extras();
 
     private stage: Stage;
     private outputStream: OutputStream  = process.stdout;
 
+    private readonly classLoader: ClassLoader;
+    private readonly workingDirectory: Path;
+
     /**
-     * @param {Clock} clock
+     * @param clock
      */
-    constructor(private readonly clock: Clock = new Clock()) {
+    constructor(
+        private readonly clock: Clock = new Clock(),
+        cwd: string = process.cwd(),
+    ) {
         this.stage = new Stage(
             Serenity.defaultActors,
             new StageManager(Serenity.defaultCueTimeout, clock),
+            new ErrorFactory(),
+            clock,
+            Serenity.defaultInteractionTimeout,
+        );
+
+        this.classLoader = new ClassLoader(
+            new ModuleLoader(cwd),
+            new ClassDescriptionParser(),
         );
+
+        this.workingDirectory = new Path(cwd);
     }
 
     /**
-     * @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.
-     *
-     * @param {SerenityConfig} config
-     * @return {void}
+     * 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.
+     *
+     * @param config
      */
     configure(config: SerenityConfig): void {
         const looksLikeBuilder          = has<StageCrewMemberBuilder>({ build: 'function' });
@@ -48,6 +66,10 @@ export class Serenity {
             ? ensure('cueTimeout', config.cueTimeout, isInstanceOf(Duration))
             : Serenity.defaultCueTimeout;
 
+        const interactionTimeout = config.interactionTimeout
+            ? ensure('interactionTimeout', config.interactionTimeout, isInstanceOf(Duration))
+            : Serenity.defaultInteractionTimeout;
+
         if (config.outputStream) {
             this.outputStream = config.outputStream;
         }
@@ -55,6 +77,9 @@ export class Serenity {
         this.stage = new Stage(
             Serenity.defaultActors,
             new StageManager(cueTimeout, this.clock),
+            new ErrorFactory(config.diffFormatter ?? new NoOpDiffFormatter()),
+            this.clock,
+            interactionTimeout,
         );
 
         if (config.actors) {
@@ -63,7 +88,12 @@ export class Serenity {
 
         if (Array.isArray(config.crew)) {
             this.stage.assign(
-                ...config.crew.map((stageCrewMember, i) => {
+                ...config.crew.map((stageCrewMemberDescription, i) => {
+
+                    const stageCrewMember = this.classLoader.looksLoadable(stageCrewMemberDescription)
+                        ? this.classLoader.instantiate<StageCrewMember | StageCrewMemberBuilder>(stageCrewMemberDescription)
+                        : stageCrewMemberDescription;
+
                     if (looksLikeBuilder(stageCrewMember)) {
                         return stageCrewMember.build({ stage: this.stage, outputStream: this.outputStream });
                     }
@@ -73,7 +103,7 @@ export class Serenity {
                     }
 
                     throw new ConfigurationError(
-                        formatted `Entries under \`crew\` should implement either StageCrewMember or StageCrewMemberBuilder interfaces, \`${ stageCrewMember }\` found at index ${ i }`
+                        d`Entries under \`crew\` should implement either StageCrewMember or StageCrewMemberBuilder interfaces, \`${ stageCrewMemberDescription }\` found at index ${ i }`
                     );
                 }),
             );
@@ -81,42 +111,71 @@ export class Serenity {
     }
 
     /**
-     * @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}.
+     *
+     * For your convenience, use {@apilink engage} function instead,
+     * 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.
+     *
+     * 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
      *
-     *  This method provides an alternative to calling {@link Actor#whoCan}
-     *  directly in your tests and you'd typically us it in a "before each"
-     *  hook of your test runner of choice.
+     * 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
      *
-     * @example <caption>Engaging a cast of actors</caption>
-     *  import { Actor, Cast } from '@serenity-js/core';
+     * ## Engaging a cast of actors
      *
-     *  class Actors implements Cast {
-     *      prepare(actor: Actor) {
-     *          return actor.whoCan(
-     *              // ... abilities you'd like the Actor to have
-     *          );
-     *      }
-     *  }
+     * ```ts
+     * import { Actor, Cast } from '@serenity-js/core';
      *
-     * engage(new Actors();
+     * class Actors implements Cast {
+     *   prepare(actor: Actor) {
+     *     return actor.whoCan(
+     *       // ... abilities you'd like the Actor to have
+     *     );
+     *   }
+     * }
      *
-     * @example <caption>Usage with Jasmine</caption>
-     *  import 'jasmine';
+     * engage(new Actors());
+     * ```
      *
-     *  beforeEach(() => engage(new Actors()));
+     * ### Using with Mocha test runner
      *
-     * @example <caption>Usage with Cucumber</caption>
-     *  import { Before } from 'cucumber';
+     * ```ts
+     * import { beforeEach } from 'mocha'
      *
-     *  Before(() => engage(new Actors());
+     * beforeEach(() => engage(new Actors()))
+     * ```
      *
-     * @param {Cast} actors
-     * @returns {void}
+     * ### Using with Jasmine test runner
      *
-     * @see {@link Actor}
-     * @see {@link Cast}
+     * ```ts
+     * import 'jasmine'
+     *
+     * beforeEach(() => engage(new Actors()))
+     * ```
+     *
+     * ### Using with Cucumber.js test runner
+     *
+     * ```ts
+     * import { Before } from '@cucumber/cucumber'
+     *
+     * Before(() => engage(new Actors()))
+     * ```
+     *
+     * ## Learn more
+     * - {@apilink Actor}
+     * - {@apilink Cast}
+     * - {@apilink engage}
+     *
+     * @param actors
      */
     engage(actors: Cast): void {
         this.stage.engage(
@@ -125,12 +184,15 @@ export class Serenity {
     }
 
     /**
-     * @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.
      *
-     * @example <caption>Usage with Jasmine</caption>
-     *   import 'jasmine';
+     * For your convenience, use {@apilink actorCalled} function instead.
+     *
+     * ## Usage with Mocha
+     *
+     * ```typescript
+     *   import { describe, it } from 'mocha';
      *   import { actorCalled } from '@serenity-js/core';
      *
      *   describe('Feature', () => {
@@ -138,65 +200,90 @@ export class Serenity {
      *      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
+     *
+     * ```typescript
+     * import { actorCalled } from '@serenity-js/core';
+     * import { Given } from '@cucumber/cucumber';
+     *
+     * Given(/(.*?) is a registered user/, (name: string) =>
+     *   actorCalled(name).attemptsTo(
+     *     // ... activities
+     *   ))
+     * ```
      *
-     * @returns {Actor}
+     * ## Learn more
      *
-     * @see {@link engage}
-     * @see {@link Actor}
-     * @see {@link Cast}
+     * - {@apilink engage}
+     * - {@apilink Actor}
+     * - {@apilink Cast}
+     * - {@apilink actorCalled}
+     *
+     * @param name
+     *  The name of the actor to instantiate or retrieve
      */
     theActorCalled(name: string): Actor {
         return this.stage.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 Serenity.theActorCalled}.
      *
-     *  This function is particularly useful when automating Cucumber scenarios.
+     * This function is particularly useful when automating Cucumber scenarios.
      *
-     * @example <caption>Usage with Cucumber</caption>
-     *   import { actorCalled } from '@serenity-js/core';
-     *   import { Given, When } from 'cucumber';
+     * For your convenience, use {@apilink actorInTheSpotlight} function instead.
      *
-     *   Given(/(.*?) is a registered user/, (name: string) =>
-     *      actorCalled(name).attemptsTo(
-     *              // ... activities
-     *          ));
+     * ## Usage with Cucumber
      *
-     *   When(/(?:he|she|they) browse their recent orders/, () =>
-     *      actorInTheSpotlight().attemptsTo(
-     *              // ... activities
-     *          ));
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core';
+     * import { Given, When } from '@cucumber/cucumber';
+     *
+     * Given(/(.*?) is a registered user/, (name: string) =>
+     *   actorCalled(name).attemptsTo(
+     *     // ... activities
+     *   ))
+     *
+     * When(/(?:he|she|they) browse their recent orders/, () =>
+     *   actorInTheSpotlight().attemptsTo(
+     *     // ... activities
+     *   ))
+     * ```
      *
-     * @returns {Actor}
+     * ## Learn more
      *
-     * @see {@link engage}
-     * @see {@link actorCalled}
-     * @see {@link Actor}
-     * @see {@link Cast}
+     * - {@apilink engage}
+     * - {@apilink actorCalled}
+     * - {@apilink actorInTheSpotlight}
+     * - {@apilink Actor}
+     * - {@apilink Cast}
      */
     theActorInTheSpotlight(): Actor {
         return this.stage.theActorInTheSpotlight();
     }
 
-    announce(event: DomainEvent): void {
-        this.stage.announce(event);
+    announce(...events: Array<DomainEvent>): void {
+        this.stage.announce(...events);
     }
 
     currentTime(): Timestamp {
@@ -211,8 +298,12 @@ export class Serenity {
         return this.stage.currentSceneId();
     }
 
-    assignNewActivityId(): CorrelationId {
-        return this.stage.assignNewActivityId();
+    assignNewActivityId(activityDetails: ActivityDetails): CorrelationId {
+        return this.stage.assignNewActivityId(activityDetails);
+    }
+
+    createError<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE {
+        return this.stage.createError(errorType, options);
     }
 
     /**
@@ -221,4 +312,8 @@ export class Serenity {
     waitForNextCue(): Promise<void> {
         return this.stage.waitForNextCue();
     }
+
+    cwd(): Path {
+        return this.workingDirectory;
+    }
 }

package/src/adapter/OutputStream.ts

@@ -0,0 +1,13 @@
+/**
+ * An output stream to be injected into {@apilink StageCrewMemberBuilder|StageCrewMemberBuilders} configured via {@apilink SerenityConfig.crew}.
+ *
+ * ## Learn more
+ * - {@apilink StageCrewMemberBuilder}
+ * - {@apilink Serenity.configure}
+ * - {@apilink SerenityConfig.crew}
+ *
+ * @group Integration
+ */
+export interface OutputStream {
+    write(content: string): void;
+}

package/src/adapter/TestRunnerAdapter.ts

@@ -0,0 +1,35 @@
+import { Outcome } from '../model';
+
+/**
+ * Describes an adapter needed to run a given type of tests programmatically
+ *
+ * @group Integration
+ */
+export interface TestRunnerAdapter {
+
+    /**
+     * Loads test scenarios.
+     */
+    load(pathsToScenarios: string[]): Promise<void>;
+
+    /**
+     * Returns the number of loaded scenarios
+     *
+     * @throws {@apilink LogicError}
+     *  If called before `load`
+     */
+    scenarioCount(): number;
+
+    /**
+     * Runs loaded test scenarios.
+     *
+     * @throws {@apilink LogicError}
+     *  If called before `load`
+     */
+    run(): Promise<void>;
+
+    /**
+     * Scenario success threshold for this test runner.
+     */
+    successThreshold(): Outcome | { Code: number };
+}

package/src/adapter/index.ts

@@ -0,0 +1,2 @@
+export * from './OutputStream';
+export * from './TestRunnerAdapter';

package/src/config/ClassDescription.ts

@@ -0,0 +1,55 @@
+/**
+ * `ClassDescription` describes the Node module ID and optionally:
+ * - a named export that you want to import
+ * - a parameter that should be passed to the static `fromJSON` method if the imported type provides it.
+ *
+ * `ClassDescription` is used to describe the {@apilink StageCrewMember|StageCrewMembers} passed to {@apilink SerenityConfig}.
+ *
+ * The most basic class description is the name of a Node module that must provide a `default` export.
+ * For example, below definition would be interpreted as a request to import the `default` export from the `@serenity-js/serenity-bdd` module and instantiate it using its no-arg constructor:
+ * ```typescript
+ * import { configure } from '@serenity-js/core'
+ *
+ * configure({
+ *   crew: [
+ *     `@serenity-js/serenity-bdd`
+ *   ]
+ * })
+ * ```
+ *
+ * Class description can also include a named export to be imported. For example, below definition would be interpreted as a request
+ * to import the `SerenityBDDReporter` type from `@serenity-js/serenity-bdd` and instantiate it using its no-arg constructor:
+ *
+ * ```typescript
+ * import { configure } from '@serenity-js/core'
+ *
+ * configure({
+ *   crew: [
+ *     `@serenity-js/serenity-bdd:SerenityBDDReporter`
+ *   ]
+ * })
+ * ```
+ *
+ * However, not all types have no-arg constructors. In those cases, a type offering a `static fromJSON(configParam)` method can be described using a tuple
+ * where the first item describes the Node module and optionally the class name, and the second item describes the `configParam`.
+ *
+ * ```typescript
+ * import { configure } from '@serenity-js/core'
+ *
+ * configure({
+ *   crew: [
+ *     [ `@serenity-js/core:ArtifactArchiver`, { outputDirectory: './target/site/serenity' } ]
+ *   ]
+ * })
+ * ```
+ *
+ * Note that the class description could also describe a local Node module. This can be useful when you're writing a custom StageCrewMember implementation.
+ * For example, `./my-reporter:MyReporter` would be interpreted as a request to load the `MyReporter` type from `./my-reporter` file, located
+ * relative to the [working directory](https://nodejs.org/api/process.html#processcwd) of the current Node.js process.
+ *
+ * @group Serenity
+ */
+export type ClassDescription =
+    string |            // e.g. '@serenity-js/core:StreamReporter'
+    [ string ] |        // e.g. [ '@serenity-js/core:StreamReporter' ]
+    [ string, any ];    // e.g. [ '@serenity-js/core:StreamReporter', { outputFile: './events.ndjson' } ]

package/src/config/SerenityConfig.ts

@@ -0,0 +1,79 @@
+import { OutputStream } from '../adapter';
+import { DiffFormatter } from '../errors';
+import { Duration } from '../screenplay';
+import { Cast, StageCrewMember, StageCrewMemberBuilder } from '../stage';
+import { ClassDescription } from './ClassDescription';
+
+/**
+ * Describes the configuration object accepted by the {@apilink configure} function.
+ *
+ * ## Learn more
+ * - {@apilink configure}
+ * - {@apilink Cast}
+ * - {@apilink StageCrewMember}
+ * - {@apilink StageCrewMemberBuilder}
+ * - {@apilink ClassDescription}
+ * - {@apilink Stage.waitForNextCue}
+ *
+ * @group Serenity
+ */
+export abstract class SerenityConfig {
+
+    /**
+     * A {@apilink Cast} of {@apilink Actor}s to be used when {@apilink actorCalled}
+     * and {@apilink actorInTheSpotlight} functions are called.
+     */
+    actors?: Cast;
+
+    /**
+     * A list of {@apilink StageCrewMemberBuilder|StageCrewMemberBuilders} or {@apilink StageCrewMember|StageCrewMembers}
+     * to be notified of {@apilink DomainEvent|DomainEvents} that occur during the scenario execution.
+     *
+     * Note that the `crew` can also be configured using {@apilink ClassDescription|ClassDescriptions}.
+     * This is useful when you need to load the configuration from a static `json` file, or when the test runner doesn't support
+     * providing class instances in configuration (e.g. Playwright Test).
+     */
+    crew?: Array<StageCrewMember | StageCrewMemberBuilder | ClassDescription>;
+
+    /**
+     * The maximum amount of time between {@apilink SceneFinishes} and {@apilink SceneFinished} events
+     * that Serenity/JS should wait for any post-scenario
+     * async operations to complete. Those include generating the screenshots,
+     * saving reports to disk, {@apilink Discardable|dismissing the actors}, and so on.
+     *
+     * Defaults to 5 seconds.
+     *
+     * **Please note** that this is not
+     * a scenario timeout, which should be configured in your test runner.
+     */
+    cueTimeout?: Duration;
+
+    /**
+     * The maximum default amount of time allowed for interactions such as {@apilink Wait.until}
+     * to complete.
+     *
+     * Defaults to 5 seconds, can be overridden per interaction.
+     *
+     * **Please note** that this is not
+     * a scenario timeout, which should be configured in your test runner.
+     *
+     * #### Learn more
+     * - {@apilink Wait.until}
+     */
+    interactionTimeout?: Duration;
+
+    /**
+     * {@apilink DiffFormatter} that should be used by the {@apilink ErrorFactory} and the ability to {@apilink RaiseErrors}
+     * when generating diffs included in {@apilink RuntimeError} objects.
+     *
+     * By default, Serenity/JS uses {@apilink NoOpDiffFormatter}.
+     */
+    diffFormatter?: DiffFormatter;
+
+    /**
+     * An output stream to be injected into {@apilink StageCrewMemberBuilder|StageCrewMemberBuilders}
+     *
+     * Defaults to [`process.stdout`](https://nodejs.org/api/process.html#process_process_stdout).
+     */
+    outputStream?: OutputStream;
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from './ClassDescription';
+export * from './SerenityConfig';