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

package/src/stage/StageManager.ts

@@ -1,8 +1,11 @@
 import { AsyncOperationAttempted, AsyncOperationCompleted, AsyncOperationFailed, DomainEvent } from '../events';
-import { CorrelationId, Description, Duration, Timestamp } from '../model';
+import { CorrelationId, Description, Name } from '../model';
+import { Clock, Duration, Timestamp } from '../screenplay';
 import { ListensToDomainEvents } from '../stage';
-import { Clock } from './Clock';
 
+/**
+ * @group Stage
+ */
 export class StageManager {
     private readonly subscribers: ListensToDomainEvents[] = [];
     private readonly wip: WIP;
@@ -25,28 +28,13 @@ export class StageManager {
         this.subscribers.forEach(crewMember => crewMember.notifyOf(event));
     }
 
-    waitForNextCue(): Promise<void> {
+    waitForAsyncOperationsToComplete(): Promise<void> {
         return new Promise((resolve, reject) => {
 
             const timeout = setTimeout(() => {
                 clearInterval(interval);
 
-                if (this.wip.hasFailedOperations()) {
-                    const error = new Error(this.wip.descriptionOfFailedOperations());
-
-                    this.wip.resetFailedOperations();
-
-                    return reject(error);
-                }
-
-                if (this.wip.hasActiveOperations()) {
-                    const error = new Error(this.wip.descriptionOfTimedOutOperations());
-
-                    return reject(error);
-                }
-
-                // "else" can't happen because this case is covered by the interval check below
-
+                return resolve();
             }, this.cueTimeout.inMilliseconds());
 
             const interval = setInterval(() => {
@@ -54,21 +42,29 @@ export class StageManager {
                     clearTimeout(timeout);
                     clearInterval(interval);
 
-                    if (this.wip.hasFailedOperations()) {
-
-                        const error = new Error(this.wip.descriptionOfFailedOperations());
-
-                        this.wip.resetFailedOperations();
-
-                        return reject(error);
-                    }
-
                     return resolve();
                 }
             }, 10);
         });
     }
 
+    async waitForNextCue(): Promise<void> {
+
+        await this.waitForAsyncOperationsToComplete();
+
+        if (this.wip.hasFailedOperations()) {
+            const error = new Error(this.wip.descriptionOfFailedOperations());
+
+            this.wip.resetFailedOperations();
+
+            throw error;
+        }
+
+        if (this.wip.hasActiveOperations()) {
+            throw new Error(this.wip.descriptionOfTimedOutOperations());
+        }
+    }
+
     currentTime(): Timestamp {
         return this.clock.now();
     }
@@ -90,8 +86,9 @@ class WIP {
     recordIfAsync(event: DomainEvent): void {
         if (event instanceof AsyncOperationAttempted) {
             this.set(event.correlationId, {
-                taskDescription:    event.taskDescription,
-                startedAt:          event.timestamp,
+                name:           event.name,
+                description:    event.description,
+                startedAt:      event.timestamp,
             });
         }
 
@@ -103,10 +100,11 @@ class WIP {
             const original = this.get(event.correlationId);
 
             this.failedOperations.push({
-                taskDescription:    original.taskDescription,
-                startedAt:          original.startedAt,
-                duration:           event.timestamp.diff(original.startedAt),
-                error:              event.error,
+                name:           original.name,
+                description:    original.description,
+                startedAt:      original.startedAt,
+                duration:       event.timestamp.diff(original.startedAt),
+                error:          event.error,
             });
 
             this.delete(event.correlationId)
@@ -129,7 +127,7 @@ class WIP {
         const now = this.clock.now();
 
         return this.activeOperations().reduce(
-            (acc, op) => acc.concat(`${ now.diff(op.startedAt) } - ${ op.taskDescription.value }`),
+            (acc, op) => acc.concat(`${ now.diff(op.startedAt) } - [${ op.name.value }] ${ op.description.value }`),
             [`${ this.header(this.wip.size) } within a ${ this.cueTimeout } cue timeout:`],
         ).join('\n');
     }
@@ -138,7 +136,7 @@ class WIP {
         let message = `${ this.header(this.failedOperations.length) }:\n`;
 
         this.failedOperations.forEach((op: FailedAsyncOperationDetails) => {
-            message += `${ op.taskDescription.value } - ${ op.error.stack }\n---\n`;
+            message += `[${ op.name.value }] ${ op.description.value } - ${ op.error.stack }\n---\n`;
         });
 
         return message;
@@ -185,18 +183,20 @@ class WIP {
  * @package
  */
 interface AsyncOperationDetails {
-    taskDescription:    Description;
-    startedAt:          Timestamp;
-    duration?:          Duration;
-    error?:             Error;
+    name:           Name;
+    description:    Description;
+    startedAt:      Timestamp;
+    duration?:      Duration;
+    error?:         Error;
 }
 
 /**
  * @package
  */
 interface FailedAsyncOperationDetails {
-    taskDescription:    Description;
-    startedAt:          Timestamp;
-    duration:           Duration;
-    error:              Error;
+    name:           Name;
+    description:    Description;
+    startedAt:      Timestamp;
+    duration:       Duration;
+    error:          Error;
 }

package/src/stage/crew/artifact-archiver/ArtifactArchiver.ts

@@ -1,5 +1,5 @@
 import { WriteFileOptions } from 'fs';
-import { ensure, isGreaterThan, property } from 'tiny-types';
+import { ensure, isDefined, isGreaterThan, isString, property } from 'tiny-types';
 
 import {
     ActivityRelatedArtifactArchived,
@@ -18,49 +18,73 @@ import { StageCrewMember } from '../../StageCrewMember';
 import { Hash } from './Hash';
 
 /**
- * @desc
- *  Stores any {@link Artifact}s emitted via {@link ArtifactGenerated} events on the {@link FileSystem}
+ * Stores any {@apilink Artifact|artifacts} emitted via {@apilink ArtifactGenerated} events on the {@apilink FileSystem}
  *
- * @example <caption>Registering ArtifactArchiver programmatically</caption>
- *  import { configure, StreamReporter } from '@serenity-js/core';
+ * ## Registering `ArtifactArchiver` programmatically
  *
- *  configure({
- *      crew: [
- *          ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
- *      ],
- *  });
+ * ```ts
+ * import { ArtifactArchiver, configure } from '@serenity-js/core'
  *
- * @example <caption>Registering ArtifactArchiver using Protractor configuration</caption>
- *  // protractor.conf.js
- *  const { ArtifactArchiver } = require('@serenity-js/core');
+ * configure({
+ *   crew: [
+ *     ArtifactArchiver.storingArtifactsAt(`/target/site/serenity`),
+ *   ]
+ *   // other Serenity/JS config
+ * })
+ * ```
  *
- *  exports.config = {
- *    framework:     'custom',
- *    frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
+ * ## Registering `ArtifactArchiver` using Protractor configuration
  *
- *    serenity: {
- *      crew: [
- *        ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
- *      ],
- *      // other Serenity/JS config
- *    },
+ * ```js
+ * // protractor.conf.js
+ * const { ArtifactArchiver } = require('@serenity-js/core')
  *
- *    // other Protractor config
- *  };
+ * exports.config = {
+ *   framework:     'custom',
+ *   frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
  *
- * @public
- * @implements {StageCrewMember}
+ *   serenity: {
+ *     crew: [
+ *       ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
+ *     ],
+ *     // other Serenity/JS config
+ *   },
+ *   // other Protractor config
+ * };
+ * ```
+ *
+ * ## Registering `ArtifactArchiver` using WebdriverIO configuration
+ *
+ * ```ts
+ * // wdio.conf.js
+ * import { ArtifactArchiver } from '@serenity-js/core'
+ * import { WebdriverIOConfig } from '@serenity-js/webdriverio'
+ *
+ * export const config: WebdriverIOConfig = {
+ *
+ *     framework: '@serenity-js/webdriverio',
+ *
+ *     serenity: {
+ *         crew: [
+ *             ArtifactArchiver.storingArtifactsAt(`/target/site/serenity`),
+ *         ]
+ *         // other Serenity/JS config
+ *     },
+ *     // other WebdriverIO config
+ * }
+ * ```
+ *
+ * [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
+ *
+ * @group Stage
  */
 export class ArtifactArchiver implements StageCrewMember {
 
     /**
-     * @desc
-     *  Instantiates an `ArtifactArchiver` storing artifacts in a given `destination`.
-     *  The `destination` directory will be created automatically and recursively if it doesn't exist.
+     * Instantiates an `ArtifactArchiver` storing artifacts in a given `destination`.
+     * The `destination` directory will be created automatically and recursively if it doesn't exist.
      *
-     * @param {string[]} destination
-     *
-     * @returns {StageCrewMember}
+     * @param destination
      */
     static storingArtifactsAt(...destination: string[]): StageCrewMember {
         ensure('Path to destination directory', destination, property('length', isGreaterThan(0)));
@@ -70,41 +94,43 @@ export class ArtifactArchiver implements StageCrewMember {
         return new ArtifactArchiver(new FileSystem(pathToDestination));
     }
 
+    /**
+     * Instantiates an `ArtifactArchiver` storing artifacts in a given `outputDirectory`.
+     * The `outputDirectory` will be created automatically and recursively if it doesn't exist.
+     *
+     * @param config
+     */
+    static fromJSON(config: { outputDirectory: string }): StageCrewMember {
+        const outputDirectory = ensure('outputDirectory', config.outputDirectory, isDefined(), isString());
+
+        return new ArtifactArchiver(new FileSystem(Path.from(outputDirectory)));
+    }
+
     /**
      * @param {FileSystem} fileSystem
      * @param {Stage} [stage]
-     *  The stage this {@link StageCrewMember} should be assigned to
+     *  The stage this {@apilink StageCrewMember} should be assigned to
      */
     constructor(
         private readonly fileSystem: FileSystem,
-        private readonly stage?: Stage,
+        private stage?: Stage,
     ) {
     }
 
-    /**
-     * @desc
-     *  Creates a new instance of this {@link StageCrewMember} and assigns it to a given {@link Stage}.
-     *
-     * @see {@link StageCrewMember}
-     *
-     * @param {Stage} stage - An instance of a {@link Stage} this {@link StageCrewMember} will be assigned to
-     * @returns {StageCrewMember} - A new instance of this {@link StageCrewMember}
-     */
     assignedTo(stage: Stage): StageCrewMember {
-        return new ArtifactArchiver(this.fileSystem, stage);
+        this.stage = stage;
+        return this;
     }
 
     /**
-     * @desc
-     *  Handles {@link DomainEvent} objects emitted by the {@link StageManager}.
+     * Handles {@apilink DomainEvent} objects emitted by the {@apilink StageManager}.
      *
-     * @see {@link StageCrewMember}
+     * @see {@apilink StageCrewMember}
      *
      * @listens {ArtifactGenerated}
      * @emits {ArtifactArchived}
      *
-     * @param {DomainEvent} event
-     * @returns {void}
+     * @param event
      */
     notifyOf(event: DomainEvent): void {
 
@@ -152,21 +178,23 @@ export class ArtifactArchiver implements StageCrewMember {
         const id = CorrelationId.create();
 
         this.stage.announce(new AsyncOperationAttempted(
-            new Description(`[${ this.constructor.name }] Saving '${ relativePath.value }'...`),
+            new Name(this.constructor.name),
+            new Description(`Saving '${ relativePath.value }'...`),
             id,
+            this.stage.currentTime(),
         ));
 
         this.fileSystem.store(relativePath, contents, encoding)
-            .then(absolutePath => {
+            .then(absolutePath_ => {
                 announce(relativePath);
 
                 this.stage.announce(new AsyncOperationCompleted(
-                    new Description(`[${ this.constructor.name }] Saved '${ absolutePath.value }'`),
                     id,
+                    this.stage.currentTime(),
                 ));
             })
             .catch(error => {
-                this.stage.announce(new AsyncOperationFailed(error, id));
+                this.stage.announce(new AsyncOperationFailed(error, id, this.stage.currentTime()));
             });
     }
 

package/src/stage/crew/stream-reporter/StreamReporter.ts

@@ -5,48 +5,79 @@ import { Stage } from '../../Stage';
 import { StageCrewMember } from '../../StageCrewMember';
 
 /**
- * @desc
- *  Serialises all the {@link DomainEvent} objects it receives and streams
- *  them as [ndjson](http://ndjson.org/) to the output stream.
- *
- * @example <caption>Writing DomainEvents to standard output</caption>
- *  import { configure, StreamReporter } from '@serenity-js/core';
- *
- *  configure({
- *      crew: [
- *          new StreamReporter(process.stdout)
- *      ],
- *  });
- *
- * @example <caption>Writing DomainEvents to a file</caption>
- *  import { configure, StreamReporter } from '@serenity-js/core';
- *  import fs = require('fs');
- *
- *  configure({
- *      crew: [
- *          new StreamReporter(fs.createWriteStream('./events.ndjson'))
- *      ],
- *  });
- *
- * @example <caption>Registering StreamReporter using Protractor configuration</caption>
- *  // protractor.conf.js
- *  const { StreamReporter } = require('@serenity-js/core');
- *
- *  exports.config = {
- *    framework:     'custom',
- *    frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
- *
- *    serenity: {
- *      crew: [
- *        new StreamReporter(process.stdout),
- *      ],
- *      // other Serenity/JS config
- *    },
- *
- *    // other Protractor config
- *  };
- *
- * @implements {StageCrewMember}
+ * Serialises all the {@apilink DomainEvent} objects it receives and streams
+ * them as [ndjson](http://ndjson.org/) to the output stream.
+ *
+ * Useful when debugging issues related to custom Serenity/JS test runner adapters.
+ *
+ * ## Registering `StreamReporter` programmatically
+ *
+ * ```ts
+ * import { configure, StreamReporter } from '@serenity-js/core'
+ *
+ * configure({
+ *   crew: [
+ *     new StreamReporter(process.stdout)
+ *   ],
+ * })
+ * ```
+ *
+ * ## Writing `DomainEvents` to a file
+ *
+ * ```ts
+ * import { configure, StreamReporter } from '@serenity-js/core'
+ * import fs = require('fs')
+ *
+ * configure({
+ *   crew: [
+ *     new StreamReporter(fs.createWriteStream('./events.ndjson'))
+ *   ],
+ * })
+ * ```
+ *
+ * ## Registering `StreamReporter` using Protractor configuration
+ *
+ * ```js
+ * // protractor.conf.js
+ * const { StreamReporter } = require('@serenity-js/core');
+ *
+ * exports.config = {
+ *   framework:     'custom',
+ *   frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
+ *
+ *   serenity: {
+ *     crew: [
+ *       new StreamReporter(process.stdout),
+ *     ],
+ *     // other Serenity/JS config
+ *   },
+ *   // other Protractor config
+ * };
+ * ```
+ *
+ * ## Registering `StreamReporter` using WebdriverIO configuration
+ *
+ * ```ts
+ * // wdio.conf.js
+ * import { StreamReporter } from '@serenity-js/core'
+ * import { WebdriverIOConfig } from '@serenity-js/webdriverio'
+ *
+ * export const config: WebdriverIOConfig = {
+ *
+ *     framework: '@serenity-js/webdriverio',
+ *
+ *     serenity: {
+ *         crew: [
+ *           new StreamReporter(process.stdout),
+ *         ]
+ *         // other Serenity/JS config
+ *     },
+ *   },
+ *   // other WebdriverIO config
+ * }
+ * ```
+ *
+ * @group Stage
  */
 export class StreamReporter implements StageCrewMember {
 
@@ -55,7 +86,7 @@ export class StreamReporter implements StageCrewMember {
      *  A Writable stream that should receive the output
      *
      * @param {Stage} [stage]
-     *  The stage this {@link StageCrewMember} should be assigned to
+     *  The stage this {@apilink StageCrewMember} should be assigned to
      */
     constructor(
         private readonly output: Writable = process.stdout,
@@ -64,28 +95,24 @@ export class StreamReporter implements StageCrewMember {
     }
 
     /**
-     * @desc
-     *  Creates a new instance of this {@link StageCrewMember} and assigns it to a given {@link Stage}.
+     * Creates a new instance of this {@apilink StageCrewMember} and assigns it to a given {@apilink Stage}.
      *
-     * @see {@link StageCrewMember}
+     * @param stage
+     *  An instance of a {@apilink Stage} this {@apilink StageCrewMember} will be assigned to
      *
-     * @param {Stage} stage - An instance of a {@link Stage} this {@link StageCrewMember} will be assigned to
-     * @returns {StageCrewMember} - A new instance of this {@link StageCrewMember}
+     * @returns {StageCrewMember}
+     *  A new instance of this {@apilink StageCrewMember}
      */
     assignedTo(stage: Stage): StageCrewMember {
         return new StreamReporter(this.output, stage);
     }
 
     /**
-     * @desc
-     *  Handles {@link DomainEvent} objects emitted by the {@link StageManager}.
-     *
-     * @see {@link StageCrewMember}
+     * Handles {@apilink DomainEvent} objects emitted by the {@apilink StageManager}.
      *
      * @listens {DomainEvent}
      *
-     * @param {DomainEvent} event
-     * @returns {void}
+     * @param event
      */
     notifyOf(event: DomainEvent): void {
         this.output.write(

package/src/stage/index.ts

@@ -1,7 +1,7 @@
 export * from './Cast';
-export * from './Clock';
 export * from './crew';
 export * from './ListensToDomainEvents';
+export * from './queues';
 export * from './Stage';
 export * from './StageCrewMember';
 export * from './StageCrewMemberBuilder';

package/src/stage/queues/DomainEventQueue.ts

@@ -0,0 +1,41 @@
+import { ensure, Predicate } from 'tiny-types';
+
+import { DomainEvent } from '../../events';
+import { CorrelationId } from '../../model';
+
+/**
+ * @group Stage
+ */
+export class DomainEventQueue {
+    private readonly queue: Array<DomainEvent & { sceneId: CorrelationId }>;
+
+    constructor(...items: Array<DomainEvent & { sceneId: CorrelationId }>) {
+        this.queue = items;
+    }
+
+    get sceneId(): CorrelationId {
+        ensure('queue', this.queue, isNotEmpty());
+
+        return this.queue[0].sceneId;
+    }
+
+    first(): DomainEvent & { sceneId: CorrelationId } {
+        return this.queue[0];
+    }
+
+    enqueue(event: DomainEvent & { sceneId: CorrelationId }): void {
+        this.queue.push(event);
+    }
+
+    drain(): Array<DomainEvent & { sceneId: CorrelationId }> {
+        return this.queue.splice(0);
+    }
+
+    reduce<U>(fn: (previousValue: U, currentValue: DomainEvent & { sceneId: CorrelationId }, currentIndex: number) => U, initialValue: U): U {
+        return Array.from(this.queue).reduce(fn, initialValue);
+    }
+}
+
+function isNotEmpty<T>(): Predicate<T[]> {
+    return Predicate.to(`not be empty`, (value: T[]) => Array.isArray(value) && value.length > 0);
+}

package/src/stage/queues/DomainEventQueues.ts

@@ -0,0 +1,88 @@
+import { LogicError } from '../../errors';
+import { DomainEvent, SceneSequenceDetected, SceneStarts } from '../../events';
+import { d } from '../../io/format';
+import { CorrelationId, ScenarioDetails } from '../../model';
+import { DomainEventQueue } from './DomainEventQueue';
+
+/**
+ * @group Stage
+ */
+export class DomainEventQueues {
+
+    private readonly queueIndex: Array<{ sceneId: CorrelationId, details: ScenarioDetails, queueId: symbol }> = [];
+
+    private readonly queues: Map<symbol, DomainEventQueue> = new Map();
+    private readonly holdingBay = new DomainEventQueue();
+
+    enqueue(event: DomainEvent & { sceneId: CorrelationId }): void {
+
+        if (this.shouldStartNewQueueFor(event)) {
+            this.queues.set(this.queueIdFor(event), new DomainEventQueue(event, ...this.holdingBay.drain()));
+        } else if (this.hasNoQueuesReadyFor(event)) {
+            this.holdingBay.enqueue(event);
+        } else {
+            this.queues.get(this.queueIdFor(event)).enqueue(event);
+        }
+    }
+
+    forEach(callback: (queue: DomainEventQueue) => void): void {
+        this.queues.forEach(callback);
+    }
+
+    drainQueueFor(sceneId: CorrelationId): Array<DomainEvent & { sceneId: CorrelationId }> {
+        for (const [key, queue] of this.queues) {
+            if (sceneId.equals(queue.sceneId)) {
+                const events = queue.drain();
+                this.queues.delete(key)
+
+                return events;
+            }
+        }
+        throw new LogicError(d`No domain event queue found for scene ${ sceneId }`);
+    }
+
+    private shouldStartNewQueueFor(event: DomainEvent & { sceneId: CorrelationId }) {
+        return (event instanceof SceneSequenceDetected || event instanceof SceneStarts)
+            && !this.queues.has(this.queueIdFor(event));
+    }
+
+    private hasNoQueuesReadyFor(event: DomainEvent & { sceneId: CorrelationId }) {
+        return this.queues.size === 0
+            || !this.queues.has(this.queueIdFor(event));
+    }
+
+    private queueIdFor(event: DomainEvent & { sceneId: CorrelationId, details?: ScenarioDetails }): symbol {
+        const exactMatch = this.queueIndex.find(entry => entry.sceneId.equals(event.sceneId));
+
+        if (exactMatch) {
+            return exactMatch.queueId;
+        }
+
+        if (! (event instanceof SceneStarts)) {
+            const sameScenarioMatch = this.queueIndex.find(entry =>
+                entry.details &&
+                entry.details.equals(event.details),
+            );
+
+            if (sameScenarioMatch) {
+                this.queueIndex.push({
+                    sceneId: event.sceneId,
+                    details: event.details || sameScenarioMatch.details,
+                    queueId: sameScenarioMatch.queueId,
+                });
+
+                return sameScenarioMatch.queueId;
+            }
+        }
+
+        const newQueueId = Symbol();
+
+        this.queueIndex.push({
+            sceneId: event.sceneId,
+            details: event.details,
+            queueId: newQueueId,
+        });
+
+        return newQueueId;
+    }
+}

package/src/stage/queues/index.ts

@@ -0,0 +1,2 @@
+export * from './DomainEventQueue';
+export * from './DomainEventQueues';

package/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "lib",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}