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

package/src/io/stringified.ts

@@ -0,0 +1,266 @@
+import { inspect } from 'util';
+
+import { Answerable } from '../screenplay/Answerable';
+import { Question } from '../screenplay/Question';
+
+const indentationPrefix = '  ';
+
+interface StringifyConfig {
+    inline: boolean;
+    indentationLevel?: number;
+    markQuestions?: boolean;
+}
+
+/**
+ * Provides a human-readable description of the {@apilink Answerable<T>}.
+ * Similar to [Node util~inspect](https://nodejs.org/api/util.html#utilinspectobject-options).
+ *
+ * @param value
+ * @param config
+ *  - inline - Return a single-line string instead of the default potentially multi-line description
+ *  - markQuestions - Surround the description of async values, such as Promises and Questions with <<value>>
+ */
+export function stringified(value: Answerable<any>, config?: StringifyConfig): string {
+
+    const { indentationLevel, inline, markQuestions } = { indentationLevel: 0, inline: false, markQuestions: false, ...config };
+
+    if (! isDefined(value)) {
+        return inspect(value);
+    }
+
+    if (Array.isArray(value)) {
+        return stringifiedArray(value, { indentationLevel, inline, markQuestions });
+    }
+
+    if (isAPromise(value)) {
+        return markAs('Promise', markQuestions);
+    }
+
+    if (Question.isAQuestion(value)) {
+        return markAs(value.toString(), markQuestions);
+    }
+
+    if (isADate(value)) {
+        return value.toISOString();
+    }
+
+    if (hasItsOwnToString(value)) {
+        return value.toString();
+    }
+
+    if (isInspectable(value)) {
+        return value.inspect();
+    }
+
+    if (isAFunction(value)) {
+        return hasName(value)
+            ? value.name
+            : markAs(`Function`, true);
+    }
+
+    if (! hasCustomInspectionFunction(value) && isPlainObject(value) && isSerialisableAsJSON(value)) {
+        return stringifiedToJson(value, { indentationLevel, inline, markQuestions });
+    }
+
+    return inspect(value, { breakLength: Number.POSITIVE_INFINITY, compact: inline ? 3 : false, sorted: false  });
+}
+
+function indented(line: string, config: { inline: boolean; indentationLevel?: number }): string {
+    const indentation = config.inline
+        ? ''
+        : indentationPrefix.repeat(config.indentationLevel || 0);
+
+    return indentation + line;
+}
+
+function stringifiedToJson(value: any, config: StringifyConfig): string {
+    const jsonLineIndentation = config.inline ? 0 : indentationPrefix.length;
+
+    const [ first, ...rest ] = JSON.stringify(value, undefined, jsonLineIndentation).split('\n');
+
+    return [
+        first,
+        ...rest.map(line => indented(line, config))
+    ].join('\n');
+}
+
+function stringifiedArray(value: any[], config: StringifyConfig): string {
+    const lineSeparator = config.inline ? ' ' : '\n';
+
+    const inspectedItem = (item: unknown, index: number) => {
+        const nestedItemConfig = { ...config, indentationLevel: config.indentationLevel + 1 }
+        return [
+            indented('', nestedItemConfig),
+            stringified(item, nestedItemConfig),
+            index < value.length - 1 ? ',' : ''
+        ].join('')
+    }
+
+    return [
+        `[`,
+        ...value.map(inspectedItem),
+        indented(']', config),
+    ].join(lineSeparator);
+}
+
+function markAs(value: string, markValue: boolean): string {
+    const [ left, right ] = markValue && ! value.startsWith('<<')
+        ? [ '<<', '>>' ]
+        : [ '', '' ];
+
+    return [ left, value, right ].join('');
+}
+
+/**
+ * Checks if the value is defined
+ *
+ * @param v
+ */
+function isDefined(v: Answerable<any>) {
+    return !! v;
+}
+
+/**
+ * Checks if the value defines its own `toString` method
+ *
+ * @param v
+ */
+function hasItsOwnToString(v: Answerable<any>): v is { toString: () => string } {
+    return typeof v === 'object'
+        && !! (v as any).toString
+        && typeof (v as any).toString === 'function'
+        && ! isNative((v as any).toString);
+}
+
+/**
+ * Checks if the value defines its own `inspect` method
+ *
+ * @param v
+ */
+function isInspectable(v: Answerable<any>): v is { inspect: () => string } {
+    return !! (v as any).inspect && typeof (v as any).inspect === 'function';
+}
+
+/**
+ * Checks if the value is a {@apilink Date}
+ *
+ * @param v
+ */
+function isADate(v: Answerable<any>): v is Date {
+    return v instanceof Date;
+}
+
+/**
+ * Checks if the value is a {@apilink Promise}
+ *
+ * @param v
+ */
+function isAPromise<T>(v: Answerable<T>): v is Promise<T> {
+    return typeof v === 'object'
+        && 'then' in v;
+}
+
+/**
+ * Checks if the value is a named {@apilink Function}
+ *
+ * @param v
+ */
+function isAFunction(v: any): v is Function {       // eslint-disable-line @typescript-eslint/ban-types
+    return Object.prototype.toString.call(v) === '[object Function]';
+}
+
+/**
+ * Checks if the value is has a property called 'name' with a non-empty value.
+ *
+ * @param v
+ */
+function hasName(v: any): v is { name: string } {
+    return typeof (v as any).name === 'string' && (v as any).name !== '';
+}
+
+/**
+ * Checks if the value defines its own [`inspect` method](https://nodejs.org/api/util.html#util_util_inspect_custom)
+ *
+ * @param v
+ */
+function hasCustomInspectionFunction(v: Answerable<any>): v is object { // eslint-disable-line @typescript-eslint/ban-types
+    return v && v[Symbol.for('nodejs.util.inspect.custom')];
+}
+
+/**
+ * Checks if the value has a good chance of being a plain JavaScript object
+ *
+ * @param v
+ */
+export function isPlainObject(v: unknown): v is object {   // eslint-disable-line @typescript-eslint/ban-types
+
+    // Basic check for Type object that's not null
+    if (typeof v === 'object' && v !== null) {
+
+        // If Object.getPrototypeOf supported, use it
+        if (typeof Object.getPrototypeOf === 'function') {
+            const proto = Object.getPrototypeOf(v);
+            return proto === Object.prototype || proto === null;
+        }
+
+        // Otherwise, use internal class
+        // This should be reliable as if getPrototypeOf not supported, is pre-ES5
+        return Object.prototype.toString.call(v) === '[object Object]';
+    }
+
+    // Not an object
+    return false;
+}
+
+/**
+ * Checks if the value is a JSON object that can be stringified
+ *
+ * @param v
+ */
+function isSerialisableAsJSON(v: any): v is object {    // eslint-disable-line @typescript-eslint/ban-types
+    try {
+        JSON.stringify(v);
+
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Inspired by https://davidwalsh.name/detect-native-function
+ *
+ * @param v
+ */
+function isNative(v: any): v is Function {  // eslint-disable-line @typescript-eslint/ban-types
+
+    const
+        toString        = Object.prototype.toString,    // Used to resolve the internal `{@apilink Class}` of values
+        fnToString      = Function.prototype.toString,  // Used to resolve the decompiled source of functions
+        hostConstructor = /^\[object .+?Constructor]$/; // Used to detect host constructors (Safari > 4; really typed array specific)
+
+    // Compile a regexp using a common native method as a template.
+    // We chose `Object#toString` because there's a good chance it is not being mucked with.
+    const nativeFunctionTemplate = new RegExp(
+        '^' +
+        // Coerce `Object#toString` to a string
+        String(toString)
+        // Escape any special regexp characters
+            .replace(/[$()*+./?[\\\]^{|}]/g , '\\$&')
+            // Replace mentions of `toString` with `.*?` to keep the template generic.
+            // Replace thing like `for ...` to support environments like Rhino which add extra info
+            // such as method arity.
+            .replace(/toString|(function).*?(?=\\\()| for .+?(?=\\])/g, '$1.*?') +
+        '$',
+    );
+
+    const type = typeof v;
+    return type === 'function'
+        // Use `Function#toString` to bypass the value's own `toString` method
+        // and avoid being faked out.
+        ? nativeFunctionTemplate.test(fnToString.call(v))
+        // Fallback to a host object check because some environments will represent
+        // things like typed arrays as DOM methods which may not conform to the
+        // normal native pattern.
+        : (v && type === 'object' && hostConstructor.test(toString.call(v))) || false;
+}

package/src/io/trimmed.ts

@@ -1,14 +1,12 @@
 /**
- * @desc
- *  A tag function trimming the leading and trailing whitespace from multi-line strings.
+ * A tag function trimming the leading and trailing whitespace from multi-line strings.
  *
- * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals
+ * @apilink https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals
  *
- * @param {TemplateStringsArray} templates
- * @param {Array<string>} placeholders
- * @returns {string}
+ * @param templates
+ * @param placeholders
  */
-export function trimmed(templates: TemplateStringsArray, ...placeholders: string[]): string {
+export function trimmed(templates: TemplateStringsArray, ...placeholders: Array<any>): string {
 
     const lines = templates
         .map((template, i) => i < placeholders.length
@@ -23,6 +21,6 @@ export function trimmed(templates: TemplateStringsArray, ...placeholders: string
         .filter(line => !! line);
 
     return nonEmptyLines
-        .map(line => line.replace(/\|\s?(.*)$/, '$1\n'))
-        .join('');
+        .map(line => line.replace(/\|\s?(.*)$/, '$1'))
+        .join('\n');
 }

package/src/model/ActivityDetails.ts

@@ -1,23 +1,29 @@
-import { JSONObject, TinyType } from 'tiny-types';
+import { ensure, isDefined, JSONObject, TinyType } from 'tiny-types';
 
+import { FileSystemLocation } from '../io/FileSystemLocation';
 import { Name } from './Name';
 
 export class ActivityDetails extends TinyType {
     static fromJSON(o: JSONObject): ActivityDetails {
         return new ActivityDetails(
             Name.fromJSON(o.name as string),
+            FileSystemLocation.fromJSON(o.location as JSONObject),
         );
     }
 
     constructor(
         public readonly name: Name,
+        public readonly location: FileSystemLocation,
     ) {
         super();
+        ensure('name', name, isDefined())
+        ensure('location', location, isDefined())
     }
 
-    toJSON(): { name: string } {
+    toJSON(): { name: string, location: { path: string, line: number, column: number } } {
         return {
             name: this.name.value,
+            location: this.location.toJSON() as { path: string, line: number, column: number },
         }
     }
 }

package/src/model/CorrelationId.ts

@@ -1,4 +1,4 @@
-import * as cuid from 'cuid';
+import cuid from 'cuid';
 import { TinyTypeOf } from 'tiny-types';
 
 export class CorrelationId extends TinyTypeOf<string>() {

package/src/model/ScenarioDetails.ts

@@ -1,4 +1,4 @@
-import { JSONObject, TinyType } from 'tiny-types';
+import { ensure, isDefined, JSONObject, TinyType } from 'tiny-types';
 
 import { FileSystemLocation } from '../io';
 import { Category } from './Category';
@@ -19,5 +19,8 @@ export class ScenarioDetails extends TinyType {
         public readonly location: FileSystemLocation,
     ) {
         super();
+        ensure('scenario name', name, isDefined());
+        ensure('scenario category', category, isDefined());
+        ensure('scenario location', location, isDefined());
     }
 }

package/src/model/artifacts/HTTPRequestResponse.ts

@@ -3,30 +3,26 @@ import { JSONObject } from 'tiny-types';
 import { JSONData } from './JSONData';
 
 /**
- * @desc
- *  The value of the {@link HTTPRequestResponse} {@link Artifact} describing a HTTP request/response pair.
- *
- * @public
+ * The value of the {@apilink HTTPRequestResponse} {@apilink Artifact} describing an HTTP request/response pair.
  */
 export interface RequestAndResponse extends JSONObject {
     request: {
         url: string;
         method: string;
-        headers: { [header: string]: string };
+        headers: Record<string, string | number | boolean>;
         data?: any;
     };
     response: {
         status: number;
         data?: any;
-        headers?: { [header: string]: string };
+        headers?: Record<string, string> & {
+            'set-cookie'?: string[]
+        };
     };
 }
 
 /**
- * @desc
- *  An {@link Artifact} describing a HTTP request/response pair.
- *
- * @public
+ * An {@apilink Artifact} describing a HTTP request/response pair.
  */
 export class HTTPRequestResponse extends JSONData {
     static fromJSON(value: RequestAndResponse): HTTPRequestResponse {

package/src/model/artifacts/Photo.ts

@@ -6,18 +6,10 @@ import { Artifact } from '../Artifact';
  */
 export class Photo extends Artifact {
 
-    /**
-     * @desc
-     * @param {string} value
-     */
     static fromBase64(value: string): Photo {
         return new Photo(value);
     }
 
-    /**
-     * @desc
-     * @param {Buffer | ArrayBuffer} value
-     */
     static fromBuffer(value: Buffer | ArrayBuffer): Photo {
         const buffer = value instanceof ArrayBuffer
             ? Buffer.from(value)

package/src/model/artifacts/index.ts

@@ -1,4 +1,3 @@
-export * from './AssertionReport';
 export * from './HTTPRequestResponse';
 export * from './JSONData';
 export * from './LogEntry';

package/src/model/index.ts

@@ -7,11 +7,9 @@ export * from './BusinessRule';
 export * from './Category';
 export * from './CorrelationId';
 export * from './Description';
-export * from './Duration';
 export * from './Name';
 export * from './outcomes';
 export * from './ScenarioDetails';
 export * from './ScenarioParameters';
 export * from './tags';
 export * from './TestSuiteDetails';
-export * from './Timestamp';

package/src/model/outcomes.ts

@@ -1,8 +1,7 @@
 /* eslint-disable @typescript-eslint/explicit-module-boundary-types,unicorn/prefer-math-trunc */
 import { JSONObject, match, TinyType } from 'tiny-types';
 
-import { AssertionError } from '../errors';
-import { ErrorSerialiser } from '../io';
+import { AssertionError, ErrorSerialiser } from '../errors';
 
 export interface SerialisedOutcome extends JSONObject {
     code:    number;
@@ -72,7 +71,8 @@ export class ExecutionCompromised extends ProblemIndication {
 export class ExecutionFailedWithError extends ProblemIndication {
     static Code = 1 << 1;
 
-    static fromJSON = (o: SerialisedOutcome) => new ExecutionFailedWithError(ErrorSerialiser.deserialise(o.error));
+    static fromJSON = (o: SerialisedOutcome) =>
+        new ExecutionFailedWithError(ErrorSerialiser.deserialise(o.error));
 
     constructor(error: Error) {
         super(error, ExecutionFailedWithError.Code);
@@ -85,7 +85,8 @@ export class ExecutionFailedWithError extends ProblemIndication {
 export class ExecutionFailedWithAssertionError extends ProblemIndication {
     static Code = 1 << 2;
 
-    static fromJSON = (o: SerialisedOutcome) => new ExecutionFailedWithAssertionError(ErrorSerialiser.deserialise(o.error));
+    static fromJSON = (o: SerialisedOutcome) =>
+        new ExecutionFailedWithAssertionError(ErrorSerialiser.deserialise(o.error) as AssertionError);
 
     constructor(error: AssertionError) {
         super(error, ExecutionFailedWithAssertionError.Code);

package/src/model/tags/ArbitraryTag.ts

@@ -1,11 +1,8 @@
 import { Tag } from './Tag';
 
 /**
- * @desc
- *  Tagged with an arbitrary tag that doesn't have any special interpretation
- *  such as @regression, @wip, etc.
- *
- * @access public
+ * Tagged with an arbitrary tag that doesn't have any special interpretation
+ * such as `@regression`, `@wip`, etc.
  */
 export class ArbitraryTag extends Tag {
     static readonly Type = 'tag';

package/src/model/tags/ExecutionRetriedTag.ts

@@ -3,11 +3,8 @@ import { JSONObject } from 'tiny-types';
 import { Tag } from './Tag';
 
 /**
- * @desc
- *  Indicates that execution of a given scene
- *  has been retried for the `currentRetry`-th time.
- *
- * @access public
+ * Indicates that execution of a given scene
+ * has been retried for the `currentRetry`-th time.
  */
 export class ExecutionRetriedTag extends Tag {
     static readonly Type = 'retry';

package/src/model/tags/index.ts

@@ -1,7 +1,6 @@
 export * from './ArbitraryTag';
 export * from './BrowserTag';
 export * from './CapabilityTag';
-export * from './ContextTag';
 export * from './ExecutionRetriedTag';
 export * from './FeatureTag';
 export * from './IssueTag';

package/src/screenplay/Activity.ts

@@ -1,34 +1,92 @@
-import { AnswersQuestions, PerformsActivities, UsesAbilities } from './actor';
+import path from 'path';
+
+import { ErrorStackParser } from '../errors';
+import { FileSystemLocation, Path } from '../io';
+import { UsesAbilities } from './abilities';
+import { PerformsActivities } from './activities';
+import { AnswersQuestions } from './questions';
 
 /**
- * @desc
- *  A command object representing an activity that an {@link Actor} can perform.
+ * **Activities** represents {@apilink Task|tasks} and {@apilink Interaction|interactions} to be performed by an {@apilink Actor|actor}.
+ *
+ * Learn more about:
+ * - [Performing activities at multiple levels](/handbook/design/screenplay-pattern#performing-activities-at-multiple-levels)
+ * - {@apilink Actor}
+ * - {@apilink PerformsActivities}
+ * - [Command design pattern on Wikipedia](https://en.wikipedia.org/wiki/Command_pattern)
  *
- * @see {@link Actor}
- * @see https://en.wikipedia.org/wiki/Command_pattern
+ * @group Screenplay Pattern
  */
-export interface Activity {
+export abstract class Activity {
+
+    private static errorStackParser = new ErrorStackParser();
+    readonly #description: string;
+    readonly #location: FileSystemLocation;
+
+    constructor(
+        description: string,
+        location: FileSystemLocation = Activity.callerLocation(5)
+    ) {
+        this.#description = description;
+        this.#location = location;
+    }
+
+    /**
+     * Returns the location where this {@apilink Activity} was instantiated.
+     */
+    instantiationLocation(): FileSystemLocation {
+        return this.#location;
+    }
 
     /**
-     * @desc
-     *  Makes the provided {@link Actor}
-     *  perform this Activity.
+     * Instructs the provided {@apilink Actor} to perform this {@apilink Activity}.
      *
-     * @param {PerformsActivities | UsesAbilities | AnswersQuestions} actor
-     * @returns {Promise<void>}
+     * @param actor
      *
-     * @see {@link Actor}
-     * @see {@link PerformsActivities}
-     * @see {@link UsesAbilities}
-     * @see {@link AnswersQuestions}
+     * #### Learn more
+     * - {@apilink Actor}
+     * - {@apilink PerformsActivities}
+     * - {@apilink UsesAbilities}
+     * - {@apilink AnswersQuestions}
      */
-    performAs(actor: PerformsActivities | UsesAbilities | AnswersQuestions): PromiseLike<any>;
+    abstract performAs(actor: PerformsActivities | UsesAbilities | AnswersQuestions): Promise<any>;
 
     /**
-     * @desc
-     *  Generates a description to be used when reporting this Activity.
+     * Generates a human-friendly description to be used when reporting this Activity.
      *
-     * @returns {string}
+     * **Note**: When this activity is reported, token `#actor` in the description
+     * will be replaced with the name of the actor performing this Activity.
+     *
+     * For example, `#actor clicks on a button` becomes `Wendy clicks on a button`.
      */
-    toString(): string;
+    toString(): string {
+        return this.#description;
+    }
+
+    protected static callerLocation(frameOffset: number): FileSystemLocation {
+
+        const originalStackTraceLimit = Error.stackTraceLimit;
+        Error.stackTraceLimit = 30;
+        const error = new Error('Caller location marker');
+        Error.stackTraceLimit = originalStackTraceLimit;
+
+        const nonSerenityNodeModulePattern = new RegExp(`node_modules` + `\\` + path.sep + `(?!@serenity-js`+ `\\` + path.sep +`)`);
+
+        const frames = this.errorStackParser.parse(error);
+        const userLandFrames = frames.filter(frame => ! (
+            frame?.fileName.startsWith('node:') ||          // node 16 and 18
+            frame?.fileName.startsWith('internal') ||       // node 14
+            nonSerenityNodeModulePattern.test(frame?.fileName)    // ignore node_modules, except for @serenity-js/*
+        ));
+
+        const index = Math.min(Math.max(1, frameOffset), userLandFrames.length - 1);
+        // use the desired user-land frame, or the last one from the stack trace for internal invocations
+        const invocationFrame = userLandFrames[index] || frames[frames.length - 1];
+
+        return new FileSystemLocation(
+            Path.from(invocationFrame.fileName),
+            invocationFrame.lineNumber,
+            invocationFrame.columnNumber,
+        );
+    }
 }