@serenity-js/core 3.25.4 → 3.26.0

package/src/events/actor/ActorStageExitCompleted.ts

@@ -0,0 +1,34 @@
+import { ensure, isDefined, type JSONObject } from 'tiny-types';
+
+import { CorrelationId, Name } from '../../model';
+import { Timestamp } from '../../screenplay';
+import { AsyncOperationCompleted } from '../AsyncOperationCompleted';
+
+/**
+ * Emitted when an [`Actor`](https://serenity-js.org/api/core/class/Actor/) and its abilities
+ * are correctly [released](https://serenity-js.org/api/core/interface/Discardable/) either
+ * upon the [`SceneFinishes`](https://serenity-js.org/api/core-events/class/SceneFinishes/) event
+ * for actors initialised within the scope of a test scenario,
+ * or upon the [`TestRunFinishes`](https://serenity-js.org/api/core-events/class/TestRunFinishes/) event
+ * for actors initialised within the scope of a test suite.
+ *
+ * @group Events
+ */
+export class ActorStageExitCompleted extends AsyncOperationCompleted {
+    static fromJSON(o: JSONObject): ActorStageExitCompleted {
+        return new ActorStageExitCompleted(
+            CorrelationId.fromJSON(o.correlationId as string),
+            Name.fromJSON(o.actor as string),
+            Timestamp.fromJSON(o.timestamp as string),
+        );
+    }
+
+    constructor(
+        correlationId: CorrelationId,
+        public readonly actor: Name,
+        timestamp?: Timestamp,
+    ) {
+        super(correlationId, timestamp);
+        ensure('actor', actor, isDefined());
+    }
+}

package/src/events/actor/ActorStageExitFailed.ts

@@ -0,0 +1,27 @@
+import type { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../../errors';
+import { CorrelationId } from '../../model';
+import { Timestamp } from '../../screenplay';
+import { AsyncOperationFailed } from '../AsyncOperationFailed';
+
+/**
+ * Emitted when [releasing](https://serenity-js.org/api/core/interface/Discardable/) an
+ * [`Actor`](https://serenity-js.org/api/core/class/Actor/) or its abilities
+ * resulted in an error either
+ * upon the [`SceneFinishes`](https://serenity-js.org/api/core-events/class/SceneFinishes/) event
+ * for actors initialised within the scope of a test scenario,
+ * or upon the [`TestRunFinishes`](https://serenity-js.org/api/core-events/class/TestRunFinishes/) event
+ * for actors initialised within the scope of a test suite.
+ *
+ * @group Events
+ */
+export class ActorStageExitFailed extends AsyncOperationFailed {
+    static fromJSON(o: JSONObject): ActorStageExitFailed {
+        return new ActorStageExitFailed(
+            ErrorSerialiser.deserialise(o.error as string),
+            CorrelationId.fromJSON(o.correlationId as string),
+            Timestamp.fromJSON(o.timestamp as string),
+        );
+    }
+}

package/src/events/actor/ActorStageExitStarts.ts

@@ -0,0 +1,35 @@
+import type { JSONObject } from 'tiny-types';
+import { ensure, isDefined } from 'tiny-types';
+
+import { CorrelationId } from '../../model';
+import { type SerialisedActor, Timestamp } from '../../screenplay';
+import { DomainEvent } from '../DomainEvent';
+
+/**
+ * Emitted upon the [`SceneFinishes`](https://serenity-js.org/api/core-events/class/SceneFinishes/) and
+ * [`TestRunFinishes`](https://serenity-js.org/api/core-events/class/TestRunFinishes/) events
+ * to notify the [stage crew members](https://serenity-js.org/api/core/interface/StageCrewMember/)
+ * about the final state of the [actors](https://serenity-js.org/api/core/class/Actor/) and their abilities
+ * before they're [released](https://serenity-js.org/api/core/interface/Discardable/).
+ *
+ * @group Events
+ */
+export class ActorStageExitStarts extends DomainEvent {
+    static fromJSON(o: JSONObject): ActorStageExitStarts {
+        return new ActorStageExitStarts(
+            CorrelationId.fromJSON(o.sceneId as string),
+            o.actor as unknown as SerialisedActor,
+            Timestamp.fromJSON(o.timestamp as string),
+        );
+    }
+
+    constructor(
+        public readonly sceneId: CorrelationId,
+        public readonly actor: SerialisedActor,
+        timestamp?: Timestamp,
+    ) {
+        super(timestamp);
+        ensure('sceneId', sceneId, isDefined());
+        ensure('actor', actor, isDefined());
+    }
+}

package/src/events/actor/index.ts

@@ -0,0 +1,5 @@
+export * from './ActorEntersStage';
+export * from './ActorStageExitAttempted';
+export * from './ActorStageExitCompleted';
+export * from './ActorStageExitFailed';
+export * from './ActorStageExitStarts';

package/src/events/index.ts

@@ -2,6 +2,7 @@ export * from './ActivityFinished';
 export * from './ActivityRelatedArtifactArchived';
 export * from './ActivityRelatedArtifactGenerated';
 export * from './ActivityStarts';
+export * from './actor';
 export * from './ArtifactArchived';
 export * from './ArtifactGenerated';
 export * from './AsyncOperationAborted';

package/src/screenplay/Actor.ts

@@ -1,26 +1,17 @@
 import { ConfigurationError, TestCompromisedError } from '../errors';
 import { ActivityRelatedArtifactGenerated } from '../events';
 import { ValueInspector } from '../io';
-import type { Artifact} from '../model';
+import type { Artifact } from '../model';
 import { Name, } from '../model';
 import type { Stage } from '../stage';
-import type {
-    AbilityType,
-    CanHaveAbilities,
-    Discardable,
-    Initialisable,
-    UsesAbilities
-} from './abilities';
-import {
-    Ability,
-    AnswerQuestions,
-    PerformActivities
-} from './abilities';
+import type { AbilityType, CanHaveAbilities, Discardable, Initialisable, UsesAbilities } from './abilities';
+import { Ability, AnswerQuestions, PerformActivities } from './abilities';
 import type { PerformsActivities } from './activities';
 import type { Activity } from './Activity';
 import type { Answerable } from './Answerable';
 import type { CollectsArtifacts } from './artifacts';
 import type { AnswersQuestions } from './questions';
+import type { SerialisedActor } from './SerialisedActor';
 import type { TellsTime, Timestamp } from './time';
 
 /**
@@ -217,6 +208,19 @@ export class Actor implements PerformsActivities,
         return `Actor(name=${ this.name }, abilities=[${ abilities.join(', ') }])`;
     }
 
+    /**
+     * Returns a JSON representation of the actor and its current state.
+     *
+     * The purpose of this method is to enable reporting the state of the actor in a human-readable format,
+     * rather than to serialise and deserialise the actor itself.
+     */
+    toJSON(): SerialisedActor {
+        return {
+            name: this.name,
+            abilities: Array.from(this.abilities.values()).map(ability => ability.toJSON())
+        }
+    }
+
     private initialiseAbilities(): Promise<void> {
         return this.findAbilitiesOfType<Initialisable>('initialise', 'isInitialised')
             .filter(ability => !ability.isInitialised())
@@ -243,9 +247,7 @@ export class Actor implements PerformsActivities,
     }
 
     private findAbilityTo<T extends Ability>(doSomething: AbilityType<T>): T | undefined {
-        const abilityType = this.mostGenericTypeOf(doSomething);
-
-        return this.abilities.get(abilityType) as T;
+        return this.abilities.get(doSomething.abilityType()) as T;
     }
 
     private acquireAbility(ability: Ability): void {
@@ -253,18 +255,7 @@ export class Actor implements PerformsActivities,
             throw new ConfigurationError(`Custom abilities must extend Ability from '@serenity-js/core'. Received ${ ValueInspector.typeOf(ability) }`);
         }
 
-        const abilityType = this.mostGenericTypeOf(ability.constructor as AbilityType<Ability>);
-
-        this.abilities.set(abilityType, ability);
-    }
-
-    private mostGenericTypeOf<Generic_Ability extends Ability, Specific_Ability extends Generic_Ability>(
-        abilityType: AbilityType<Specific_Ability>
-    ): AbilityType<Generic_Ability> {
-        const parentType = Object.getPrototypeOf(abilityType);
-        return !parentType || parentType === Ability
-            ? abilityType
-            : this.mostGenericTypeOf(parentType)
+        this.abilities.set(ability.abilityType(), ability);
     }
 
     /**

package/src/screenplay/SerialisedActor.ts

@@ -0,0 +1,9 @@
+import type { SerialisedAbility } from './abilities';
+
+/**
+ * @group Actors
+ */
+export interface SerialisedActor {
+    name: string;
+    abilities: Array<SerialisedAbility>;
+}

package/src/screenplay/abilities/Ability.ts

@@ -1,4 +1,5 @@
 import type { AbilityType } from './AbilityType';
+import type { SerialisedAbility } from './SerialisedAbility';
 import type { UsesAbilities } from './UsesAbilities';
 
 /**
@@ -404,4 +405,76 @@ export abstract class Ability {
     ): A {
         return actor.abilityTo(this) as A;
     }
+
+    /**
+     * Returns a JSON representation of the ability and its current state, if available.
+     * The purpose of this method is to enable reporting the state of the ability in a human-readable format,
+     * rather than to serialise and deserialise the ability itself.
+     */
+    toJSON(): SerialisedAbility {
+        const abilityClass = this.constructor.name;
+        const abilityType = this.abilityType().name;
+
+        if (abilityClass !== abilityType) {
+            return {
+                class: abilityClass,
+                type: abilityType,
+            };
+        }
+        return {
+            type: abilityType,
+        }
+    }
+
+    /**
+     * Returns the most abstract type of this Ability class,
+     * specifically the first class in the inheritance hierarchy that directly extends the `Ability` class.
+     *
+     * ```ts
+     * import { Ability } from '@serenity-js/core';
+     *
+     * class MyAbility extends Ability {}
+     * class MySpecialisedAbility extends MyAbility {}
+     *
+     * MyAbility.abilityType();            // returns MyAbility
+     * MySpecialisedAbility.abilityType(); // returns MyAbility
+     * ```
+     */
+    static abilityType(): AbilityType<Ability> {
+        return Ability.abilityTypeOf(this);
+    }
+
+    /**
+     * Returns the most abstract type of this Ability instance,
+     * specifically the first class in the inheritance hierarchy that directly extends the `Ability` class.
+     *
+     * ```ts
+     * import { Ability } from '@serenity-js/core';
+     *
+     * class MyAbility extends Ability {}
+     * class MySpecialisedAbility extends MyAbility {}
+     *
+     * new MyAbility().abilityType();            // returns MyAbility
+     * new MySpecialisedAbility().abilityType(); // returns MyAbility
+     * ```
+     */
+    abilityType(): AbilityType<Ability> {
+        return Ability.abilityTypeOf(this.constructor as AbilityType<Ability>);
+    }
+
+    private static abilityTypeOf(abilityType: AbilityType<Ability>): AbilityType<Ability> {
+        const abilityTypes = Ability.ancestorTypes(abilityType);
+        return [
+            ...abilityTypes,
+            abilityType
+        ][0];
+    }
+
+    private static ancestorTypes(abilityType: AbilityType<Ability>, ancestors: Array<AbilityType<Ability>> = []): Array<AbilityType<Ability>> {
+        const parentType = Object.getPrototypeOf(abilityType);
+
+        return ! parentType || parentType === Ability
+            ? ancestors
+            : this.ancestorTypes(parentType, [ parentType, ...ancestors ]);
+    }
 }

package/src/screenplay/abilities/AbilityType.ts

@@ -1,4 +1,5 @@
 import type { Ability } from './Ability';
+import type { UsesAbilities } from './UsesAbilities';
 
 /**
  * An interface describing the static access method that every [`Ability`](https://serenity-js.org/api/core/class/Ability/) class
@@ -43,4 +44,10 @@ import type { Ability } from './Ability';
  * @group Abilities
  */
 export type AbilityType<A extends Ability> =
-    (abstract new (... args: any[]) => A);
+    (abstract new (... args: any[]) => A) & {
+        as<S extends Ability>(
+            this: AbilityType<S>,
+            actor: UsesAbilities
+        ): S;
+        abilityType(): AbilityType<Ability>
+    };

package/src/screenplay/abilities/SerialisedAbility.ts

@@ -0,0 +1,10 @@
+import type { JSONValue } from 'tiny-types';
+
+/**
+ * @group Abilities
+ */
+export interface SerialisedAbility {
+    type: string;
+    class?: string;
+    options?: JSONValue;
+}

package/src/screenplay/abilities/index.ts

@@ -5,4 +5,5 @@ export * from './CanHaveAbilities';
 export * from './Discardable';
 export * from './Initialisable';
 export * from './PerformActivities';
+export * from './SerialisedAbility';
 export * from './UsesAbilities';

package/src/screenplay/index.ts

@@ -12,6 +12,7 @@ export * from './Optional';
 export * from './Question';
 export * from './questions';
 export * from './RecursivelyAnswered';
+export * from './SerialisedActor';
 export * from './Task';
 export * from './time';
 export * from './WithAnswerableProperties';

package/src/screenplay/notes/TakeNotes.ts

@@ -1,4 +1,4 @@
-import { Ability } from '../abilities';
+import { Ability, type SerialisedAbility } from '../abilities';
 import { Notepad } from './Notepad';
 
 /**
@@ -254,4 +254,13 @@ export class TakeNotes<Notes_Type extends Record<any, any>> extends Ability {
     constructor(public readonly notepad: Notepad<Notes_Type>) {
         super();
     }
+
+    toJSON(): SerialisedAbility {
+        return {
+            ...super.toJSON(),
+            options: {
+                notepad: this.notepad.toJSON(),
+            }
+        };
+    }
 }

package/src/screenplay/time/abilities/ScheduleWork.ts

@@ -1,6 +1,6 @@
-import type { Discardable } from '../../abilities';
+import type { Discardable, SerialisedAbility } from '../../abilities';
 import { Ability } from '../../abilities';
-import type { Clock, DelayedCallback, Duration, RepeatUntilLimits} from '../models';
+import type { Clock, DelayedCallback, Duration, RepeatUntilLimits } from '../models';
 import { Scheduler } from '../models';
 
 /**
@@ -40,4 +40,13 @@ export class ScheduleWork extends Ability implements Discardable {
     discard(): void {
         this.scheduler.stop();
     }
+
+    override toJSON(): SerialisedAbility {
+        return {
+            ...super.toJSON(),
+            options: {
+                scheduler: this.scheduler.toJSON(),
+            },
+        };
+    }
 }

package/src/screenplay/time/models/Clock.ts

@@ -1,4 +1,4 @@
-import { ensure, isDefined } from 'tiny-types';
+import { ensure, isDefined, type JSONObject } from 'tiny-types';
 
 import { Duration } from './Duration';
 import { Timestamp } from './Timestamp';
@@ -24,6 +24,12 @@ export class Clock {
     constructor(private readonly checkTime: () => Date = () => new Date()) {
     }
 
+    toJSON(): JSONObject {
+        return {
+            timeAdjustment: this.timeAdjustment.toJSON(),
+        };
+    }
+
     /**
      * Sets the clock ahead to force early resolution of promises
      * returned by [`Clock.waitFor`](https://serenity-js.org/api/core/class/Clock/#waitFor).

package/src/screenplay/time/models/Scheduler.ts

@@ -1,3 +1,5 @@
+import type { JSONObject } from 'tiny-types';
+
 import { OperationInterruptedError, TimeoutExpiredError } from '../../../errors';
 import type { Clock } from './Clock';
 import type { DelayedCallback } from './DelayedCallback';
@@ -23,6 +25,13 @@ export class Scheduler {
     ) {
     }
 
+    toJSON(): JSONObject {
+        return {
+            clock: this.clock.toJSON(),
+            interactionTimeout: this.interactionTimeout.toJSON(),
+        }
+    }
+
     /**
      * Schedules a callback function to be invoked after a delay
      *

package/src/stage/Stage.ts

@@ -1,22 +1,20 @@
 import { ensure, isDefined } from 'tiny-types';
 
-import type { ErrorFactory, ErrorOptions, RuntimeError } from '../errors';
-import { ConfigurationError, LogicError, RaiseErrors } from '../errors';
-import type {
-    DomainEvent,
-    EmitsDomainEvents} from '../events';
+import { ConfigurationError, type ErrorFactory, type ErrorOptions, LogicError, RaiseErrors,type RuntimeError } from '../errors';
 import {
-    AsyncOperationAttempted,
-    AsyncOperationCompleted,
-    AsyncOperationFailed,
+    ActorEntersStage,
+    ActorStageExitAttempted,
+    ActorStageExitCompleted,
+    ActorStageExitFailed,
+    ActorStageExitStarts,
+    type DomainEvent,
+    type EmitsDomainEvents,
     SceneFinishes,
     SceneStarts,
     TestRunFinishes
 } from '../events';
-import type { ActivityDetails} from '../model';
-import { CorrelationId, Description, Name } from '../model';
-import type { Clock, Duration, Timestamp } from '../screenplay';
-import { Actor, ScheduleWork } from '../screenplay';
+import { type ActivityDetails, CorrelationId, Name } from '../model';
+import { Actor, type Clock, type Duration, ScheduleWork, type Timestamp } from '../screenplay';
 import type { ListensToDomainEvents } from '../stage';
 import type { Cast } from './Cast';
 import type { StageManager } from './StageManager';
@@ -39,7 +37,7 @@ import type { StageManager } from './StageManager';
  */
 export class Stage implements EmitsDomainEvents {
 
-    private static readonly unknownSceneId = new CorrelationId('unknown')
+    public static readonly unknownSceneId = new CorrelationId('unknown')
 
     /**
      * Actors instantiated after the scene has started,
@@ -111,9 +109,6 @@ export class Stage implements EmitsDomainEvents {
                 ]);
 
                 actor = this.cast.prepare(newActor);
-
-                // todo this.manager.notifyOf(ActorStarts)
-                // todo: map this in Serenity BDD Reporter so that the "cast" is recorded
             }
             catch (error) {
                 throw new ConfigurationError(`${ this.typeOf(this.cast) } encountered a problem when preparing actor "${ name }" for stage`, error);
@@ -123,7 +118,23 @@ export class Stage implements EmitsDomainEvents {
                 throw new ConfigurationError(`Instead of a new instance of actor "${ name }", ${ this.typeOf(this.cast) } returned ${ actor }`);
             }
 
-            this.actorsOnStage.set(name, actor)
+            this.actorsOnStage.set(name, actor);
+
+            this.announce(
+                new ActorEntersStage(
+                    this.currentScene,
+                    actor.toJSON(),
+                )
+            )
+        }
+
+        if (this.actorsOnBackstage.has(name)) {
+            this.announce(
+                new ActorEntersStage(
+                    this.currentScene,
+                    this.actorsOnBackstage.get(name).toJSON(),
+                )
+            )
         }
 
         this.actorInTheSpotlight = this.instantiatedActorCalled(name);
@@ -192,6 +203,10 @@ export class Stage implements EmitsDomainEvents {
             this.actorsOnStage = this.actorsOnFrontStage;
         }
 
+        if (event instanceof SceneFinishes || event instanceof TestRunFinishes) {
+            this.notifyOfStageExit(this.currentSceneId());
+        }
+
         this.manager.notifyOf(event);
 
         if (event instanceof SceneFinishes) {
@@ -298,6 +313,16 @@ export class Stage implements EmitsDomainEvents {
             : this.actorsOnFrontStage.get(name)
     }
 
+    private notifyOfStageExit(sceneId: CorrelationId): void {
+        for (const actor of this.actorsOnStage.values()) {
+            this.announce(new ActorStageExitStarts(
+                sceneId,
+                actor.toJSON(),
+                this.currentTime(),
+            ));
+        }
+    }
+
     private async dismiss(activeActors: Map<string, Actor>): Promise<void> {
         const actors = Array.from(activeActors.values());
 
@@ -311,10 +336,9 @@ export class Stage implements EmitsDomainEvents {
         const actorsToDismiss = new Map<Actor, CorrelationId>(actors.map(actor => [actor, CorrelationId.create()]));
 
         for (const [ actor, correlationId ] of actorsToDismiss) {
-            this.announce(new AsyncOperationAttempted(
-                new Name(this.constructor.name),
-                new Description(`Dismissing ${ actor.name }...`),
+            this.announce(new ActorStageExitAttempted(
                 correlationId,
+                new Name(actor.name),
                 this.currentTime(),
             ));
         }
@@ -324,13 +348,14 @@ export class Stage implements EmitsDomainEvents {
             try {
                 await actor.dismiss();
 
-                this.announce(new AsyncOperationCompleted(
-                    correlationId,
-                    this.currentTime(),
-                ));
+                this.announce(new ActorStageExitCompleted(correlationId, new Name(actor.name), this.currentTime()));
             }
             catch (error) {
-                this.announce(new AsyncOperationFailed(error, correlationId, this.currentTime()));     // todo: serialise the error!
+                this.announce(new ActorStageExitFailed(
+                    error,
+                    correlationId,
+                    this.currentTime()
+                ));
             }
         }