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

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

@@ -0,0 +1,12 @@
+import { Duration } from './Duration';
+
+/**
+ * @group Time
+ */
+export interface RepeatUntilLimits<Result> {
+    exitCondition?: (result: Result) => boolean,
+    maxInvocations?: number,
+    delayBetweenInvocations?: (i: number) => Duration,
+    timeout?: Duration
+    errorHandler?: (error: Error, result?: Result) => void;
+}

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

@@ -0,0 +1,226 @@
+import { OperationInterruptedError, TimeoutExpiredError } from '../../../errors';
+import { Clock } from './Clock';
+import { DelayedCallback } from './DelayedCallback';
+import { Duration } from './Duration';
+import { RepeatUntilLimits } from './RepeatUntilLimits';
+import { Timestamp } from './Timestamp';
+
+/**
+ * @group Time
+ */
+export class Scheduler {
+
+    private remainingCallbacks: Map<DelayedCallback<unknown>, CallbackInfo<unknown>> = new Map();
+    private completedCallbacks: Map<DelayedCallback<unknown>, CallbackInfo<unknown>> = new Map();
+    private failedCallbacks:    Map<DelayedCallback<unknown>, CallbackInfo<unknown>> = new Map();
+
+    private timer: NodeJS.Timer;
+
+    /**
+     * @param clock
+     * @param interactionTimeout
+     *  The maximum amount of time to give to a callback to complete before throwing an error
+     */
+    constructor(
+        private readonly clock: Clock,
+        private readonly interactionTimeout: Duration,
+    ) {
+    }
+
+    /**
+     * Schedules a callback function to be invoked after a delay
+     *
+     * @param delay
+     * @param callback
+     */
+    after<Result>(delay: Duration, callback: DelayedCallback<Result>): Promise<Result> {
+        return this.repeatUntil<Result>(
+            callback,
+            {
+                maxInvocations: 1,
+                delayBetweenInvocations: () => delay,
+                timeout: this.interactionTimeout,
+            },
+        );
+    }
+
+    /**
+     * Schedules a callback function to be repeated, according to configured limits.
+     *
+     * @param callback
+     * @param limits
+     */
+    async repeatUntil<Result>(
+        callback: DelayedCallback<Result>,
+        limits: RepeatUntilLimits<Result> = {},
+    ): Promise<Result> {
+
+        const {
+            maxInvocations          = Number.POSITIVE_INFINITY,
+            delayBetweenInvocations = noDelay,
+            timeout                 = this.interactionTimeout,
+            exitCondition           = noEarlyExit,
+            errorHandler            = rethrowErrors,
+        } = limits;
+
+        this.remainingCallbacks.set(callback, {
+            exitCondition: exitCondition,
+            currentInvocation: 0,
+            invocationsLeft: maxInvocations,
+            delayBetweenInvocations,
+            startedAt: this.clock.now(),
+            timeout,
+            errorHandler,
+            result: undefined,
+        });
+
+        return this.receiptFor<Result>(callback);
+    }
+
+    start(): void {
+        if (! this.timer) {
+            this.timer = setInterval(
+                () =>  this.invokeCallbacksScheduledUntil(this.clock.now()),
+                100
+            )
+        }
+    }
+
+    isRunning(): boolean {
+        return Boolean(this.timer);
+    }
+
+    stop(): void {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+
+            for (const [callback, info] of this.remainingCallbacks) {
+                this.remainingCallbacks.delete(callback);
+                this.failedCallbacks.set(callback, {
+                    ...info,
+                    error: new OperationInterruptedError(`Scheduler stopped before executing callback ${ callback }`)
+                });
+            }
+        }
+    }
+
+    invokeCallbacksScheduledForNext(duration: Duration): void {
+        this.invokeCallbacksScheduledUntil(
+            this.clock.now().plus(duration)
+        );
+    }
+
+    private invokeCallbacksScheduledUntil(timestamp: Timestamp): void {
+        for (const [ callback, info ] of this.remainingCallbacks) {
+            const { startedAt, currentInvocation, delayBetweenInvocations } = info;
+            const expectedInvocationTime = startedAt.plus(delayBetweenInvocations(currentInvocation));
+
+            if (expectedInvocationTime.isBeforeOrEqual(timestamp)) {
+                this.invoke(callback);
+            }
+        }
+    }
+
+    private invoke<Result>(callback: DelayedCallback<Result>): void {
+        const info = this.remainingCallbacks.get(callback);
+
+        this.remainingCallbacks.delete(callback);
+
+        Promise.resolve()
+            .then(async () => {
+                const timeoutExpired = info.startedAt.plus(info.timeout).isBefore(this.clock.now());
+                const isLastInvocation = info.invocationsLeft === 1;
+
+                if (info.invocationsLeft === 0) {
+                    return {
+                        hasCompleted: true,
+                    };
+                }
+
+                try {
+                    if (timeoutExpired) {
+                        throw new TimeoutExpiredError(`Timeout of ${ info.timeout } has expired`);
+                    }
+
+                    const result = await callback({ currentTime: this.clock.now(), i: info.currentInvocation });
+
+                    return {
+                        result,
+                        hasCompleted: info.exitCondition(result) || isLastInvocation,
+                    }
+                }
+                catch(error) {
+                    info.errorHandler(error, info.result);
+
+                    // if the errorHandler didn't throw, it's a recoverable error
+                    return {
+                        error,
+                        hasCompleted: isLastInvocation,
+                    }
+                }
+            })
+            .then(({ result, error, hasCompleted }) => {
+                if (hasCompleted) {
+                    this['completedCallbacks'].set(callback, {
+                        ...info,
+                        result: result ?? info.result,
+                        error,
+                    });
+                }
+                else {
+                    this['remainingCallbacks'].set(callback, {
+                        ...info,
+                        currentInvocation:  info.currentInvocation + 1,
+                        invocationsLeft:    info.invocationsLeft - 1,
+                        result: result ?? info.result,
+                        error,
+                    });
+                }
+            })
+            .catch(error => {
+                this.failedCallbacks.set(callback, { ...info, error });
+            });
+    }
+
+    private receiptFor<Result>(callback: DelayedCallback<unknown>): Promise<Result> {
+        return new Promise((resolve, reject) => {
+
+            const timer = setInterval(() => {
+                if (this.failedCallbacks.has(callback)) {
+                    clearInterval(timer);
+                    return reject(this.failedCallbacks.get(callback).error);
+                }
+
+                if (this.completedCallbacks.has(callback)) {
+                    clearInterval(timer);
+                    return resolve(this.completedCallbacks.get(callback).result as Result);
+                }
+            }, 25);
+        })
+    }
+}
+
+interface CallbackInfo<Result> {
+    exitCondition: (result: Result) => boolean,
+    currentInvocation: number;
+    invocationsLeft: number,
+    delayBetweenInvocations: (i: number) => Duration,
+    timeout: Duration
+    startedAt: Timestamp,
+    errorHandler: (error: Error, result: Result) => void,
+    result?: Result,
+    error?: Error,
+}
+
+function noDelay() {
+    return Duration.ofMilliseconds(0);
+}
+
+function noEarlyExit() {
+    return false;
+}
+
+function rethrowErrors(error: Error) {
+    throw error;
+}

package/src/{model → screenplay/time/models}/Timestamp.ts

@@ -1,8 +1,19 @@
-import * as moment from 'moment';
+import moment from 'moment';
 import { ensure, isDefined, isInstanceOf, Predicate, TinyType } from 'tiny-types';
 
 import { Duration } from './Duration';
 
+/**
+ * Represents a point in time.
+ *
+ * `Timestamp` makes it easier for Serenity/JS to work with information related to time, like {@apilink DomainEvent|domain events}.
+ *
+ * ## Learn more
+ * - {@apilink Duration}
+ * - [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
+ *
+ * @group Time
+ */
 export class Timestamp extends TinyType {
     static fromJSON(v: string): Timestamp {
         return new Timestamp(new Date(ensure(Timestamp.name, v, isSerialisedISO8601Date())));
@@ -22,17 +33,40 @@ export class Timestamp extends TinyType {
     }
 
     diff(another: Timestamp): Duration {
+        ensure('timestamp', another, isDefined());
         return new Duration(Math.abs(moment(this.value).diff(another.value, 'ms', true)));
     }
 
     plus(duration: Duration): Timestamp {
+        ensure('duration', duration, isDefined());
         return new Timestamp(moment(this.value).add(duration.inMilliseconds(), 'ms').toDate());
     }
 
     less(duration: Duration): Timestamp {
+        ensure('duration', duration, isDefined());
         return new Timestamp(moment(this.value).subtract(duration.inMilliseconds(), 'ms').toDate());
     }
 
+    isBefore(another: Timestamp): boolean {
+        ensure('timestamp', another, isDefined());
+        return this.value.getTime() < another.value.getTime();
+    }
+
+    isBeforeOrEqual(another: Timestamp): boolean {
+        ensure('timestamp', another, isDefined());
+        return this.value.getTime() <= another.value.getTime();
+    }
+
+    isAfter(another: Timestamp): boolean {
+        ensure('timestamp', another, isDefined());
+        return this.value.getTime() > another.value.getTime();
+    }
+
+    isAfterOrEqual(another: Timestamp): boolean {
+        ensure('timestamp', another, isDefined());
+        return this.value.getTime() >= another.value.getTime();
+    }
+
     toMilliseconds(): number {
         return moment(this.value).valueOf();
     }
@@ -46,7 +80,7 @@ export class Timestamp extends TinyType {
     }
 
     toString(): string {
-        return this.value.toString();
+        return this.value.toISOString();
     }
 }
 

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

@@ -0,0 +1,6 @@
+export * from './Clock';
+export * from './DelayedCallback';
+export * from './Duration';
+export * from './RepeatUntilLimits';
+export * from './Scheduler';
+export * from './Timestamp';

package/src/stage/Cast.ts

@@ -1,90 +1,175 @@
-import { Ability, Actor } from '../screenplay';
+import { Actor } from '../screenplay';
 
 /**
- * @desc
- *  Describes the {@link Actor}s available to take part in the performance.
+ * Serenity/JS uses the concept of a _**cast of actors**_ to centralise the process of configuring the {@apilink Actor|actors} and assigning their {@apilink Ability|abilities}.
  *
- * @example <caption>Define a cast of actors interacting with a Web UI</caption>
+ * When you invoke {@apilink actorCalled} for the first time in a test scenario,
+ * Serenity/JS {@apilink Actor|instantiates a new actor}
+ * and passes it through the {@apilink Cast.prepare} method.
+ * Specifying a **custom cast** gives you an opportunity to configure the actor with the abilities
+ * they need before it's returned to the caller,
+ * or configure the actors differently **depending on their name**.
+ * It also helps you to avoid having to configure abilities individually in every test scenario.
  *
- *  import { engage, Actor, Cast } from '@serenity-js/core';
- *  import { BrowseTheWeb } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
+ * :::tip Remember
+ * A **cast** is responsible for assigning **abilities** to **actors** in a central location.
+ * :::
  *
- *  class UIActors implements Cast {
- *      prepare(actor: Actor) {
- *          return actor.whoCan(BrowseTheWeb.using(protractor.browser));
- *      }
- *  }
+ * ## Configuring a cast of actors for the entire test suite
  *
- *  beforeEach(() => engage(new UIActors()));
+ * When working with relatively **simple scenarios** where all the actors should always receive the same set of abilities,
+ * you can {@apilink configure} Serenity/JS to use a generic {@apilink Cast.where}:
  *
- * @example <caption>Using a generic cast</caption>
+ * ```typescript
+ * import { Cast, configure } from '@serenity-js/core'
+ * import { CallAnApi } from '@serenity-js/rest'
  *
- *  import { engage, Cast } from '@serenity-js/core';
- *  import { BrowseTheWeb } from '@serenity-js/protractor';
- *  import { protractor } from 'protractor';
+ * configure({
+ *   actors: Cast.where(actor => actor.whoCan(
+ *     CallAnApi.at('http://api.example.org'),
+ *     // other abilities
+ *   ))
+ * })
+ * ```
  *
- *  beforeEach(() => engage(BrowseTheWeb.using(protractor.browser)));
+ * If you're using Serenity/JS with one of the [supported test runners](/handbook/test-runners/),
+ * you might prefer to use your test runner's native configuration mechanism
+ * instead of invoking {@apilink configure} explicitly.
  *
- * @example <caption>Preparing actors differently based on their name</caption>
+ * :::tip configure vs engage
+ * Calling {@apilink configure} resets the entire Serenity/JS configuration
+ * and should be done exactly once in your entire test suite.
+ * If you want to retain the configuration but reset the cast, use {@apilink engage} instead.
+ * :::
  *
- *  import { actorCalled, engage, Cast } from '@serenity-js/core';
- *  import { BrowseTheWeb } from '@serenity-js/protractor';
- *  import { CallAnApi } from '@serenity-js/rest';
- *  import { protractor } from 'protractor';
+ * Learn more about configuring Serenity/JS with:
+ * - [Cucumber.js](/handbook/test-runners/cucumber)
+ * - [Jasmine](/handbook/test-runners/jasmine)
+ * - [Mocha](/handbook/test-runners/mocha)
+ * - [Playwright Test](/handbook/test-runners/playwright-test)
+ * - [Protractor](/handbook/test-runners/protractor)
+ * - [WebdriverIO](/handbook/test-runners/webdriverio)
  *
- *  class Actors implements Cast {
- *      prepare(actor: Actor) {
- *          switch (actor.name) {
- *              case 'James':
- *                  return actor.whoCan(BrowseTheWeb.using(protractor.browser));
- *              default:
- *                  return actor.whoCan(CallAnApi.at(protractor.browser.baseUrl));
- *          }
- *      }
- *  }
+ * ## Engaging a cast of actors for the specific scenario
  *
- *  beforeEach(() => engage(new Actors()));
+ * If you want to retain Serenity/JS configuration, but set a different {@apilink Cast}
+ * for the given test scenario you should use {@apilink engage} instead of {@apilink configure}.
  *
- *  actorCalled('James') // returns an actor using a browser
- *  actorCalled('Alice') // returns an actor interacting with an API
+ * This approach is useful for example when your entire test suite is dedicated to interacting with the system
+ * under test via its REST APIs, and you have a handful of scenarios that need a web browser.
  *
- * @see {@link Stage}
- * @interface
+ * ```ts
+ * import { describe, beforeEach } from 'mocha'
+ * import { engage, Cast } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * describe('My UI feature', () => {
+ *   beforeEach(async () => {
+ *     const browser = await chromium.launch({ headless: true })
+ *     engage(Cast.where(actor => actor.whoCan(BrowseTheWebWithPlaywright.using(browser))))
+ *   })
+ *
+ *   // test scenarios
+ * })
+ * ```
+ *
+ * ## Writing custom casts for complex scenarios
+ *
+ * In **complex scenarios** that involve multiple **actors with different abilities**,
+ * you should create a custom implementation of the {@apilink Cast}.
+ *
+ * Examples of such scenarios include those where actors use separate browser instances, interact with different REST APIs,
+ * or start with different data in their {@apilink Notepad|notepads}.
+ *
+ * ### Defining a custom cast of actors interacting with a Web UI
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { engage, Actor, Cast } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright, PlaywrightOptions } from '@serenity-js/playwright'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * export class UIActors implements Cast {
+ *   constructor(
+ *     private readonly browser: Browser,
+ *     private readonly options?: PlaywrightOptions,
+ *   ) {
+ *   }
+ *
+ *   prepare(actor: Actor): Actor {
+ *     return actor.whoCan(
+ *       BrowseTheWebWithPlaywright.using(this.browser, this.options),
+ *     )
+ *   }
+ * }
+ *
+ * beforeEach(async () => {
+ *   const browser = await chromium.launch({ headless: true })
+ *   engage(new UIActors(browser));
+ * });
+ * ```
+ *
+ * ### Preparing actors differently based on their name
+ *
+ * ```ts
+ * import { beforeEach } from 'mocha'
+ * import { actorCalled, engage, Cast } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { CallAnApi } from '@serenity-js/rest'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * class Actors implements Cast {
+ *   constructor(
+ *     private readonly browser: Browser,
+ *     private readonly options: PlaywrightOptions,
+ *   ) {
+ *   }
+ *
+ *   prepare(actor: Actor) {
+ *     switch (actor.name) {
+ *       case 'James':
+ *         return actor.whoCan(BrowseTheWebWithPlaywright.using(this.browser, this.options));
+ *       default:
+ *         return actor.whoCan(CallAnApi.at(this.options.baseURL));
+ *     }
+ *   }
+ * }
+ *
+ * beforeEach(async () => {
+ *   const browser = await chromium.launch({ headless: true })
+ *   engage(new Actors(browser, { baseURL: 'https://example.org' }));
+ * });
+ *
+ * actorCalled('James') // returns an actor using a browser
+ * actorCalled('Alice') // returns an actor interacting with an API
+ * ```
+ *
+ * @group Stage
  */
 export abstract class Cast {
+
     /**
-     * @desc
-     *  Creates a generic `Cast` implementation, where every actor
-     *  is given all the abilities specified when the method is called.
+     * Creates a generic `Cast` implementation, where new actors receive the abilities
+     * configured by the `prepareFunction`.
      *
-     * @param {Ability[]} abilities
-     * @returns {Cast}
+     * @param prepareFunction
      */
-    static whereEveryoneCan(...abilities: Ability[]): Cast {
-        return new GenericCast(abilities);
+    static where(prepareFunction: (actor: Actor) => Actor): Cast {
+        return new class GenericCast extends Cast {
+            prepare(actor: Actor): Actor {
+                return prepareFunction(actor);
+            }
+        }
     }
 
     /**
-     * @desc
-     *  Configures an {@link Actor} instantiated when {@link Stage#actor} is invoked.
+     * Configures an {@apilink Actor} instantiated when {@apilink Stage.actor} is invoked.
      *
-     * @param {Actor} actor
-     * @return {Actor}
+     * @param actor
      *
-     * @see {@link engage}
+     * #### Learn more
+     * - {@apilink engage}
      */
     abstract prepare(actor: Actor): Actor;
 }
-
-/**
- * @package
- */
-class GenericCast implements Cast {
-    constructor(private readonly abilities: Ability[]) {
-    }
-
-    prepare(actor: Actor): Actor {
-        return actor.whoCan(...this.abilities);
-    }
-}

package/src/stage/Extras.ts

@@ -2,10 +2,7 @@ import { Actor } from '../screenplay';
 import { Cast } from './Cast';
 
 /**
- * @desc
- *  Produces no-op actors with no special {@link Ability}
- *
- * @private
+ * Produces no-op actors with no special {@apilink Ability}
  */
 export class Extras implements Cast {
     prepare(actor: Actor): Actor {

package/src/stage/ListensToDomainEvents.ts

@@ -1,22 +1,24 @@
 import { DomainEvent } from '../events';
 
 /**
- * @desc
- *  A {@link StageCrewMember} that can listen and react to {@link DomainEvent}s
+ * A {@apilink StageCrewMember} that can listen and react to {@apilink DomainEvent|DomainEvents}
  *
- * @see {@link StageCrewMember}
- * @see {@link StageCrewMemberBuilder}
- * @see {@link Serenity#configure}
- * @see {@link SerenityConfig#crew}
+ * ## Learn more
+ *
+ * - {@apilink StageCrewMember}
+ * - {@apilink StageCrewMemberBuilder}
+ * - {@apilink configure}
+ * - {@apilink SerenityConfig.crew}
+ *
+ * @group Stage
  */
 export interface ListensToDomainEvents {
 
     /**
-     * @desc
-     *  Handles {@link DomainEvent} objects emitted by the {@link Stage}
-     *  that this {@link StageCrewMember} is assigned to.
+     * Handles {@apilink DomainEvent} objects emitted by the {@apilink Stage}
+     * that this {@apilink StageCrewMember} is assigned to.
      *
-     * @type {function(event: DomainEvent): void}
+     * @param event
      */
-    notifyOf: (event: DomainEvent) => void;
+    notifyOf(event: DomainEvent): void;
 }