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

package/src/errors/ErrorFactory.ts

@@ -0,0 +1,329 @@
+import { ArrayChange, Change, diffArrays, diffJson } from 'diff';
+import { equal } from 'tiny-types/lib/objects';
+import { types } from 'util';
+
+import { inspected, isPrimitive, typeOf } from '../io';
+import { isPlainObject } from '../io/stringified';
+import { Unanswered } from '../screenplay/questions/Unanswered';
+import { DiffFormatter } from './diff';
+import { AnsiDiffFormatter } from './diff/AnsiDiffFormatter';
+import { ErrorOptions } from './ErrorOptions';
+import { RuntimeError } from './model';
+
+/**
+ * Generates Serenity/JS {@apilink RuntimeError} objects based on provided {@apilink ErrorOptions|configuration}.
+ *
+ * @group Errors
+ */
+export class ErrorFactory {
+
+    constructor(private readonly formatter: DiffFormatter = new AnsiDiffFormatter()) {
+    }
+
+    create<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE {
+
+        const message = [
+            this.title(options.message),
+            options.expectation && `\nExpectation: ${ options.expectation }`,
+            options.diff && ('\n' + this.diffFrom(options.diff)),
+            options.location && (`    at ${ options.location.path.value }:${ options.location.line }:${ options.location.column }`),
+        ].
+        filter(Boolean).
+        join('\n');
+
+        return new errorType(message, options?.cause) as unknown as RE;
+    }
+
+    private title(value: string): string {
+        return String(value).trim();
+    }
+
+    private diffFrom(diff: { expected: unknown, actual: unknown }): string {
+        return new Diff(diff.expected, diff.actual)
+            .lines()
+            .map(line => line.decorated(this.formatter))
+            .join('\n');
+    }
+}
+
+type DiffType = 'expected' | 'received' | 'unchanged';
+
+class DiffLine {
+    private static markers: Record<DiffType, string> = {
+        'expected':  '- ',
+        'received':  '+ ',
+        'unchanged': '  ',
+    }
+
+    static empty = () =>
+        new DiffLine('unchanged', '');
+
+    static unchanged = (line: any) =>
+        new DiffLine('unchanged', String(line));
+
+    static expected = (line: any) =>
+        new DiffLine('expected', String(line));
+
+    static received = (line: any) =>
+        new DiffLine('received', String(line));
+
+    static changed = (change: Change | ArrayChange<any>, line: string) => {
+        if (change.removed) {
+            return this.expected(line);
+        }
+
+        if (change.added) {
+            return this.received(line);
+        }
+
+        return this.unchanged(line);
+    }
+
+    private constructor(
+        private readonly type: DiffType,
+        private readonly value: string,
+    ) {
+    }
+
+    prependMarker(): DiffLine {
+        return this.prepend(this.marker());
+    }
+
+    appendMarker(): DiffLine {
+        return this.append(this.marker());
+    }
+
+    prepend(text: any): DiffLine {
+        return new DiffLine(this.type, String(text) + this.value);
+    }
+
+    append(text: any): DiffLine {
+        return new DiffLine(this.type, this.value + String(text));
+    }
+
+    decorated(decorator: DiffFormatter): string {
+        return decorator[this.type](this.value);
+    }
+
+    private marker(): string {
+        return DiffLine.markers[this.type];
+    }
+}
+
+class DiffValue {
+    private nameAndType: string;
+    private readonly summary?: string;
+    private changes?: string;
+
+    public desiredNameFieldLength: number;
+
+    constructor(
+        name: string,
+        public readonly value: unknown,
+    ) {
+        this.nameAndType            = `${ name } ${ typeOf(value) }`;
+        this.desiredNameFieldLength = this.nameAndType.length;
+        this.summary                = this.summaryOf(value);
+    }
+
+    withDesiredFieldLength(columns: number): this {
+        this.desiredNameFieldLength = columns;
+        return this;
+    }
+
+    hasSummary() {
+        return this.summary !== undefined;
+    }
+
+    type(): string {
+        return typeOf(this.value);
+    }
+
+    isComplex(): boolean {
+        return (typeof this.value === 'object' || types.isProxy(this.value))
+            && ! (this.value instanceof RegExp)
+            && ! (this.value instanceof Unanswered);
+    }
+
+    isArray(): boolean {
+        return Array.isArray(this.value);
+    }
+
+    isComparableAsJson() {
+        if (! this.value || this.value instanceof Unanswered) {
+            return false;
+        }
+
+        return isPlainObject(this.value)
+            || this.value['toJSON'];
+    }
+
+    toString(): string {
+        const labelWidth = this.desiredNameFieldLength - this.nameAndType.length;
+
+        return [
+            this.nameAndType,
+            this.summary && ': '.padEnd(labelWidth + 2),
+            this.summary,
+            this.changes && this.changes.padStart(labelWidth + 5),
+        ].
+        filter(Boolean).
+        join('');
+    }
+
+    private summaryOf(value: unknown): string | undefined {
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+
+        const isDefined = value !== undefined && value !== null;
+
+        if (isDefined && (isPrimitive(value) || value instanceof RegExp)) {
+            return String(value);
+        }
+
+        return undefined;
+    }
+}
+
+class Diff {
+    private readonly diff: DiffLine[];
+
+    constructor(
+        expectedValue: unknown,
+        actualValue: unknown,
+    ) {
+        this.diff = this.diffFrom(expectedValue, actualValue);
+    }
+
+    private diffFrom(expectedValue: unknown, actualValue: unknown): DiffLine[] {
+        const { expected, actual } = this.aligned(
+            new DiffValue('Expected', expectedValue),
+            new DiffValue('Received', actualValue)
+        );
+
+        if (this.shouldRenderActualValueOnly(expected, actual)) {
+            return this.renderActualValue(expected, actual);
+        }
+
+        if (this.shouldRenderJsonDiff(expected, actual)) {
+            return this.renderJsonDiff(expected, actual);
+        }
+
+        if (this.shouldRenderArrayDiff(expected, actual)) {
+            return this.renderArrayDiff(expected, actual);
+        }
+
+        return [
+            DiffLine.expected(expected),
+            DiffLine.received(actual),
+            DiffLine.empty(),
+        ]
+    }
+
+    private shouldRenderActualValueOnly(expected: DiffValue, actual: DiffValue): boolean {
+        return actual.isComplex()
+            && ! actual.hasSummary()
+            && expected.type() !== actual.type();
+    }
+
+    private shouldRenderJsonDiff(expected: DiffValue, actual: DiffValue): boolean {
+        return expected.isComparableAsJson()
+            && actual.isComparableAsJson()
+            && ! expected.hasSummary()
+            && ! actual.hasSummary()
+    }
+
+    private shouldRenderArrayDiff(expected: DiffValue, actual: DiffValue): boolean {
+        return expected.isArray()
+            && actual.isArray();
+    }
+
+    private aligned(expected: DiffValue, actual: DiffValue): { expected: DiffValue, actual: DiffValue } {
+        const maxFieldLength = Math.max(
+            expected.desiredNameFieldLength,
+            actual.desiredNameFieldLength
+        );
+
+        return {
+            expected: expected.withDesiredFieldLength(maxFieldLength),
+            actual:   actual.withDesiredFieldLength(maxFieldLength)
+        };
+    }
+
+    private renderActualValue(expected: DiffValue, actual: DiffValue): DiffLine[] {
+
+        const lines = inspected(actual.value)
+            .split('\n')
+            .map(DiffLine.unchanged);
+
+        return [
+            DiffLine.expected(expected),
+            DiffLine.received(actual),
+            DiffLine.empty(),
+            ...lines,
+            DiffLine.empty(),
+        ];
+    }
+
+    private renderJsonDiff(expected: DiffValue, actual: DiffValue): DiffLine[] {
+        const changes = diffJson(expected.value as object, actual.value as object);
+
+        const lines = changes.reduce((acc, change) => {
+            const changedLines = change.value.trimEnd().split('\n');
+            return acc.concat(
+                changedLines.map(line => DiffLine.changed(change, line).prependMarker())
+            )
+        }, []);
+
+        const { added, removed } = this.countOf(changes);
+
+        return [
+            DiffLine.expected(expected).append('  ').appendMarker().append(`${ removed }`),
+            DiffLine.received(actual).append('  ').appendMarker().append(`${ added }`),
+            DiffLine.empty(),
+            ...lines,
+            DiffLine.empty(),
+        ];
+    }
+
+    private renderArrayDiff(expected: DiffValue, actual: DiffValue): DiffLine[]  {
+        const changes = diffArrays(expected.value as Array<unknown>, actual.value as Array<unknown>, { comparator: equal } );
+
+        const lines = changes.reduce((acc, change) => {
+            const items = change.value;
+            return acc.concat(
+                items.map(item =>
+                    DiffLine.changed(change, inspected(item, { compact: true }))
+                        .prepend('  ')
+                        .prependMarker()
+                )
+            );
+        }, []);
+
+        const { added, removed } = this.countOf(changes);
+
+        return [
+            DiffLine.expected(expected).append('  ').appendMarker().append(`${ removed }`),
+            DiffLine.received(actual).append('  ').appendMarker().append(`${ added }`),
+            DiffLine.empty(),
+            DiffLine.unchanged('  ['),
+            ...lines,
+            DiffLine.unchanged('  ]'),
+            DiffLine.empty(),
+        ]
+    }
+
+    private countOf(changes: Array<Change | ArrayChange<unknown>>): { added: number, removed: number } {
+        return changes.reduce(({ removed, added }, change) => {
+            return {
+                removed: removed + (change.removed ? change.count : 0),
+                added:   added +   (change.added ? change.count : 0),
+            }
+        }, { removed: 0, added: 0 });
+    }
+
+    lines(): DiffLine[] {
+        return this.diff;
+    }
+}

package/src/errors/ErrorOptions.ts

@@ -0,0 +1,16 @@
+import { FileSystemLocation } from '../io';
+import { ExpectationDetails } from '../screenplay';
+
+/**
+ * @group Errors
+ */
+export interface ErrorOptions {
+    message: string;
+    location?: FileSystemLocation;
+    expectation?: ExpectationDetails;
+    diff?: {
+        expected: unknown;
+        actual: unknown;
+    };
+    cause?: Error;
+}

package/src/errors/ErrorSerialiser.ts

@@ -0,0 +1,106 @@
+import { ensure, isDefined, isFunction, JSONObject, JSONValue } from 'tiny-types';
+
+/**
+ * @group Errors
+ */
+export class ErrorSerialiser {
+    private static readonly recognisedErrors: Array<new (...args: any[]) => Error> = [
+        // Built-in JavaScript errors
+        Error,
+        EvalError,
+        RangeError,
+        ReferenceError,
+        SyntaxError,
+        TypeError,
+        URIError,
+    ];
+
+    static serialise(error: Error): string {
+        if (this.isSerialisable(error)) {
+            return JSON.stringify(error.toJSON(), undefined, 0);
+        }
+
+        const name = error && error.constructor && error.constructor.name
+            ? error.constructor.name
+            : error.name;
+
+        const serialisedError = Object.getOwnPropertyNames(error).reduce((serialised, key) => {
+            serialised[key] = error[key]
+            return serialised;
+        }, { name }) as SerialisedError;
+
+        return JSON.stringify(serialisedError, undefined, 0);
+    }
+
+    static registerErrorTypes(...types: Array<new (...args: any[]) => Error>): void {
+        types.forEach(type => {
+            ErrorSerialiser.recognisedErrors.push(
+                ensure(`Error type ${ type }`, type as any, isDefined(), isFunction())
+            );
+        });
+    }
+
+    static deserialise(serialised?: string | JSONObject): Error | undefined {
+        if (serialised === null || serialised === undefined) {
+            return undefined;
+        }
+
+        const serialisedError = typeof serialised === 'string'
+            ? JSON.parse(serialised) as SerialisedError
+            : serialised;
+
+        const constructor = ErrorSerialiser.recognisedErrors.find(errorType => errorType.name === serialisedError.name) || Error;
+
+        if (this.isDeserialisable(constructor)) {
+            return constructor.fromJSON(serialisedError) as Error;
+        }
+
+        const deserialised = Object.create(constructor.prototype);
+        for (const property in serialisedError) {
+            if (Object.prototype.hasOwnProperty.call(serialisedError, property)) {
+                deserialised[property] = serialisedError[property];
+            }
+        }
+        return deserialised;
+    }
+
+    private static isSerialisable(value: any): value is { toJSON: () => JSONValue } {
+        return value
+            && typeof (value as any).toJSON === 'function';
+    }
+
+    private static isDeserialisable<T>(type: new (...args: any[]) => T): type is typeof type & { fromJSON: (o: JSONValue) => T } {
+        return type
+            && typeof (type as any).fromJSON === 'function';
+    }
+
+    static deserialiseFromStackTrace(stack: string): Error {
+        const stackTracePattern = /^([^\s:]*Error).*?(?::\s)?(.*?)\n(^ +at.*)$/ms;
+
+        if (! stackTracePattern.test(stack)) {
+            return new Error(String(stack));
+        }
+
+        const [, name, message, callStack_ ] = stack.match(stackTracePattern);
+
+        return ErrorSerialiser.deserialise({ name, message: message.trim(), stack });
+    }
+}
+
+interface SerialisedError extends JSONObject {
+    /**
+     *  Name of the constructor function used to instantiate
+     *  the original {@apilink Error} object.
+     */
+    name:    string;
+
+    /**
+     *  Message of the original {@apilink Error} object
+     */
+    message: string;
+
+    /**
+     *  Stack trace of the original {@apilink Error} object
+     */
+    stack:   string;
+}

package/src/{io → errors}/ErrorStackParser.ts

@@ -1,12 +1,12 @@
 import * as parser from 'error-stack-parser';
 
 /**
- * @desc
- *  A thin wrapper around error-stack-parser module
+ * A thin wrapper around error-stack-parser module
  *
- * @see https://www.npmjs.com/package/error-stack-parser
+ * ## Learn more
+ * - [Error stack parser](https://www.npmjs.com/package/error-stack-parser)
  *
- * @package
+ * @group Errors
  */
 export class ErrorStackParser {
     parse(error: Error): parser.StackFrame[] {

package/src/errors/RaiseErrors.ts

@@ -0,0 +1,61 @@
+import { Ability } from '../screenplay';
+import { Stage } from '../stage';
+import { ErrorOptions } from './ErrorOptions';
+import { RuntimeError } from './model';
+
+/**
+ * An {@apilink Ability} that enables an {@apilink Actor} to create a Serenity/JS {@apilink RuntimeError}
+ * from within a custom {@apilink Interaction}.
+ *
+ * The stack trace of an error created this way includes the filesystem location pointing to where the interaction was invoked,
+ * which makes debugging any failures easier.
+ *
+ * :::info Pro tip
+ * The ability to `RaiseErrors` is given to all Serenity/JS actors by default, so you don't need to configure it explicitly.
+ * :::
+ *
+ * ## Raising an error
+ *
+ * ```typescript
+ * import { Interaction, LogicError, RaiseErrors } from '@serenity-js/core'
+ * import isPathInside from 'is-path-inside'
+ * import { unlink } from 'fs/promises'
+ *
+ * const RemoveFile = (pathToFile: string) =>
+ *   Interaction.where(`#actor removes a file at ${ pathToFile }`, async actor => {
+ *
+ *     if (! isPathInside(pathToFile, process.cwd())) {
+ *
+ *       throw RaiseErrors.as(actor).create(LogicError, {
+ *         message: `Removing files outside the current working directory is not allowed`
+ *         diff: {
+ *           expected: process.cwd(),
+ *           actual: pathToFile,
+ *         }
+ *       })
+ *     }
+ *
+ *     await unlink(pathToFile);
+ *   })
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink ErrorOptions}
+ * - {@apilink ErrorFactory}
+ * - {@apilink AssertionError}
+ * - {@apilink ConfigurationError}
+ * - {@apilink LogicError}
+ * - {@apilink RuntimeError}
+ * - {@apilink TestCompromisedError}
+ *
+ * @group Errors
+ */
+export class RaiseErrors extends Ability {
+    constructor(private readonly stage: Stage) {
+        super();
+    }
+
+    create<RE extends RuntimeError>(errorType: new (...args: any[]) => RE, options: ErrorOptions): RE {
+        return this.stage.createError(errorType, options);
+    }
+}

package/src/errors/diff/AnsiDiffFormatter.ts

@@ -0,0 +1,41 @@
+import { Chalk, Instance as ChalkInstance, Options } from 'chalk';   // eslint-disable-line unicorn/import-style
+
+import { DiffFormatter } from './DiffFormatter';
+
+/**
+ * A {@apilink DiffFormatter} that uses [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)
+ * to format the output.
+ *
+ * @group Errors
+ */
+export class AnsiDiffFormatter implements DiffFormatter {
+    private readonly chalk: Chalk;
+
+    /**
+     * Instantiates an `AnsiDiffFormatter`, configured with colour support options for [Chalk](https://github.com/chalk/chalk).
+     * When no `chalkOptions` object is provided, Chalk will auto-detect colour support automatically based on the execution environment.
+     *
+     * Available colour support levels:
+     * - `0` - All colours disabled.
+     * - `1` - Basic 16 colours support.
+     * - `2` - ANSI 256 colours support.
+     * - `3` - Truecolor - 16 million colours support.
+     *
+     * @param chalkOptions
+     */
+    constructor(chalkOptions?: Options) {
+        this.chalk = new ChalkInstance(chalkOptions);
+    }
+
+    expected(line: string): string {
+        return this.chalk.green(line);
+    }
+
+    received(line: string): string {
+        return this.chalk.red(line);
+    }
+
+    unchanged(line: string): string {
+        return line;
+    }
+}

package/src/errors/diff/DiffFormatter.ts

@@ -0,0 +1,12 @@
+/**
+ * Formats text representing expected, received, and unchanged lines of a diff
+ * produced by the {@apilink ErrorFactory}, so that they can be presented to a developer
+ * in a visually distinctive way.
+ *
+ * @group Errors
+ */
+export interface DiffFormatter {
+    expected(line: string): string;
+    received(line: string): string;
+    unchanged(line: string): string;
+}

package/src/errors/diff/NoOpDiffFormatter.ts

@@ -0,0 +1,20 @@
+import { DiffFormatter } from './DiffFormatter';
+
+/**
+ * A no-op {@apilink DiffFormatter} that produces output identical to input.
+ *
+ * @group Errors
+ */
+export class NoOpDiffFormatter implements DiffFormatter {
+    expected(line: string): string {
+        return line;
+    }
+
+    received(line: string): string {
+        return line;
+    }
+
+    unchanged(line: string): string {
+        return line;
+    }
+}

package/src/errors/diff/index.ts

@@ -0,0 +1,3 @@
+export * from './AnsiDiffFormatter';
+export * from './DiffFormatter';
+export * from './NoOpDiffFormatter';

package/src/errors/index.ts

@@ -1,7 +1,28 @@
-export * from './AssertionError';
-export * from './ConfigurationError';
-export * from './ImplementationPendingError';
-export * from './LogicError';
-export * from './RuntimeError';
-export * from './TestCompromisedError';
-export * from './UnknownError';
+/* eslint-disable simple-import-sort/imports */
+import { AssertionError, ConfigurationError, ImplementationPendingError, LogicError, OperationInterruptedError, TestCompromisedError, TimeoutExpiredError, UnknownError } from './model';
+import { ErrorSerialiser } from './ErrorSerialiser';
+/* eslint-enable simple-import-sort/imports */
+
+// todo: export ErrorSerialiser as an instance to avoid static method calls
+ErrorSerialiser.registerErrorTypes(
+    AssertionError,
+    ConfigurationError,
+    ImplementationPendingError,
+    LogicError,
+    OperationInterruptedError,
+    TestCompromisedError,
+    TimeoutExpiredError,
+    UnknownError,
+);
+
+export * from './diff';
+export * from './model';
+
+/* eslint-disable simple-import-sort/exports */
+export { ErrorSerialiser } from './ErrorSerialiser';
+export { ErrorStackParser } from './ErrorStackParser';
+/* eslint-enable simple-import-sort/exports */
+
+export { ErrorFactory } from './ErrorFactory';
+export { ErrorOptions } from './ErrorOptions';
+export * from './RaiseErrors'

package/src/errors/model/AssertionError.ts

@@ -0,0 +1,31 @@
+import { JSONObject } from 'tiny-types';
+
+import { ErrorSerialiser } from '../ErrorSerialiser';
+import { RuntimeError } from './RuntimeError';
+
+/**
+ * Thrown to indicate that an assertion has failed.
+ *
+ * @group Errors
+ */
+export class AssertionError extends RuntimeError {
+
+    static fromJSON(serialised: JSONObject): AssertionError {
+        const error = new AssertionError(
+            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 and the difference between the expected and actual values
+     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     */
+    constructor(message: string, cause?: Error) {
+        super(AssertionError, message, cause);
+    }
+}