@serenity-js/core 3.2.0 → 3.3.0

package/src/screenplay/Actor.ts

@@ -1,26 +1,22 @@
-import { match } from 'tiny-types';
-
-import { AssertionError, ConfigurationError, ImplementationPendingError, TestCompromisedError } from '../errors';
-import { ActivityRelatedArtifactGenerated, InteractionFinished, InteractionStarts, TaskFinished, TaskStarts } from '../events';
+import { ConfigurationError, TestCompromisedError } from '../errors';
+import { ActivityRelatedArtifactGenerated } from '../events';
 import { typeOf } from '../io';
-import {
-    ActivityDetails,
-    Artifact,
-    ExecutionCompromised,
-    ExecutionFailedWithAssertionError,
-    ExecutionFailedWithError,
-    ExecutionSuccessful,
-    ImplementationPending,
-    Name,
-    ProblemIndication,
-} from '../model';
-import { Ability, AbilityType, Answerable, Discardable, Initialisable, Interaction } from '../screenplay';
+import { Artifact, Name, } from '../model';
 import { Stage } from '../stage';
-import { CanHaveAbilities, UsesAbilities } from './abilities';
+import {
+    Ability,
+    AbilityType,
+    AnswerQuestions,
+    CanHaveAbilities,
+    Discardable,
+    Initialisable,
+    PerformActivities,
+    UsesAbilities
+} from './abilities';
 import { PerformsActivities } from './activities';
 import { Activity } from './Activity';
+import { Answerable } from './Answerable';
 import { CollectsArtifacts } from './artifacts';
-import { Question } from './Question';
 import { AnswersQuestions } from './questions';
 
 /**
@@ -82,18 +78,23 @@ import { AnswersQuestions } from './questions';
  *
  * @group Screenplay Pattern
  */
-export class Actor implements
-    PerformsActivities,
+export class Actor implements PerformsActivities,
     UsesAbilities,
     CanHaveAbilities<Actor>,
     AnswersQuestions,
-    CollectsArtifacts
-{
+    CollectsArtifacts {
+    private readonly abilities: Map<AbilityType<Ability>, Ability> = new Map<AbilityType<Ability>, Ability>();
+
     constructor(
         public readonly name: string,
         private readonly stage: Stage,
-        private readonly abilities: Map<AbilityType<Ability>, Ability> = new Map<AbilityType<Ability>, Ability>(),
+        abilities: Ability[] = [],
     ) {
+        [
+            new PerformActivities(this, stage),
+            new AnswerQuestions(this),
+            ...abilities
+        ].forEach(ability => this.acquireAbility(ability));
     }
 
     /**
@@ -111,16 +112,9 @@ export class Actor implements
         const found = this.findAbilityTo(abilityType);
 
         if (! found) {
-            if (this.abilities.size > 0) {
-                throw new ConfigurationError(
-                    `${ this.name } can ${ Array.from(this.abilities.keys()).map(type => type.name).join(', ') }. ` +
-                    `They can't, however, ${ abilityType.name } yet. ` +
-                    `Did you give them the ability to do so?`
-                );
-            }
-
             throw new ConfigurationError(
-                `${ this.name } can't ${ abilityType.name } yet. ` +
+                `${ this.name } can ${ Array.from(this.abilities.keys()).map(type => type.name).join(', ') }. ` +
+                `They can't, however, ${ abilityType.name } yet. ` +
                 `Did you give them the ability to do so?`
             );
         }
@@ -137,15 +131,9 @@ export class Actor implements
      */
     attemptsTo(...activities: Activity[]): Promise<void> {
         return activities
-            .map(activity => new TrackedActivity(activity, this.stage))
             .reduce((previous: Promise<void>, current: Activity) => {
                 return previous
-                    // synchronise async operations like taking screenshots
-                    .then(() => this.stage.waitForNextCue())
-                    .then(() =>{
-                        /* todo: add an execution strategy */
-                        return current.performAs(this);
-                    });
+                    .then(() => PerformActivities.as(this).perform(current));
             }, this.initialiseAbilities());
     }
 
@@ -176,23 +164,7 @@ export class Actor implements
      *  The answer to the Answerable
      */
     answer<T>(answerable: Answerable<T>): Promise<T> {
-        function isAPromise<V>(v: Answerable<V>): v is Promise<V> {
-            return Object.prototype.hasOwnProperty.call(v, 'then');
-        }
-
-        function isDefined<V>(v: Answerable<V>) {
-            return ! (v === undefined || v === null);
-        }
-
-        if (isDefined(answerable) && isAPromise(answerable)) {
-            return answerable;
-        }
-
-        if (isDefined(answerable) && Question.isAQuestion(answerable)) {
-            return this.answer(answerable.answeredBy(this));
-        }
-
-        return Promise.resolve(answerable as T);
+        return AnswerQuestions.as(this).answer(answerable);
     }
 
     /**
@@ -237,7 +209,7 @@ export class Actor implements
 
     private initialiseAbilities(): Promise<void> {
         return this.findAbilitiesOfType<Initialisable>('initialise', 'isInitialised')
-            .filter(ability => ! ability.isInitialised())
+            .filter(ability => !ability.isInitialised())
             .reduce(
                 (previous: Promise<void>, ability: (Initialisable & Ability)) =>
                     previous
@@ -254,7 +226,7 @@ export class Actor implements
             Array.from(map.values());
 
         const abilitiesWithDesiredMethods = (ability: Ability & T): boolean =>
-            methodNames.every(methodName => typeof(ability[methodName]) === 'function');
+            methodNames.every(methodName => typeof (ability[methodName]) === 'function');
 
         return abilitiesFrom(this.abilities)
             .filter(abilitiesWithDesiredMethods) as Array<Ability & T>;
@@ -267,7 +239,7 @@ export class Actor implements
     }
 
     private acquireAbility(ability: Ability): void {
-        if (! (ability instanceof Ability)) {
+        if (!(ability instanceof Ability)) {
             throw new ConfigurationError(`Custom abilities must extend Ability from '@serenity-js/core'. Received ${ typeOf(ability) }`);
         }
 
@@ -280,7 +252,7 @@ export class Actor implements
         abilityType: AbilityType<Specific_Ability>
     ): AbilityType<Generic_Ability> {
         const parentType = Object.getPrototypeOf(abilityType);
-        return ! parentType || parentType === Ability
+        return !parentType || parentType === Ability
             ? abilityType
             : this.mostGenericTypeOf(parentType)
     }
@@ -297,74 +269,3 @@ export class Actor implements
             : maybeName;
     }
 }
-
-class ActivityDescriber {
-
-    describe(activity: Activity, actor: { name: string }): Name {
-        const template = activity.toString() === ({}).toString()
-            ? `#actor performs ${ activity.constructor.name }`
-            : activity.toString();
-
-        return new Name(
-            this.includeActorName(template, actor),
-        );
-    }
-
-    private includeActorName(template: string, actor: { name: string }) {
-        return template.replace('#actor', actor.name);
-    }
-}
-
-class OutcomeMatcher {
-    outcomeFor(error: Error | any): ProblemIndication {
-        return match<Error, ProblemIndication>(error)
-            .when(ImplementationPendingError, _ => new ImplementationPending(error))
-            .when(TestCompromisedError, _ => new ExecutionCompromised(error))
-            .when(AssertionError, _ => new ExecutionFailedWithAssertionError(error))
-            .when(Error, _ =>
-                /AssertionError/.test(error.constructor.name) // mocha
-                    ? new ExecutionFailedWithAssertionError(error)
-                    : new ExecutionFailedWithError(error))
-            .else(_ => new ExecutionFailedWithError(error));
-    }
-}
-
-class TrackedActivity extends Activity {
-
-    protected static readonly describer = new ActivityDescriber();
-    protected static readonly outcomes = new OutcomeMatcher();
-
-    constructor(
-        protected readonly activity: Activity,
-        protected readonly stage: Stage,
-    ) {
-        super(activity.toString(), activity.instantiationLocation());
-    }
-
-    performAs(actor: (PerformsActivities | UsesAbilities | AnswersQuestions) & { name: string }): Promise<void> {
-        const sceneId = this.stage.currentSceneId();
-        const details = new ActivityDetails(
-            TrackedActivity.describer.describe(this.activity, actor),
-            this.activity.instantiationLocation(),
-        );
-        const activityId = this.stage.assignNewActivityId(details);
-
-        const [ activityStarts, activityFinished] = this.activity instanceof Interaction
-            ? [ InteractionStarts, InteractionFinished ]
-            : [ TaskStarts, TaskFinished ];
-
-        return Promise.resolve()
-            .then(() => this.stage.announce(new activityStarts(sceneId, activityId, details, this.stage.currentTime())))
-            .then(() => this.activity.performAs(actor))
-            .then(() => {
-                const outcome = new ExecutionSuccessful();
-                this.stage.announce(new activityFinished(sceneId, activityId, details, outcome, this.stage.currentTime()));
-            })
-            .catch(error => {
-                const outcome = TrackedActivity.outcomes.outcomeFor(error);
-                this.stage.announce(new activityFinished(sceneId, activityId, details, outcome, this.stage.currentTime()));
-
-                throw error;
-            });
-    }
-}

package/src/screenplay/abilities/AnswerQuestions.ts

@@ -0,0 +1,41 @@
+import { Answerable } from '../Answerable';
+import { Question } from '../Question';
+import { AnswersQuestions } from '../questions';
+import { Ability } from './Ability';
+import { UsesAbilities } from './UsesAbilities';
+
+/**
+ * This {@apilink Ability} enables an {@apilink Actor} to resolve the value of a given {@apilink Answerable}.
+ *
+ * {@apilink AnswerQuestions} is used internally by {@apilink Actor.answer}, and it is unlikely you'll ever need to use it directly in your code.
+ * That is, unless you're building a custom Serenity/JS extension and want to override the default behaviour of the framework,
+ * in which case you should check out the [Contributor's Guide](/contributing).
+ *
+ * @group Abilities
+ */
+export class AnswerQuestions extends Ability {
+    constructor(protected readonly actor: AnswersQuestions & UsesAbilities) {
+        super();
+    }
+
+    answer<T>(answerable: Answerable<T>): Promise<T> {
+
+        if (AnswerQuestions.isDefined(answerable) && AnswerQuestions.isAPromise(answerable)) {
+            return answerable;
+        }
+
+        if (AnswerQuestions.isDefined(answerable) && Question.isAQuestion(answerable)) {
+            return this.answer(answerable.answeredBy(this.actor));
+        }
+
+        return Promise.resolve(answerable as T);
+    }
+
+    private static isAPromise<V>(v: Answerable<V>): v is Promise<V> {
+        return Object.prototype.hasOwnProperty.call(v, 'then');
+    }
+
+    private static isDefined<V>(v: Answerable<V>) {
+        return !(v === undefined || v === null);
+    }
+}

package/src/screenplay/abilities/PerformActivities.ts

@@ -0,0 +1,88 @@
+import { match } from 'tiny-types';
+
+import { AssertionError, ImplementationPendingError, TestCompromisedError } from '../../errors';
+import { EmitsDomainEvents, InteractionFinished, InteractionStarts, TaskFinished, TaskStarts } from '../../events';
+import {
+    ActivityDetails,
+    ExecutionCompromised,
+    ExecutionFailedWithAssertionError,
+    ExecutionFailedWithError,
+    ExecutionSuccessful,
+    ImplementationPending,
+    Name,
+    Outcome,
+    ProblemIndication
+} from '../../model';
+import { PerformsActivities } from '../activities/PerformsActivities';
+import { Activity } from '../Activity';
+import { Interaction } from '../Interaction';
+import { Ability } from './index';
+
+/**
+ * An {@apilink Ability} that enables an {@apilink Actor} to perform a given {@apilink Activity}.
+ *
+ * {@apilink PerformActivities} is used internally by {@apilink Actor.perform}, and it is unlikely you'll ever need to use it directly in your code.
+ * That is, unless you're building a custom Serenity/JS extension and want to override the default behaviour of the framework,
+ * in which case you should check out the [Contributor's Guide](/contributing).
+ *
+ * @group Abilities
+ */
+export class PerformActivities extends Ability {
+    constructor(
+        protected readonly actor: PerformsActivities & { name: string },
+        protected readonly stage: EmitsDomainEvents,
+    ) {
+        super();
+    }
+
+    async perform(activity: Activity): Promise<void> {
+        const sceneId = this.stage.currentSceneId();
+        const details = this.detailsOf(activity);
+        const activityId = this.stage.assignNewActivityId(details);
+
+        const [ activityStarts, activityFinished ] = activity instanceof Interaction
+            ? [ InteractionStarts, InteractionFinished ]
+            : [ TaskStarts, TaskFinished ];
+
+        try {
+            this.stage.announce(new activityStarts(sceneId, activityId, details, this.stage.currentTime()))
+
+            await activity.performAs(this.actor);
+
+            this.stage.announce(new activityFinished(sceneId, activityId, details, new ExecutionSuccessful(), this.stage.currentTime()));
+        }
+        catch (error) {
+            this.stage.announce(new activityFinished(sceneId, activityId, details, this.outcomeFor(error), this.stage.currentTime()));
+            throw error;
+        }
+        finally {
+            await this.stage.waitForNextCue();
+        }
+    }
+    protected outcomeFor(error: Error | any): Outcome {
+        return match<Error, ProblemIndication>(error)
+            .when(ImplementationPendingError, _ => new ImplementationPending(error))
+            .when(TestCompromisedError, _ => new ExecutionCompromised(error))
+            .when(AssertionError, _ => new ExecutionFailedWithAssertionError(error))
+            .when(Error, _ =>
+                /AssertionError/.test(error.constructor.name) // mocha
+                    ? new ExecutionFailedWithAssertionError(error)
+                    : new ExecutionFailedWithError(error))
+            .else(_ => new ExecutionFailedWithError(error));
+    }
+
+    private detailsOf(activity: Activity): ActivityDetails {
+        return new ActivityDetails(
+            new Name(this.nameOf(activity)),
+            activity.instantiationLocation(),
+        )
+    }
+
+    protected nameOf(activity: Activity): string {
+        const template = activity.toString() === ({}).toString()
+            ? `#actor performs ${ activity.constructor.name }`
+            : activity.toString();
+
+        return template.replace('#actor', this.actor.name);
+    }
+}

package/src/screenplay/abilities/index.ts

@@ -1,6 +1,8 @@
 export * from './Ability';
 export * from './AbilityType';
+export * from './AnswerQuestions';
 export * from './CanHaveAbilities';
 export * from './Discardable';
 export * from './Initialisable';
+export * from './PerformActivities';
 export * from './UsesAbilities';

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

@@ -1,4 +1,4 @@
-import { Ability, Discardable, Initialisable } from '../../abilities';
+import { Ability, Discardable } from '../../abilities';
 import { Clock, DelayedCallback, Duration, RepeatUntilLimits, Scheduler } from '../models';
 
 /**
@@ -11,7 +11,7 @@ import { Clock, DelayedCallback, Duration, RepeatUntilLimits, Scheduler } from '
  *
  * @group Time
  */
-export class ScheduleWork extends Ability implements Initialisable, Discardable {
+export class ScheduleWork extends Ability implements Discardable {
 
     private readonly scheduler: Scheduler;
 
@@ -20,14 +20,6 @@ export class ScheduleWork extends Ability implements Initialisable, Discardable
         this.scheduler = new Scheduler(clock, interactionTimeout);
     }
 
-    initialise(): void {
-        this.scheduler.start();
-    }
-
-    isInitialised(): boolean {
-        return this.scheduler.isRunning();
-    }
-
     /**
      * @param callback
      * @param limits

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

@@ -1,3 +1,6 @@
+import { ensure, isDefined } from 'tiny-types';
+
+import { Duration } from './Duration';
 import { Timestamp } from './Timestamp';
 
 /**
@@ -15,14 +18,57 @@ import { Timestamp } from './Timestamp';
  * @group Time
  */
 export class Clock {
+    private static resolution: Duration = Duration.ofMilliseconds(10);
+    private timeAdjustment: Duration = Duration.ofMilliseconds(0);
 
     constructor(private readonly checkTime: () => Date = () => new Date()) {
     }
 
+    /**
+     * Sets the clock ahead to force early resolution of promises
+     * returned by {@apilink Clock.waitFor};
+     *
+     * Useful for test purposes to avoid unnecessary delays.
+     *
+     * @param duration
+     */
+    setAhead(duration: Duration): void {
+        this.timeAdjustment = ensure('duration', duration, isDefined());
+    }
+
+    /**
+     * Returns a Promise that resolves after one tick of the clock.
+     *
+     * Useful for test purposes to avoid unnecessary delays.
+     */
+    async tick(): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, Clock.resolution.inMilliseconds()));
+    }
+
     /**
      * Returns current time
      */
     now(): Timestamp {
-        return new Timestamp(this.checkTime());
+        return new Timestamp(this.checkTime()).plus(this.timeAdjustment);
+    }
+
+    /**
+     * Returns a Promise that will be resolved after the given duration
+     *
+     * @param duration
+     */
+    async waitFor(duration: Duration): Promise<void> {
+        const stopAt = this.now().plus(duration);
+
+        let timer: NodeJS.Timer;
+
+        return new Promise<void>(resolve => {
+            timer = setInterval(() => {
+                if (this.now().isAfterOrEqual(stopAt)) {
+                    clearInterval(timer);
+                    return resolve();
+                }
+            }, Clock.resolution.inMilliseconds());
+        });
     }
 }