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

package/src/stage/Stage.ts

@@ -1,91 +1,101 @@
 import { ensure, isDefined } from 'tiny-types';
 
-import { ConfigurationError, LogicError } from '../errors';
+import { ConfigurationError, ErrorFactory, ErrorOptions, LogicError, RaiseErrors, RuntimeError } from '../errors';
 import { AsyncOperationAttempted, AsyncOperationCompleted, AsyncOperationFailed, DomainEvent, SceneFinishes, SceneStarts, TestRunFinishes } from '../events';
-import { CorrelationId, Description, Timestamp } from '../model';
-import { Actor } from '../screenplay/actor';
+import { ActivityDetails, CorrelationId, Description, Name } from '../model';
+import { Actor, Clock, Duration, ScheduleWork, Timestamp } from '../screenplay';
 import { ListensToDomainEvents } from '../stage';
 import { Cast } from './Cast';
 import { StageManager } from './StageManager';
 
 /**
- * @desc
- *  The place where {@link Actor}s perform.
+ * Stage is the place where {@apilink Actor|actors} perform.
  *
- *  In more technical terms, the Stage is the main event bus propagating {@link DomainEvent}s
- *  to {@link Actor}s it instantiates and {@link StageCrewMember}s that have been registered with it.
+ * In more technical terms, the Stage is the main event bus propagating {@apilink DomainEvent|DomainEvents}
+ * to {@apilink Actor|Actors} it instantiates and {@apilink StageCrewMember|StageCrewMembers} that have been registered with it.
  *
- * @see {@link configure}
- * @see {@link engage}
+ * It is unlikely that you'll ever need to interact with the `Stage` directly in your tests. Instead, you'll use functions like
+ * {@apilink actorCalled} and {@apilink actorInTheSpotlight}.
+ *
+ * ## Learn more
+ * - {@apilink configure}
+ * - {@apilink engage}
+ *
+ * @group Stage
  */
 export class Stage {
 
+    private static readonly unknownSceneId = new CorrelationId('unknown')
+
     /**
-     * @desc
-     *  Actors instantiated after the scene has started,
-     *  who will be dismissed when the scene finishes.
-     *
-     * @private
+     * Actors instantiated after the scene has started,
+     * who will be dismissed when the scene finishes.
      */
     private actorsOnFrontStage: Map<string, Actor> = new Map<string, Actor>();
 
     /**
-     * @desc
-     *  Actors instantiated before the scene has started,
-     *  who will be dismissed when the test run finishes.
-     *
-     * @private
+     * Actors instantiated before the scene has started,
+     * who will be dismissed when the test run finishes.
      */
     private actorsOnBackstage: Map<string, Actor> = new Map<string, Actor>();
 
     private actorsOnStage: Map<string, Actor> = this.actorsOnBackstage;
 
     /**
-     * @desc
-     *  The most recent actor referenced via the {@link actor} method
-     *
-     * @private
+     * The most recent actor referenced via the {@apilink actor} method
      */
     private actorInTheSpotlight: Actor = undefined;
 
-    private currentActivity: CorrelationId = undefined;
-    private currentScene: CorrelationId = new CorrelationId('unknown');
+    private currentActivity: { id: CorrelationId, details: ActivityDetails } = undefined;
+
+    private currentScene: CorrelationId = Stage.unknownSceneId;
 
     /**
-     * @param {Cast} cast
-     * @param {StageManager} manager
+     * @param cast
+     * @param manager
+     * @param errors
+     * @param clock
+     * @param interactionTimeout
      */
     constructor(
         private cast: Cast,
         private readonly manager: StageManager,
+        private errors: ErrorFactory,
+        private readonly clock: Clock,
+        private readonly interactionTimeout: Duration,
     ) {
         ensure('Cast', cast, isDefined());
         ensure('StageManager', manager, isDefined());
+        ensure('ErrorFactory', errors, isDefined());
+        ensure('Clock', clock, isDefined());
+        ensure('interactionTimeout', interactionTimeout, isDefined());
     }
 
     /**
-     * @desc An alias for {@link Stage#actor}
-     * @see {@link Stage#actor}
-     * @alias {Stage#actor}
-     * @param {string} name
-     * @return {Actor}
+     * An alias for {@apilink Stage.actor}
+     *
+     * @param name
      */
     theActorCalled(name: string): Actor {
         return this.actor(name);
     }
 
     /**
-     * @desc Instantiates a new {@link Actor} or fetches an existing one
-     * by their name if they've already been instantiated.
+     * Instantiates a new {@apilink Actor} or fetches an existing one
+     * identified by their name if they've already been instantiated.
      *
-     * @param {string} name - case-sensitive name of the Actor
-     * @return {Actor}
+     * @param name
+     *  Case-sensitive name of the Actor, e.g. `Alice`
      */
     actor(name: string): Actor {
         if (! this.instantiatedActorCalled(name)) {
             let actor;
             try {
-                const newActor = new Actor(name, this);
+                const newActor = new Actor(name, this)
+                    .whoCan(
+                        new RaiseErrors(this),
+                        new ScheduleWork(this.clock, this.interactionTimeout),
+                    );
 
                 actor = this.cast.prepare(newActor);
 
@@ -109,12 +119,11 @@ export class Stage {
     }
 
     /**
-     * @desc
-     *  Returns the last {@link Actor} instantiated via {@link Stage#actor}.
-     *  Useful when you don't can't or choose not to reference the actor by their name.
+     * Returns the last {@apilink Actor} instantiated via {@apilink Stage.actor}.
+     * Useful when you don't can't or choose not to reference the actor by their name.
      *
-     * @throws {LogicError} if no {Actor} has been activated yet
-     * @return {Actor}
+     * @throws {LogicError}
+     *  If no {@apilink Actor} has been activated yet
      */
     theActorInTheSpotlight(): Actor {
         if (! this.actorInTheSpotlight) {
@@ -125,51 +134,47 @@ export class Stage {
     }
 
     /**
-     * @desc
-     *  Returns {true} if there is an {@link Actor} in the spotlight, {false} otherwise.
-     *
-     * @return {boolean}
+     * Returns `true` if there is an {@apilink Actor} in the spotlight, `false` otherwise.
      */
     theShowHasStarted(): boolean {
         return !! this.actorInTheSpotlight;
     }
 
     /**
-     * @desc
-     *  Configures the Stage to prepare {@link Actor}s
-     *  instantiated via {@link Stage#actor} using the provided {@link Cast}.
+     * Configures the Stage to prepare {@apilink Actor|Actors}
+     * instantiated via {@apilink Stage.actor} using the provided {@apilink Cast}.
      *
-     * @param {Cast} actors
-     * @returns {void}
+     * @param actors
      */
     engage(actors: Cast): void {
         ensure('Cast', actors, isDefined());
 
-        this.cast        = actors;
+        this.cast = actors;
     }
 
     /**
-     * @desc
-     *  Assigns listeners to be notified of {@link DomainEvent}s
-     *  emitted via {@link Stage#announce}
+     * Assigns listeners to be notified of {@apilink DomainEvent|DomainEvents}
+     * emitted via {@apilink Stage.announce}.s
      *
-     * @param {ListensToDomainEvents[]} listeners
-     * @returns {void}
+     * @param listeners
      */
     assign(...listeners: ListensToDomainEvents[]): void {
         this.manager.register(...listeners);
     }
 
     /**
-     * @desc
-     *  Notifies all the assigned listeners of the event.
-     *
-     * @listens {DomainEvent}
+     * Notifies all the assigned listeners of the events,
+     * emitting them one by one.
      *
-     * @param {DomainEvent} event
-     * @returns {void}
+     * @param events
      */
-    announce(event: DomainEvent): void {
+    announce(...events: Array<DomainEvent>): void {
+        events.forEach(event => {
+            this.announceSingle(event)
+        });
+    }
+
+    private announceSingle(event: DomainEvent): void {
         if (event instanceof SceneStarts) {
             this.actorsOnStage = this.actorsOnFrontStage;
         }
@@ -188,27 +193,23 @@ export class Stage {
     }
 
     /**
-     * @desc
-     *  Returns current time. This method should be used whenever
-     *  {@link DomainEvent} objects are instantiated by hand.
-     *
-     * @returns {Timestamp}
+     * Returns current time. This method should be used whenever
+     * {@apilink DomainEvent} objects are instantiated by you programmatically.
      */
     currentTime(): Timestamp {
         return this.manager.currentTime();
     }
 
     /**
-     * @desc
-     *  Generates and remembers a {@link CorrelationId}
-     *  for the current scene.
-     *
-     *  This method should be used in custom test runner adapters
-     *  when instantiating a {@link SceneStarts} event.
+     * Generates and remembers a {@apilink CorrelationId}
+     * for the current scene.
      *
-     * @see {@link Stage#currentSceneId}
+     * This method should be used in custom test runner adapters
+     * when instantiating a {@apilink SceneStarts} event.
      *
-     * @returns {CorrelationId}
+     * #### Learn more
+     * - {@apilink Stage.currentSceneId}
+     * - {@apilink CorrelationId}
      */
     assignNewSceneId(): CorrelationId {
         // todo: inject an id factory to make it easier to test
@@ -218,106 +219,115 @@ export class Stage {
     }
 
     /**
-     * @desc
-     *  Returns the {@link CorrelationId} for the current scene.
+     * Returns the {@apilink CorrelationId} for the current scene.
      *
-     * @see {@link Stage#assignNewSceneId}
-     *
-     * @returns {CorrelationId}
+     * #### Learn more
+     * - {@apilink Stage.assignNewSceneId}
      */
     currentSceneId(): CorrelationId {
         return this.currentScene;
     }
 
     /**
-     * @desc
-     *  Generates and remembers a {@link CorrelationId}
-     *  for the current {@link Activity}.
-     *
-     *  This method should be used in custom test runner adapters
-     *  when instantiating an {@link ActivityStarts} event.
+     * Generates and remembers a {@apilink CorrelationId}
+     * for the current {@apilink Activity}.
      *
-     * @see {@link Stage#currentActivityId}
+     * This method should be used in custom test runner adapters
+     * when instantiating the {@apilink ActivityStarts} event.
      *
-     * @returns {CorrelationId}
+     * #### Learn more
+     * - {@apilink Stage.currentActivityId}
      */
-    assignNewActivityId(): CorrelationId {
-        // todo: inject an id factory to make it easier to test
-        this.currentActivity = CorrelationId.create();
+    assignNewActivityId(activityDetails: ActivityDetails): CorrelationId {
+        this.currentActivity = {
+            id: CorrelationId.create(),
+            details: activityDetails,
+        };
 
-        return this.currentActivity;
+        return this.currentActivity.id;
     }
 
     /**
-     * @desc
-     *  Returns the {@link CorrelationId} for the current {@link Activity}.
-     *
-     * @see {@link Stage#assignNewSceneId}
+     * Returns the {@apilink CorrelationId} for the current {@apilink Activity}.
      *
-     * @returns {CorrelationId}
+     * #### Learn more
+     * - {@apilink Stage.assignNewSceneId}
      */
     currentActivityId(): CorrelationId {
         if (! this.currentActivity) {
             throw new LogicError(`No activity is being performed. Did you call assignNewActivityId before invoking currentActivityId?`);
         }
 
-        return this.currentActivity;
+        return this.currentActivity.id;
     }
 
     /**
-     * @desc
-     *  Returns a Promise that will be resolved when any asynchronous
-     *  post-processing activities performed by Serenity/JS are completed.
+     * Returns a Promise that will be resolved when any asynchronous
+     * post-processing activities performed by Serenity/JS are completed.
      *
-     * @returns {Promise<void>}
+     * Invoked in Serenity/JS test runner adapters to inform the test runner when
+     * the scenario has finished and when it's safe for the test runner to proceed
+     * with the next test, or finish execution.
      */
     waitForNextCue(): Promise<void> {
         return this.manager.waitForNextCue();
     }
 
+    createError<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE {
+        return this.errors.create(errorType, {
+            location: this.currentActivity?.details.location,
+            ...options,
+        });
+    }
+
     private instantiatedActorCalled(name: string): Actor | undefined {
         return this.actorsOnBackstage.has(name)
             ? this.actorsOnBackstage.get(name)
             : this.actorsOnFrontStage.get(name)
     }
 
-    private dismiss(activeActors: Map<string, Actor>): Promise<void> {
+    private async dismiss(activeActors: Map<string, Actor>): Promise<void> {
         const actors = Array.from(activeActors.values());
 
         if (actors.includes(this.actorInTheSpotlight)) {
             this.actorInTheSpotlight = undefined;
         }
 
-        return Promise
-            .all(actors.map(actor => {
-                const id = CorrelationId.create();
+        // Wait for the Photographer to finish taking any screenshots
+        await this.manager.waitForAsyncOperationsToComplete();
 
-                this.announce(new AsyncOperationAttempted(
-                    new Description(`[${ this.constructor.name }] Dismissing ${ actor.name }...`),
-                    id,
-                ));
+        const actorsToDismiss = new Map<Actor, CorrelationId>(actors.map(actor => [actor, CorrelationId.create()]));
 
-                return actor.dismiss()
-                    .then(() =>
-                        this.announce(new AsyncOperationCompleted(
-                            new Description(`[${ this.constructor.name }] Dismissed ${ actor.name } successfully`),
-                            id,
-                        )))
-                    .catch(error =>
-                        this.announce(new AsyncOperationFailed(error, id)),     // todo: serialise the error!
-                    );
+        for (const [ actor, correlationId ] of actorsToDismiss) {
+            this.announce(new AsyncOperationAttempted(
+                new Name(this.constructor.name),
+                new Description(`Dismissing ${ actor.name }...`),
+                correlationId,
+                this.currentTime(),
+            ));
+        }
+
+        // Try to dismiss each actor
+        for (const [ actor, correlationId ] of actorsToDismiss) {
+            try {
+                await actor.dismiss();
 
-            }))
-            .then(() => activeActors.clear());
+                this.announce(new AsyncOperationCompleted(
+                    correlationId,
+                    this.currentTime(),
+                ));
+            }
+            catch (error) {
+                this.announce(new AsyncOperationFailed(error, correlationId, this.currentTime()));     // todo: serialise the error!
+            }
+        }
+
+        activeActors.clear();
     }
 
-    /**
-     * @private
-     * @param {Cast} cast
-     */
     private typeOf(cast: Cast): string {
-        return this.cast.constructor !== Object
-            ? this.cast.constructor.name
-            : 'Cast';
+        return cast.constructor === Object
+            ? 'Cast'
+            : cast.constructor.name;
     }
 }

package/src/stage/StageCrewMember.ts

@@ -2,27 +2,78 @@ import { ListensToDomainEvents } from './ListensToDomainEvents';
 import { Stage } from './Stage';
 
 /**
- * @desc
- *  You can think of the {@link StageCrewMember} as an in-memory micro-service that reacts to {@link DomainEvent}s
- *  from the {@link StageManager}.
+ * You can think of the {@apilink StageCrewMember} as an in-memory microservice that reacts to {@apilink DomainEvent|domain events},
+ * published by the {@apilink StageManager}, and originally emitted by {@apilink Actor|actors} performing activities and Serenity/JS
+ * test runner adapters notifying the framework about test scenario-specific events like {@apilink SceneStarts} or {@apilink SceneFinishes}.
  *
- *  Every {@link StageCrewMember} receives a reference to the {@link Stage},
- *  and therefore {@link StageManager} as well, which enables them to emit {@link DomainEvent}s back.
+ * Every {@apilink StageCrewMember} receives a reference to the {@apilink Stage},
+ * and therefore {@apilink StageManager} as well, which enables them to emit {@apilink DomainEvent}s back.
  *
- *  Useful when you're interested in implementing [custom reporters](/handbook/reporting/index.html).
+ * This interface is useful when you're interested in implementing custom Serenity/JS reporters or supporting services.
  *
- * @extends {ListensToDomainEvents}
- * @see {@link StageCrewMemberBuilder}
- * @see {@link SerenityConfig#crew}
+ * ## Implementing a custom StageCrewMember
+ *
+ * ```ts
+ * import { Stage, StageCrewMember } from '@serenity-js/core'
+ * import * as events from '@serenity-js/core/lib/events'
+ * import { ArbitraryTag } from '@serenity-js/core/lib/model'
+ *
+ * export class TestRunnerTagger implements StageCrewMember {
+ *
+ *   static using(tagName: string) {
+ *     return new TestRunnerTagger(tagName);
+ *   }
+ *
+ *   protected constructor(
+ *     private readonly tagName: string,
+ *     private stage?: Stage,
+ *   ) {
+ *   }
+ *
+ *   assignedTo(stage: Stage): StageCrewMember {
+ *     this.stage = stage;
+ *     return this;
+ *   }
+ *
+ *   notifyOf(event: events.DomainEvent): void {
+ *     if (event instanceof events.TestRunnerDetected) {
+ *       this.stage.announce(
+ *         new events.SceneTagged(
+ *           this.stage.currentSceneId(),
+ *           new ArbitraryTag(this.tagName),
+ *           this.stage.currentTime()
+ *         )
+ *       )
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ## Using the custom StageCrewMember
+ *
+ * ```ts
+ * import { configure } from '@serenity-js/core'
+ *
+ * configure({
+ *   crew: [
+ *     TestRunnerTagger.using(`Node:${ process.version }`),
+ *   ]
+ * })
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink SerenityConfig.crew}
+ * - {@apilink configure}
+ * - {@apilink StageCrewMemberBuilder}
+ * - {@apilink ListensToDomainEvents}
+ * - {@apilink DomainEvent}
+ *
+ * @group Stage
  */
 export interface StageCrewMember extends ListensToDomainEvents {
 
     /**
-     * @desc
-     *  Assigns a {@link Stage} to this {@link StageCrewMember}
-     *
-     * @type {function(stage: Stage): StageCrewMember}
-     *  An instance of a {@link Stage} this {@link StageCrewMember} will be assigned to
+     * Assigns a {@apilink Stage} to this {@apilink StageCrewMember}
      */
-    assignedTo: (stage: Stage) => StageCrewMember;
+    assignedTo(stage: Stage): StageCrewMember;
 }

package/src/stage/StageCrewMemberBuilder.ts

@@ -2,22 +2,23 @@ import { ListensToDomainEvents } from './ListensToDomainEvents';
 import { StageCrewMemberBuilderDependencies } from './StageCrewMemberBuilderDependencies';
 
 /**
- * @desc
- *  Use a {@link StageCrewMemberBuilder} to configure complex {@link StageCrewMember} objects.
- *  Useful when you're interested in implementing custom reporters with multiple configuration options.
+ * Use a {@apilink StageCrewMemberBuilder} to configure complex {@apilink StageCrewMember} objects.
  *
- * @see {@link StageCrewMember}
- * @see {@link StageCrewMemberBuilderDependencies}
- * @see {@link SerenityConfig#crew}
+ * Useful when you're interested in implementing custom reporters with multiple configuration options.
+ * See {@apilink ConsoleReporter} for an example.
+ *
+ * ## Learn more
+ * - {@apilink StageCrewMember}
+ * - {@apilink StageCrewMemberBuilderDependencies}
+ * - {@apilink SerenityConfig.crew}
+ *
+ * @group Stage
  */
 export interface StageCrewMemberBuilder<T extends ListensToDomainEvents = ListensToDomainEvents> {
 
     /**
-     * @desc
-     *  Instantiates a {@link StageCrewMember}, giving it access to shared dependencies
-     *  such as {@link Stage} or {@link OutputStream}
-     *
-     * @type {function(dependencies: StageCrewMemberBuilderDependencies): T}
+     * Instantiates a {@apilink StageCrewMember}, giving it access to shared dependencies
+     * such as {@apilink Stage} or {@apilink OutputStream}
      */
-    build: (dependencies: StageCrewMemberBuilderDependencies) => T;
+    build(dependencies: StageCrewMemberBuilderDependencies): T;
 }

package/src/stage/StageCrewMemberBuilderDependencies.ts

@@ -1,25 +1,15 @@
-import { OutputStream } from '../io';
+import { OutputStream } from '../adapter';
 import { Stage } from './Stage';
 
 /**
- * @desc
- *  Dependencies injected by {@link Serenity} into {@link StageCrewMemberBuilder#build}
+ * Dependencies injected by {@apilink Serenity.configure} into {@apilink StageCrewMemberBuilder.build}
  *
- * @interface
+ * ## Learn more
+ * - {@apilink StageCrewMemberBuilder}
  *
- * @see {@link StageCrewMemberBuilder}
+ * @group Stage
  */
 export interface StageCrewMemberBuilderDependencies {
-
-    /**
-     * @type {Stage}
-     */
     stage: Stage;
-
-    /**
-     * @desc
-     *
-     * @type {OutputStream}
-     */
     outputStream: OutputStream;
 }