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

package/src/errors/model/ConfigurationError.ts

@@ -0,0 +1,31 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that a test framework or test suite configuration error occurred.
+ *
+ * @group Errors
+ */
+export class ConfigurationError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): ConfigurationError {
+        const error = new ConfigurationError(
+            serialised.message as string,
+            ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+        );
+
+        error.stack = serialised.stack as string;
+
+        return error;
+    }
+
+    /**
+     * @param message - Human-readable description of the error
+     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     */
+    constructor(message: string, cause?: Error) {
+        super(ConfigurationError, message, cause);
+    }
+}

package/src/errors/model/ImplementationPendingError.ts

@@ -0,0 +1,52 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that the {@apilink Actor} attempted to perform
+ * a {@apilink Task} or {@apilink Interaction} that hasn't been implemented yet.
+ *
+ * ## A pending Task
+ *
+ * ```ts
+ * import { Task } from '@serenity-js/core'
+ *
+ * // A pending Task is one that encapsulates no other activities
+ * const Authenticate = () =>
+ *   Task.where(`#actor authenticates with the service up a test database` )
+ * ```
+ *
+ * ## A pending Interaction
+ *
+ * ```ts
+ * import { Interaction } from '@serenity-js/core'
+ *
+ * // A pending Interaction is one that doesn't perform any action
+ * const DoubleClick = () =>
+ *   Interaction.where(`#actor double-clicks`)
+ * ```
+ *
+ * @group Errors
+ */
+export class ImplementationPendingError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): ImplementationPendingError {
+        const error = new ImplementationPendingError(
+            serialised.message as string,
+            ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+        );
+
+        error.stack = serialised.stack as string;
+
+        return error;
+    }
+
+    /**
+     * @param {string} message - Human-readable description of the error
+     * @param {Error} [cause] - The root cause of this {@apilink RuntimeError}, if any
+     */
+    constructor(message: string, cause?: Error) {
+        super(ImplementationPendingError, message, cause);
+    }
+}

package/src/errors/model/ListItemNotFoundError.ts

@@ -0,0 +1,35 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that an {@apilink Interaction}, a {@apilink Task} or a test scenario
+ * can't be executed due to no items are found in a list.
+ *
+ * For example, it's not possible to get the first() or the last() item of a list
+ * if the list is empty.
+ *
+ * @group Errors
+ */
+export class ListItemNotFoundError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): ListItemNotFoundError {
+        const error = new ListItemNotFoundError(
+            serialised.message as string,
+            ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+        );
+
+        error.stack = serialised.stack as string;
+
+        return error;
+    }
+
+    /**
+     * @param message - Human-readable description of the error
+     * @param [cause] - The root cause of this {@apilink ListItemNotFoundError}, if any
+     */
+    constructor(message: string, cause?: Error) {
+        super(ListItemNotFoundError, message, cause);
+    }
+}

package/src/errors/model/LogicError.ts

@@ -0,0 +1,35 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that an {@apilink Interaction}, a {@apilink Task} or a test scenario
+ * can't be executed due to a logical error.
+ *
+ * For example, it's not possible to assert on the last HTTP Response if the request
+ * hasn't been performed yet.
+ *
+ * @group Errors
+ */
+export class LogicError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): LogicError {
+        const error = new LogicError(
+            serialised.message as string,
+            ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+        );
+
+        error.stack = serialised.stack as string;
+
+        return error;
+    }
+
+    /**
+     * @param message - Human-readable description of the error
+     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     */
+    constructor(message: string, cause?: Error) {
+        super(LogicError, message, cause);
+    }
+}

package/src/errors/model/OperationInterruptedError.ts

@@ -0,0 +1,38 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that a {@apilink Scheduler|scheduled operation}
+ * has been stopped before it was completed.
+ *
+ * @group Errors
+ */
+export class OperationInterruptedError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): OperationInterruptedError {
+        const error = new OperationInterruptedError(
+            serialised.message as string,
+            ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+        );
+
+        error.stack = serialised.stack as string;
+
+        return error;
+    }
+
+    /**
+     * @param message
+     *  Human-readable description of the error
+     *
+     * @param [cause]
+     *  The root cause of this {@apilink RuntimeError}, if any
+     */
+    constructor(
+        message: string,
+        cause?: Error
+    ) {
+        super(OperationInterruptedError, message, cause);
+    }
+}

package/src/errors/model/RuntimeError.ts

@@ -0,0 +1,101 @@
+import { TinyType } from 'tiny-types';
+
+/**
+ * Base class for custom errors that may occur during execution of a test scenario.
+ *
+ * ## Defining a custom error
+ *
+ * ```ts
+ * import { RuntimeError } from '@serenity-js/core'
+ *
+ * export class CustomError extends RuntimeError {
+ *   constructor(message: string, cause?: Error) {
+ *       super(CustomError, message, cause);
+ *   }
+ * }
+ * ```
+ *
+ * ## Wrapping a sync error
+ *
+ * ```ts
+ * try {
+ *     operationThatMightThrowAnError();
+ * } catch(error) {
+ *     // catch and re-throw
+ *     throw new CustomError('operationThatMightThrowAnError has failed', error);
+ * }
+ * ```
+ *
+ * ## Wrapping an async error
+ *
+ * ```ts
+ * operationThatMightRejectAPromise()
+ *   .catch(error => {
+ *     // catch and re-throw
+ *     throw new CustomError('operationThatMightThrowAnError has failed', error)
+ *   })
+ * ```
+ *
+ * ## Registering a custom error with {@apilink ErrorSerialiser}
+ *
+ * ```ts
+ * import { RuntimeError } from '@serenity-js/core'
+ * import { ErrorSerialiser } from '@serenity-js/core/lib/io'
+ *
+ * export class CustomError extends RuntimeError {
+ *
+ *    static fromJSON(serialised: JSONObject): CustomError {
+ *         const error = new CustomError(
+ *             serialised.message as string,
+ *             ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+ *         );
+ *
+ *         error.stack = serialised.stack as string;
+ *
+ *         return error;
+ *     }
+ *
+ *   constructor(message: string, cause?: Error) {
+ *       super(CustomError, message, cause);
+ *   }
+ * }
+ *
+ * ErrorSerialiser.registerErrorTypes(CustomError)
+ * ```
+ *
+ * @group Errors
+ */
+export abstract class RuntimeError extends Error {
+
+    /**
+     * @param type - Constructor function used to instantiate a subclass of a RuntimeError
+     * @param message - Human-readable description of the error
+     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     */
+    protected constructor(
+        type: new (...args: any[]) => RuntimeError,
+        message: string,
+        public readonly cause?: Error,
+    ) {
+        super(message);
+        Object.setPrototypeOf(this, type.prototype);
+        this.name = this.constructor.name;
+
+        Error.captureStackTrace(this, type);
+
+        if (cause) {
+            this.stack = `${ this.stack }\nCaused by: ${ cause.stack }`;
+        }
+    }
+
+    /**
+     * Human-readable description of the error
+     */
+    toString(): string {
+        return `${ this.constructor.name }: ${ this.message }`;
+    }
+
+    toJSON(): object {
+        return TinyType.prototype.toJSON.apply(this)
+    }
+}

package/src/errors/model/TestCompromisedError.ts

@@ -0,0 +1,46 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that the test can't be performed due to an issue with a downstream dependency.
+ * For example, it makes no sense to run a full-stack integration test if we already know that
+ * the database server is down.
+ *
+ * ## Throwing a TestCompromisedError from a custom Interaction
+ *
+ * ```ts
+ * import { Interaction } from '@serenity-js/core';
+ *
+ * const SetUpTestDatabase = () =>
+ *   Interaction.where(`#actor sets up a test database`, actor => {
+ *     return SomeCustomDatabaseSpecificAbility.as(actor).setUpTestDatabase().catch(error => {
+ *       throw new TestCompromisedError('Could not set up the test database', error)
+ *     })
+ * })
+ * ```
+ *
+ * @group Errors
+ */
+export class TestCompromisedError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): TestCompromisedError {
+        const error = new TestCompromisedError(
+            serialised.message as string,
+            ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+        );
+
+        error.stack = serialised.stack as string;
+
+        return error;
+    }
+
+    /**
+     * @param message - Human-readable description of the error
+     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     */
+    constructor(message: string, cause?: Error) {
+        super(TestCompromisedError, message, cause);
+    }
+}

package/src/errors/model/TimeoutExpiredError.ts

@@ -0,0 +1,38 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that an {@apilink Interaction}, a {@apilink Task} or a test scenario
+ * took longer to execute than the expected timeout.
+ *
+ * @group Errors
+ */
+export class TimeoutExpiredError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): TimeoutExpiredError {
+        const error = new TimeoutExpiredError(
+            serialised.message as string,
+            ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+        );
+
+        error.stack = serialised.stack as string;
+
+        return error;
+    }
+
+    /**
+     * @param message
+     *  Human-readable description of the error
+     *
+     * @param [cause]
+     *  The root cause of this {@apilink RuntimeError}, if any
+     */
+    constructor(
+        message: string,
+        cause?: Error
+    ) {
+        super(TimeoutExpiredError, message, cause);
+    }
+}

package/src/errors/model/UnknownError.ts

@@ -0,0 +1,31 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that an unknown error has occurred.
+ *
+ * @group Errors
+ */
+export class UnknownError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): UnknownError {
+        const error = new UnknownError(
+            serialised.message as string,
+            ErrorSerialiser.deserialise(serialised.cause as string | undefined),
+        );
+
+        error.stack = serialised.stack as string;
+
+        return error;
+    }
+
+    /**
+     * @param message - Human-readable description of the error
+     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     */
+    constructor(message: string, cause?: Error) {
+        super(UnknownError, message, cause);
+    }
+}

package/src/errors/model/index.ts

@@ -0,0 +1,10 @@
+export * from './AssertionError';
+export * from './ConfigurationError';
+export * from './ImplementationPendingError';
+export * from './ListItemNotFoundError';
+export * from './LogicError';
+export * from './OperationInterruptedError';
+export * from './RuntimeError';
+export * from './TestCompromisedError';
+export * from './TimeoutExpiredError';
+export * from './UnknownError';

package/src/events/ActivityFinished.ts

@@ -1,14 +1,13 @@
 import { ensure, isDefined } from 'tiny-types';
 
-import { ActivityDetails, CorrelationId, Outcome, Timestamp } from '../model';
+import { ActivityDetails, CorrelationId, Outcome } from '../model';
+import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
 /**
- * @desc
- *  Emitted when an {@link Activity} is finished.
+ * Emitted when an {@apilink Activity} is finished.
  *
- * @abstract
- * @extends {DomainEvent}
+ * @group Events
  */
 export abstract class ActivityFinished extends DomainEvent {
     constructor(

package/src/events/ActivityRelatedArtifactArchived.ts

@@ -1,12 +1,17 @@
 import { ensure, isDefined, JSONObject } from 'tiny-types';
 
 import { Path } from '../io';
-import { Artifact, ArtifactType, CorrelationId, Name, Timestamp } from '../model';
+import { Artifact, ArtifactType, CorrelationId, Name } from '../model';
+import { Timestamp } from '../screenplay';
 import { ArtifactArchived } from './ArtifactArchived';
 
 // todo: there should be two types of events here:
 //  - ActivityArtifactGenerated
 //  - SceneArtifactGenerated
+
+/**
+ * @group Events
+ */
 export class ActivityRelatedArtifactArchived extends ArtifactArchived {
     static fromJSON(o: JSONObject): ActivityRelatedArtifactArchived {
         return new ActivityRelatedArtifactArchived(

package/src/events/ActivityRelatedArtifactGenerated.ts

@@ -1,8 +1,12 @@
 import { ensure, isDefined, JSONObject } from 'tiny-types';
 
-import { Artifact, CorrelationId, Name, SerialisedArtifact, Timestamp } from '../model';
+import { Artifact, CorrelationId, Name, SerialisedArtifact } from '../model';
+import { Timestamp } from '../screenplay';
 import { ArtifactGenerated } from './ArtifactGenerated';
 
+/**
+ * @group Events
+ */
 export class ActivityRelatedArtifactGenerated extends ArtifactGenerated {
     static fromJSON(o: JSONObject): ActivityRelatedArtifactGenerated {
         return new ActivityRelatedArtifactGenerated(

package/src/events/ActivityStarts.ts

@@ -1,14 +1,13 @@
 import { ensure, isDefined } from 'tiny-types';
 
-import { ActivityDetails, CorrelationId, Timestamp } from '../model';
+import { ActivityDetails, CorrelationId } from '../model';
+import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
 /**
- * @desc
- *  Emitted when an {@link Activity} starts.
+ * Emitted when an {@apilink Activity} starts.
  *
- * @abstract
- * @extends {DomainEvent}
+ * @group Events
  */
 export abstract class ActivityStarts extends DomainEvent {
     constructor(

package/src/events/ArtifactArchived.ts

@@ -1,9 +1,13 @@
 import { ensure, isDefined, JSONObject } from 'tiny-types';
 
 import { Path } from '../io';
-import { Artifact, ArtifactType, CorrelationId, Name, Timestamp } from '../model';
+import { Artifact, ArtifactType, CorrelationId, Name } from '../model';
+import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
+/**
+ * @group Events
+ */
 export class ArtifactArchived extends DomainEvent {
     static fromJSON(o: JSONObject): ArtifactArchived {
         return new ArtifactArchived(

package/src/events/ArtifactGenerated.ts

@@ -1,8 +1,12 @@
 import { ensure, isDefined, JSONObject } from 'tiny-types';
 
-import { Artifact, CorrelationId, Name, SerialisedArtifact, Timestamp } from '../model';
+import { Artifact, CorrelationId, Name, SerialisedArtifact } from '../model';
+import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
+/**
+ * @group Events
+ */
 export class ArtifactGenerated extends DomainEvent {
     static fromJSON(o: JSONObject): ArtifactGenerated {
         return new ArtifactGenerated(

package/src/events/AsyncOperationAborted.ts

@@ -0,0 +1,28 @@
+import { ensure, isDefined, JSONObject } from 'tiny-types';
+
+import { CorrelationId, Description } from '../model';
+import { Timestamp } from '../screenplay';
+import { DomainEvent } from './DomainEvent';
+
+/**
+ * @group Events
+ */
+export class AsyncOperationAborted extends DomainEvent {
+    static fromJSON(o: JSONObject): AsyncOperationAborted {
+        return new AsyncOperationAborted(
+            Description.fromJSON(o.description as string),
+            CorrelationId.fromJSON(o.correlationId as string),
+            Timestamp.fromJSON(o.timestamp as string),
+        );
+    }
+
+    constructor(
+        public readonly description: Description,
+        public readonly correlationId: CorrelationId,
+        timestamp?: Timestamp,
+    ) {
+        super(timestamp);
+        ensure('description', description, isDefined());
+        ensure('correlationId', correlationId, isDefined());
+    }
+}

package/src/events/AsyncOperationAttempted.ts

@@ -1,24 +1,31 @@
 import { ensure, isDefined, JSONObject } from 'tiny-types';
 
-import { CorrelationId, Description, Timestamp } from '../model';
+import { CorrelationId, Description, Name } from '../model';
+import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
+/**
+ * @group Events
+ */
 export class AsyncOperationAttempted extends DomainEvent {
     static fromJSON(o: JSONObject): AsyncOperationAttempted {
         return new AsyncOperationAttempted(
-            Description.fromJSON(o.taskDescription as string),
+            Name.fromJSON(o.name as string),
+            Description.fromJSON(o.description as string),
             CorrelationId.fromJSON(o.correlationId as string),
             Timestamp.fromJSON(o.timestamp as string),
         );
     }
 
     constructor(
-        public readonly taskDescription: Description,
+        public readonly name: Name,
+        public readonly description: Description,
         public readonly correlationId: CorrelationId,
         timestamp?: Timestamp,
     ) {
         super(timestamp);
-        ensure('taskDescription', taskDescription, isDefined());
+        ensure('name', name, isDefined());
+        ensure('description', description, isDefined());
         ensure('correlationId', correlationId, isDefined());
     }
 }

package/src/events/AsyncOperationCompleted.ts

@@ -1,24 +1,25 @@
 import { ensure, isDefined, JSONObject } from 'tiny-types';
 
-import { CorrelationId, Description, Timestamp } from '../model';
+import { CorrelationId } from '../model';
+import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
+/**
+ * @group Events
+ */
 export class AsyncOperationCompleted extends DomainEvent {
     static fromJSON(o: JSONObject): AsyncOperationCompleted {
         return new AsyncOperationCompleted(
-            Description.fromJSON(o.taskDescription as string),
             CorrelationId.fromJSON(o.correlationId as string),
             Timestamp.fromJSON(o.timestamp as string),
         );
     }
 
     constructor(
-        public readonly taskDescription: Description,
         public readonly correlationId: CorrelationId,
         timestamp?: Timestamp,
     ) {
         super(timestamp);
-        ensure('taskDescription', taskDescription, isDefined());
         ensure('correlationId', correlationId, isDefined());
     }
 }

package/src/events/AsyncOperationFailed.ts

@@ -1,9 +1,13 @@
 import { ensure, isDefined, JSONObject } from 'tiny-types';
 
-import { ErrorSerialiser } from '../io';
-import { CorrelationId, Timestamp } from '../model';
+import { ErrorSerialiser } from '../errors';
+import { CorrelationId } from '../model';
+import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
+/**
+ * @group Events
+ */
 export class AsyncOperationFailed extends DomainEvent {
     static fromJSON(o: JSONObject): AsyncOperationFailed {
         return new AsyncOperationFailed(

package/src/events/BusinessRuleDetected.ts

@@ -1,14 +1,14 @@
 import { ensure, isDefined, JSONObject } from 'tiny-types';
 
-import { BusinessRule, CorrelationId, ScenarioDetails, Timestamp } from '../model';
+import { BusinessRule, CorrelationId, ScenarioDetails } from '../model';
+import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
 /**
- * @desc
- *  Emitted by [@serenity-js/cucumber](https://serenity-js.org/modules/cucumber)
- *  when a [business rule](https://cucumber.io/docs/gherkin/reference/#rule) is detected.
+ * Emitted by [@serenity-js/cucumber](/api/cucumber)
+ * when a [business rule](https://cucumber.io/docs/gherkin/reference/#rule) is detected.
  *
- * @extends {DomainEvent}
+ * @group Events
  */
 export class BusinessRuleDetected extends DomainEvent {
     public static fromJSON(o: JSONObject): BusinessRuleDetected {