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

package/lib/stage/Stage.d.ts

@@ -1,178 +1,159 @@
+import { ErrorFactory, ErrorOptions, RuntimeError } from '../errors';
 import { DomainEvent } from '../events';
-import { CorrelationId, Timestamp } from '../model';
-import { Actor } from '../screenplay/actor';
+import { ActivityDetails, CorrelationId } from '../model';
+import { Actor, Clock, Duration, 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 declare class Stage {
     private cast;
     private readonly manager;
+    private errors;
+    private readonly clock;
+    private readonly interactionTimeout;
+    private static readonly unknownSceneId;
     /**
-     * @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;
     /**
-     * @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;
     private actorsOnStage;
     /**
-     * @desc
-     *  The most recent actor referenced via the {@link actor} method
-     *
-     * @private
+     * The most recent actor referenced via the {@apilink actor} method
      */
     private actorInTheSpotlight;
     private currentActivity;
     private currentScene;
     /**
-     * @param {Cast} cast
-     * @param {StageManager} manager
+     * @param cast
+     * @param manager
+     * @param errors
+     * @param clock
+     * @param interactionTimeout
      */
-    constructor(cast: Cast, manager: StageManager);
+    constructor(cast: Cast, manager: StageManager, errors: ErrorFactory, clock: Clock, interactionTimeout: Duration);
     /**
-     * @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;
     /**
-     * @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;
     /**
-     * @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;
     /**
-     * @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;
     /**
-     * @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;
     /**
-     * @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;
     /**
-     * @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;
+    private announceSingle;
     /**
-     * @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;
     /**
-     * @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;
     /**
-     * @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;
     /**
-     * @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;
+    assignNewActivityId(activityDetails: ActivityDetails): CorrelationId;
     /**
-     * @desc
-     *  Returns the {@link CorrelationId} for the current {@link Activity}.
+     * Returns the {@apilink CorrelationId} for the current {@apilink Activity}.
      *
-     * @see {@link Stage#assignNewSceneId}
-     *
-     * @returns {CorrelationId}
+     * #### Learn more
+     * - {@apilink Stage.assignNewSceneId}
      */
     currentActivityId(): CorrelationId;
     /**
-     * @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>;
+    createError<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE;
     private instantiatedActorCalled;
     private dismiss;
-    /**
-     * @private
-     * @param {Cast} cast
-     */
     private typeOf;
 }
+//# sourceMappingURL=Stage.d.ts.map

package/lib/stage/Stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stage.d.ts","sourceRoot":"","sources":["../../src/stage/Stage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,YAAY,EAAE,YAAY,EAA2B,YAAY,EAAE,MAAM,WAAW,CAAC;AAClH,OAAO,EAA0E,WAAW,EAA+C,MAAM,WAAW,CAAC;AAC7J,OAAO,EAAE,eAAe,EAAE,aAAa,EAAqB,MAAM,UAAU,CAAC;AAC7E,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAgB,SAAS,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,qBAAa,KAAK;IAmCV,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IArCvC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAA+B;IAErE;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAAgD;IAE1E;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAAgD;IAEzE,OAAO,CAAC,aAAa,CAA8C;IAEnE;;OAEG;IACH,OAAO,CAAC,mBAAmB,CAAoB;IAE/C,OAAO,CAAC,eAAe,CAA8D;IAErF,OAAO,CAAC,YAAY,CAAuC;IAE3D;;;;;;OAMG;gBAES,IAAI,EAAE,IAAI,EACD,OAAO,EAAE,YAAY,EAC9B,MAAM,EAAE,YAAY,EACX,KAAK,EAAE,KAAK,EACZ,kBAAkB,EAAE,QAAQ;IASjD;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAInC;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IA+B1B;;;;;;OAMG;IACH,sBAAsB,IAAI,KAAK;IAQ/B;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI;IAM1B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,SAAS,EAAE,qBAAqB,EAAE,GAAG,IAAI;IAInD;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI;IAM7C,OAAO,CAAC,cAAc;IAkBtB;;;OAGG;IACH,WAAW,IAAI,SAAS;IAIxB;;;;;;;;;;OAUG;IACH,gBAAgB,IAAI,aAAa;IAOjC;;;;;OAKG;IACH,cAAc,IAAI,aAAa;IAI/B;;;;;;;;;OASG;IACH,mBAAmB,CAAC,eAAe,EAAE,eAAe,GAAG,aAAa;IASpE;;;;;OAKG;IACH,iBAAiB,IAAI,aAAa;IAQlC;;;;;;;OAOG;IACH,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,WAAW,CAAC,EAAE,SAAS,YAAY,EAAE,SAAS,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,EAAE;IAOtG,OAAO,CAAC,uBAAuB;YAMjB,OAAO;IAuCrB,OAAO,CAAC,MAAM;CAKjB"}

package/lib/stage/Stage.js

@@ -5,76 +5,80 @@ const tiny_types_1 = require("tiny-types");
 const errors_1 = require("../errors");
 const events_1 = require("../events");
 const model_1 = require("../model");
-const actor_1 = require("../screenplay/actor");
+const screenplay_1 = require("../screenplay");
 /**
- * @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
  */
 class Stage {
     /**
-     * @param {Cast} cast
-     * @param {StageManager} manager
+     * @param cast
+     * @param manager
+     * @param errors
+     * @param clock
+     * @param interactionTimeout
      */
-    constructor(cast, manager) {
+    constructor(cast, manager, errors, clock, interactionTimeout) {
         this.cast = cast;
         this.manager = manager;
+        this.errors = errors;
+        this.clock = clock;
+        this.interactionTimeout = interactionTimeout;
         /**
-         * @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.
          */
         this.actorsOnFrontStage = new Map();
         /**
-         * @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.
          */
         this.actorsOnBackstage = new Map();
         this.actorsOnStage = this.actorsOnBackstage;
         /**
-         * @desc
-         *  The most recent actor referenced via the {@link actor} method
-         *
-         * @private
+         * The most recent actor referenced via the {@apilink actor} method
          */
         this.actorInTheSpotlight = undefined;
         this.currentActivity = undefined;
-        this.currentScene = new model_1.CorrelationId('unknown');
+        this.currentScene = Stage.unknownSceneId;
         (0, tiny_types_1.ensure)('Cast', cast, (0, tiny_types_1.isDefined)());
         (0, tiny_types_1.ensure)('StageManager', manager, (0, tiny_types_1.isDefined)());
+        (0, tiny_types_1.ensure)('ErrorFactory', errors, (0, tiny_types_1.isDefined)());
+        (0, tiny_types_1.ensure)('Clock', clock, (0, tiny_types_1.isDefined)());
+        (0, tiny_types_1.ensure)('interactionTimeout', interactionTimeout, (0, tiny_types_1.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) {
         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) {
         if (!this.instantiatedActorCalled(name)) {
             let actor;
             try {
-                const newActor = new actor_1.Actor(name, this);
+                const newActor = new screenplay_1.Actor(name, this)
+                    .whoCan(new errors_1.RaiseErrors(this), new screenplay_1.ScheduleWork(this.clock, this.interactionTimeout));
                 actor = this.cast.prepare(newActor);
                 // todo this.manager.notifyOf(ActorStarts)
                 // todo: map this in Serenity BDD Reporter so that the "cast" is recorded
@@ -82,7 +86,7 @@ class Stage {
             catch (error) {
                 throw new errors_1.ConfigurationError(`${this.typeOf(this.cast)} encountered a problem when preparing actor "${name}" for stage`, error);
             }
-            if (!(actor instanceof actor_1.Actor)) {
+            if (!(actor instanceof screenplay_1.Actor)) {
                 throw new errors_1.ConfigurationError(`Instead of a new instance of actor "${name}", ${this.typeOf(this.cast)} returned ${actor}`);
             }
             this.actorsOnStage.set(name, actor);
@@ -91,12 +95,11 @@ class Stage {
         return this.actorInTheSpotlight;
     }
     /**
-     * @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() {
         if (!this.actorInTheSpotlight) {
@@ -105,47 +108,42 @@ class Stage {
         return this.actorInTheSpotlight;
     }
     /**
-     * @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() {
         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) {
         (0, tiny_types_1.ensure)('Cast', actors, (0, tiny_types_1.isDefined)());
         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) {
         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) {
+    announce(...events) {
+        events.forEach(event => {
+            this.announceSingle(event);
+        });
+    }
+    announceSingle(event) {
         if (event instanceof events_1.SceneStarts) {
             this.actorsOnStage = this.actorsOnFrontStage;
         }
@@ -159,26 +157,22 @@ 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() {
         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() {
         // todo: inject an id factory to make it easier to test
@@ -186,86 +180,95 @@ class Stage {
         return this.currentScene;
     }
     /**
-     * @desc
-     *  Returns the {@link CorrelationId} for the current scene.
-     *
-     * @see {@link Stage#assignNewSceneId}
+     * Returns the {@apilink CorrelationId} for the current scene.
      *
-     * @returns {CorrelationId}
+     * #### Learn more
+     * - {@apilink Stage.assignNewSceneId}
      */
     currentSceneId() {
         return this.currentScene;
     }
     /**
-     * @desc
-     *  Generates and remembers a {@link CorrelationId}
-     *  for the current {@link Activity}.
+     * Generates and remembers a {@apilink CorrelationId}
+     * for the current {@apilink Activity}.
      *
-     *  This method should be used in custom test runner adapters
-     *  when instantiating an {@link ActivityStarts} event.
+     * This method should be used in custom test runner adapters
+     * when instantiating the {@apilink ActivityStarts} event.
      *
-     * @see {@link Stage#currentActivityId}
-     *
-     * @returns {CorrelationId}
+     * #### Learn more
+     * - {@apilink Stage.currentActivityId}
      */
-    assignNewActivityId() {
-        // todo: inject an id factory to make it easier to test
-        this.currentActivity = model_1.CorrelationId.create();
-        return this.currentActivity;
+    assignNewActivityId(activityDetails) {
+        this.currentActivity = {
+            id: model_1.CorrelationId.create(),
+            details: activityDetails,
+        };
+        return this.currentActivity.id;
     }
     /**
-     * @desc
-     *  Returns the {@link CorrelationId} for the current {@link Activity}.
+     * Returns the {@apilink CorrelationId} for the current {@apilink Activity}.
      *
-     * @see {@link Stage#assignNewSceneId}
-     *
-     * @returns {CorrelationId}
+     * #### Learn more
+     * - {@apilink Stage.assignNewSceneId}
      */
     currentActivityId() {
         if (!this.currentActivity) {
             throw new errors_1.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() {
         return this.manager.waitForNextCue();
     }
+    createError(errorType, options) {
+        var _a;
+        return this.errors.create(errorType, {
+            location: (_a = this.currentActivity) === null || _a === void 0 ? void 0 : _a.details.location,
+            ...options,
+        });
+    }
     instantiatedActorCalled(name) {
         return this.actorsOnBackstage.has(name)
             ? this.actorsOnBackstage.get(name)
             : this.actorsOnFrontStage.get(name);
     }
-    dismiss(activeActors) {
+    async dismiss(activeActors) {
         const actors = Array.from(activeActors.values());
         if (actors.includes(this.actorInTheSpotlight)) {
             this.actorInTheSpotlight = undefined;
         }
-        return Promise
-            .all(actors.map(actor => {
-            const id = model_1.CorrelationId.create();
-            this.announce(new events_1.AsyncOperationAttempted(new model_1.Description(`[${this.constructor.name}] Dismissing ${actor.name}...`), id));
-            return actor.dismiss()
-                .then(() => this.announce(new events_1.AsyncOperationCompleted(new model_1.Description(`[${this.constructor.name}] Dismissed ${actor.name} successfully`), id)))
-                .catch(error => this.announce(new events_1.AsyncOperationFailed(error, id)));
-        }))
-            .then(() => activeActors.clear());
+        // Wait for the Photographer to finish taking any screenshots
+        await this.manager.waitForAsyncOperationsToComplete();
+        const actorsToDismiss = new Map(actors.map(actor => [actor, model_1.CorrelationId.create()]));
+        for (const [actor, correlationId] of actorsToDismiss) {
+            this.announce(new events_1.AsyncOperationAttempted(new model_1.Name(this.constructor.name), new model_1.Description(`Dismissing ${actor.name}...`), correlationId, this.currentTime()));
+        }
+        // Try to dismiss each actor
+        for (const [actor, correlationId] of actorsToDismiss) {
+            try {
+                await actor.dismiss();
+                this.announce(new events_1.AsyncOperationCompleted(correlationId, this.currentTime()));
+            }
+            catch (error) {
+                this.announce(new events_1.AsyncOperationFailed(error, correlationId, this.currentTime())); // todo: serialise the error!
+            }
+        }
+        activeActors.clear();
     }
-    /**
-     * @private
-     * @param {Cast} cast
-     */
     typeOf(cast) {
-        return this.cast.constructor !== Object
-            ? this.cast.constructor.name
-            : 'Cast';
+        return cast.constructor === Object
+            ? 'Cast'
+            : cast.constructor.name;
     }
 }
 exports.Stage = Stage;
+Stage.unknownSceneId = new model_1.CorrelationId('unknown');
 //# sourceMappingURL=Stage.js.map