@serenity-js/core 3.0.0-rc.23 → 3.0.0-rc.24

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.0.0-rc.24](https://github.com/serenity-js/serenity-js/compare/v3.0.0-rc.23...v3.0.0-rc.24) (2022-07-23)
+
+
+### Bug Fixes
+
+* **core:** improved how the interaction to Log reports names of the logged values ([c4cc60d](https://github.com/serenity-js/serenity-js/commit/c4cc60d0e1d4bdc34218566b1726e74d3ac40909))
+
+
+### Features
+
+* **core:** new interaction to Debug.values(..) and Debug.setBreakpoint() ([ef54324](https://github.com/serenity-js/serenity-js/commit/ef54324ca1b415d41eee12e7f4667cbffe2c8a01))
+
+
+
+
+
 # [3.0.0-rc.23](https://github.com/serenity-js/serenity-js/compare/v2.33.10...v3.0.0-rc.23) (2022-07-19)
 
 

package/lib/screenplay/Answered.d.ts

@@ -0,0 +1,2 @@
+import { Question } from './Question';
+export declare type Answered<T> = T extends null | undefined ? T : T extends Question<Promise<infer A>> | Question<infer A> | Promise<infer A> ? Awaited<A> : T;

package/lib/screenplay/Answered.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Answered.js.map

package/lib/screenplay/Answered.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Answered.js","sourceRoot":"","sources":["../../src/screenplay/Answered.ts"],"names":[],"mappings":""}

package/lib/screenplay/index.d.ts

@@ -4,6 +4,7 @@ export * from './AbilityType';
 export * from './Activity';
 export * from './actor';
 export * from './Answerable';
+export * from './Answered';
 export * from './Interaction';
 export * from './interactions';
 export * from './notes';

package/lib/screenplay/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./AbilityType"), exports);
 __exportStar(require("./Activity"), exports);
 __exportStar(require("./actor"), exports);
 __exportStar(require("./Answerable"), exports);
+__exportStar(require("./Answered"), exports);
 __exportStar(require("./Interaction"), exports);
 __exportStar(require("./interactions"), exports);
 __exportStar(require("./notes"), exports);

package/lib/screenplay/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/screenplay/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,4CAA0B;AAC1B,gDAA8B;AAC9B,6CAA2B;AAC3B,0CAAwB;AACxB,+CAA6B;AAC7B,gDAA8B;AAC9B,iDAA+B;AAC/B,0CAAwB;AACxB,6CAA2B;AAC3B,6CAA2B;AAC3B,8CAA4B;AAC5B,wDAAsC;AACtC,yCAAuB;AACvB,6DAA2C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/screenplay/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,4CAA0B;AAC1B,gDAA8B;AAC9B,6CAA2B;AAC3B,0CAAwB;AACxB,+CAA6B;AAC7B,6CAA2B;AAC3B,gDAA8B;AAC9B,iDAA+B;AAC/B,0CAAwB;AACxB,6CAA2B;AAC3B,6CAA2B;AAC3B,8CAA4B;AAC5B,wDAAsC;AACtC,yCAAuB;AACvB,6DAA2C"}

package/lib/screenplay/interactions/Log.d.ts

@@ -29,7 +29,7 @@ export declare class Log extends Interaction {
      */
     static the(...items: Array<Answerable<any>>): Interaction;
     /**
-     * @param {...items: any[]} items
+     * @param {Array<Answerable<any>>} items
      *  The items to be logged
      */
     constructor(items: Array<Answerable<any>>);

package/lib/screenplay/interactions/Log.js

@@ -4,7 +4,6 @@ exports.Log = void 0;
 const io_1 = require("../../io");
 const inspected_1 = require("../../io/inspected");
 const model_1 = require("../../model");
-const artifacts_1 = require("../../model/artifacts");
 const Interaction_1 = require("../Interaction");
 /**
  * @desc
@@ -24,7 +23,7 @@ const Interaction_1 = require("../Interaction");
  */
 class Log extends Interaction_1.Interaction {
     /**
-     * @param {...items: any[]} items
+     * @param {Array<Answerable<any>>} items
      *  The items to be logged
      */
     constructor(items) {
@@ -55,10 +54,11 @@ class Log extends Interaction_1.Interaction {
      * @see {@link AnswersQuestions}
      * @see {@link CollectsArtifacts}
      */
-    performAs(actor) {
-        return Promise
-            .all(this.items.map(item => actor.answer(item)))
-            .then(items => items.forEach((item, i) => actor.collect(artifacts_1.LogEntry.fromJSON({ data: (0, inspected_1.inspected)(item) }), new model_1.Name((0, inspected_1.inspected)(this.items[i])))));
+    async performAs(actor) {
+        for (const item of this.items) {
+            const data = await actor.answer(item);
+            actor.collect(model_1.LogEntry.fromJSON({ data: (0, inspected_1.inspected)(data) }), new model_1.Name((0, io_1.d) `${item}`));
+        }
     }
     /**
      * @desc
@@ -67,7 +67,7 @@ class Log extends Interaction_1.Interaction {
      * @returns {string}
      */
     toString() {
-        return `#actor logs: ${this.items.map(item => (0, io_1.formatted) `${item}`).join(', ')}`;
+        return `#actor logs: ${this.items.map(item => (0, io_1.d) `${item}`).join(', ')}`;
     }
 }
 exports.Log = Log;

package/lib/screenplay/interactions/Log.js.map

@@ -1 +1 @@
-{"version":3,"file":"Log.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Log.ts"],"names":[],"mappings":";;;AAAA,iCAAqC;AACrC,kDAA+C;AAC/C,uCAAmC;AACnC,qDAAiD;AAGjD,gDAA6C;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,MAAa,GAAI,SAAQ,yBAAW;IAchC;;;OAGG;IACH,YACqB,KAA6B;QAE9C,KAAK,EAAE,CAAC;QAFS,UAAK,GAAL,KAAK,CAAwB;IAGlD,CAAC;IApBD;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,KAA6B;QACvC,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAYD;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,KAA2D;QACjE,OAAO,OAAO;aACT,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;aAC/C,IAAI,CAAC,KAAK,CAAC,EAAE,CACV,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CACtB,KAAK,CAAC,OAAO,CAAC,oBAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAA,qBAAS,EAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,YAAI,CAAC,IAAA,qBAAS,EAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAClG,CACJ,CAAC;IACV,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,gBAAiB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAA,cAAS,EAAA,GAAI,IAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAE,EAAE,CAAC;IACvF,CAAC;CACJ;AAxDD,kBAwDC"}
+{"version":3,"file":"Log.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Log.ts"],"names":[],"mappings":";;;AAAA,iCAA6B;AAC7B,kDAA+C;AAC/C,uCAA6C;AAG7C,gDAA6C;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,MAAa,GAAI,SAAQ,yBAAW;IAchC;;;OAGG;IACH,YACqB,KAA6B;QAE9C,KAAK,EAAE,CAAC;QAFS,UAAK,GAAL,KAAK,CAAwB;IAGlD,CAAC;IApBD;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,KAA6B;QACvC,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAYD;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,SAAS,CAAC,KAA2D;QACvE,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE;YAE3B,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAEtC,KAAK,CAAC,OAAO,CACT,gBAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAA,qBAAS,EAAC,IAAI,CAAC,EAAE,CAAC,EAC5C,IAAI,YAAI,CAAC,IAAA,MAAC,EAAA,GAAI,IAAK,EAAE,CAAC,CACzB,CAAC;SACL;IACL,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,gBAAiB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAA,MAAC,EAAA,GAAI,IAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAE,EAAE,CAAC;IAC/E,CAAC;CACJ;AA1DD,kBA0DC"}

package/lib/screenplay/interactions/debug/Debug.d.ts

@@ -0,0 +1,95 @@
+import { AnswersQuestions, CollectsArtifacts, UsesAbilities } from '../../actor';
+import { Answerable } from '../../Answerable';
+import { Answered } from '../../Answered';
+import { Interaction } from '../../Interaction';
+import { DebuggingResult } from './DebuggingResult';
+/**
+ * @desc
+ *  Instructs the {@link Actor} to set a breakpoint and optionally evaluate and log the provided {@link Answerable} values.
+ *
+ *  Since this interaction sets a breakpoint using the [`debugger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) statement,
+ *  the best way to use it is while running the test scenario via a Node.js debugger.
+ *
+ * @example <caption>Setting a breakpoint to pause the scenario</caption>
+ *  import { actorCalled, Debug } from '@serenity-js/core';
+ *  import { Navigate } from '@serenity-js/web';
+ *
+ *  await actorCalled('Debbie').attemptsTo(
+ *      Navigate.to('http://example.org'),
+ *      Debug.setBreakpoint(),
+ *      // ... other activities
+ *  );
+ *
+ * @example <caption>Debugging Answerable values</caption>
+ *  import { actorCalled, Debug } from '@serenity-js/core';
+ *  import { Navigate, Page } from '@serenity-js/web';
+ *
+ *  // Running the below through the Node.js debugger makes the actor resolve the provided values
+ *  // and return them to the debugger function, where you can investigate their contents,
+ *  // or inspect any Errors the evaluation has resulted with.
+ *  await actorCalled('Debbie').attemptsTo(
+ *      Navigate.to('http://example.org'),
+ *      Debug.values(Page.current().title(), Page.current().url()), // accepts multiple values
+ *  );
+ *
+ * @extends {Interaction}
+ */
+export declare class Debug<Values extends Array<Answerable<unknown>>> extends Interaction {
+    private readonly description;
+    private readonly debuggerFunction;
+    private readonly values;
+    /**
+     * @desc
+     *  Invokes a debugger function that sets a breakpoint.
+     *
+     *   To use this interaction, run your test scenario in the Node.js debugger.
+     *
+     * @returns {Interaction}
+     */
+    static setBreakpoint(): Interaction;
+    /**
+     * @desc
+     *  Instructs the Actor to evaluate the provided `values`,
+     *  log the results, and then pass them to a debugger function.
+     *
+     *  To use this interaction, run your test scenario in the Node.js debugger.
+     *
+     * @param {...items: Array<Answerable<any>>} values
+     *  The values to be debugged
+     *
+     * @returns {Interaction}
+     */
+    static values(...values: Array<Answerable<any>>): Interaction;
+    /**
+     * @param {string} description
+     *  Description of this interaction
+     * @param debuggerFunction
+     *  Callback function to receive the results of debugging
+     * @param {Array<Answerable<any>>} values
+     *  Values to be evaluated by the actor, and provided to debuggerFunction
+     */
+    constructor(description: string, debuggerFunction: (args: {
+        [Index in keyof Values]: DebuggingResult<Answered<Values[Index]>>;
+    }) => void, values: Values);
+    /**
+     * @desc
+     *  Makes the provided {@link Actor}
+     *  perform this {@link Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions & CollectsArtifacts} actor
+     * @returns {Promise<void>}
+     *
+     * @see {@link Actor}
+     * @see {@link UsesAbilities}
+     * @see {@link AnswersQuestions}
+     * @see {@link CollectsArtifacts}
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void>;
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link Activity}.
+     *
+     * @returns {string}
+     */
+    toString(): string;
+}

package/lib/screenplay/interactions/debug/Debug.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Debug = void 0;
+const io_1 = require("../../../io");
+const inspected_1 = require("../../../io/inspected");
+const model_1 = require("../../../model");
+const Interaction_1 = require("../../Interaction");
+const breakpoint_1 = require("./breakpoint");
+const viewer_1 = require("./viewer");
+/**
+ * @desc
+ *  Instructs the {@link Actor} to set a breakpoint and optionally evaluate and log the provided {@link Answerable} values.
+ *
+ *  Since this interaction sets a breakpoint using the [`debugger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) statement,
+ *  the best way to use it is while running the test scenario via a Node.js debugger.
+ *
+ * @example <caption>Setting a breakpoint to pause the scenario</caption>
+ *  import { actorCalled, Debug } from '@serenity-js/core';
+ *  import { Navigate } from '@serenity-js/web';
+ *
+ *  await actorCalled('Debbie').attemptsTo(
+ *      Navigate.to('http://example.org'),
+ *      Debug.setBreakpoint(),
+ *      // ... other activities
+ *  );
+ *
+ * @example <caption>Debugging Answerable values</caption>
+ *  import { actorCalled, Debug } from '@serenity-js/core';
+ *  import { Navigate, Page } from '@serenity-js/web';
+ *
+ *  // Running the below through the Node.js debugger makes the actor resolve the provided values
+ *  // and return them to the debugger function, where you can investigate their contents,
+ *  // or inspect any Errors the evaluation has resulted with.
+ *  await actorCalled('Debbie').attemptsTo(
+ *      Navigate.to('http://example.org'),
+ *      Debug.values(Page.current().title(), Page.current().url()), // accepts multiple values
+ *  );
+ *
+ * @extends {Interaction}
+ */
+class Debug extends Interaction_1.Interaction {
+    /**
+     * @param {string} description
+     *  Description of this interaction
+     * @param debuggerFunction
+     *  Callback function to receive the results of debugging
+     * @param {Array<Answerable<any>>} values
+     *  Values to be evaluated by the actor, and provided to debuggerFunction
+     */
+    constructor(description, debuggerFunction, values) {
+        super();
+        this.description = description;
+        this.debuggerFunction = debuggerFunction;
+        this.values = values;
+    }
+    /**
+     * @desc
+     *  Invokes a debugger function that sets a breakpoint.
+     *
+     *   To use this interaction, run your test scenario in the Node.js debugger.
+     *
+     * @returns {Interaction}
+     */
+    static setBreakpoint() {
+        /* istanbul ignore next can't test using a debugger in an automated test */
+        return new Debug(`#actor sets a breakpoint`, breakpoint_1.breakpoint, []);
+    }
+    /**
+     * @desc
+     *  Instructs the Actor to evaluate the provided `values`,
+     *  log the results, and then pass them to a debugger function.
+     *
+     *  To use this interaction, run your test scenario in the Node.js debugger.
+     *
+     * @param {...items: Array<Answerable<any>>} values
+     *  The values to be debugged
+     *
+     * @returns {Interaction}
+     */
+    static values(...values) {
+        /* istanbul ignore next can't test using a debugger in an automated test */
+        return new Debug(`#actor debugs ${values.length} values`, viewer_1.viewer, values);
+    }
+    /**
+     * @desc
+     *  Makes the provided {@link Actor}
+     *  perform this {@link Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions & CollectsArtifacts} actor
+     * @returns {Promise<void>}
+     *
+     * @see {@link Actor}
+     * @see {@link UsesAbilities}
+     * @see {@link AnswersQuestions}
+     * @see {@link CollectsArtifacts}
+     */
+    async performAs(actor) {
+        const results = [];
+        for (const value of this.values) {
+            const result = {
+                description: (0, io_1.d) `${value}`,
+                value: undefined,
+                error: undefined,
+            };
+            try {
+                result.value = await actor.answer(value);
+            }
+            catch (error) {
+                result.error = error;
+            }
+            actor.collect(model_1.LogEntry.fromJSON({
+                data: JSON.stringify({
+                    value: (0, inspected_1.inspected)(result.value),
+                    error: result.error ? io_1.ErrorSerialiser.serialise(result.error) : result.error
+                }),
+            }), new model_1.Name(result.description));
+            results.push(result);
+        }
+        this.debuggerFunction(results);
+    }
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link Activity}.
+     *
+     * @returns {string}
+     */
+    toString() {
+        return this.description;
+    }
+}
+exports.Debug = Debug;
+//# sourceMappingURL=Debug.js.map

package/lib/screenplay/interactions/debug/Debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Debug.js","sourceRoot":"","sources":["../../../../src/screenplay/interactions/debug/Debug.ts"],"names":[],"mappings":";;;AAAA,oCAAiD;AACjD,qDAAkD;AAClD,0CAAgD;AAIhD,mDAAgD;AAChD,6CAA0C;AAE1C,qCAAkC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAa,KAAiD,SAAQ,yBAAW;IAwC7E;;;;;;;OAOG;IACH,YACqB,WAAmB,EACnB,gBAAyG,EACzG,MAAc;QAE/B,KAAK,EAAE,CAAC;QAJS,gBAAW,GAAX,WAAW,CAAQ;QACnB,qBAAgB,GAAhB,gBAAgB,CAAyF;QACzG,WAAM,GAAN,MAAM,CAAQ;IAGnC,CAAC;IApDD;;;;;;;OAOG;IACH,MAAM,CAAC,aAAa;QAChB,2EAA2E;QAC3E,OAAO,IAAI,KAAK,CACZ,0BAA0B,EAC1B,uBAAU,EACV,EAAE,CACL,CAAC;IACN,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,GAAG,MAA8B;QAC3C,2EAA2E;QAC3E,OAAO,IAAI,KAAK,CACZ,iBAAkB,MAAM,CAAC,MAAO,SAAS,EACzC,eAAM,EACN,MAAM,CACT,CAAC;IACN,CAAC;IAkBD;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,SAAS,CAAC,KAA2D;QACvE,MAAM,OAAO,GAAG,EAA6E,CAAC;QAE9F,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE;YAE7B,MAAM,MAAM,GAA6B;gBACrC,WAAW,EAAE,IAAA,MAAC,EAAA,GAAI,KAAM,EAAE;gBAC1B,KAAK,EAAE,SAAS;gBAChB,KAAK,EAAE,SAAS;aACnB,CAAA;YAED,IAAI;gBACA,MAAM,CAAC,KAAK,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aAC5C;YACD,OAAM,KAAK,EAAE;gBACT,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;aACxB;YAED,KAAK,CAAC,OAAO,CACT,gBAAQ,CAAC,QAAQ,CAAC;gBACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACjB,KAAK,EAAE,IAAA,qBAAS,EAAC,MAAM,CAAC,KAAK,CAAC;oBAC9B,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,oBAAe,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK;iBAC/E,CAAC;aACL,CAAC,EACF,IAAI,YAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAC/B,CAAC;YAEF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;SACvB;QAED,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;CACJ;AAhHD,sBAgHC"}

package/lib/screenplay/interactions/debug/DebuggingResult.d.ts

@@ -0,0 +1,5 @@
+export interface DebuggingResult<T> {
+    description: string;
+    value: T | undefined;
+    error: Error | undefined;
+}

package/lib/screenplay/interactions/debug/DebuggingResult.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=DebuggingResult.js.map

package/lib/screenplay/interactions/debug/DebuggingResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DebuggingResult.js","sourceRoot":"","sources":["../../../../src/screenplay/interactions/debug/DebuggingResult.ts"],"names":[],"mappings":""}

package/lib/screenplay/interactions/debug/breakpoint.d.ts

@@ -0,0 +1 @@
+export declare function breakpoint(): void;

package/lib/screenplay/interactions/debug/breakpoint.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.breakpoint = void 0;
+/* istanbul ignore next */
+function breakpoint() {
+    debugger; // eslint-disable-line no-debugger
+}
+exports.breakpoint = breakpoint;
+//# sourceMappingURL=breakpoint.js.map

package/lib/screenplay/interactions/debug/breakpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoint.js","sourceRoot":"","sources":["../../../../src/screenplay/interactions/debug/breakpoint.ts"],"names":[],"mappings":";;;AAAA,0BAA0B;AAC1B,SAAgB,UAAU;IACtB,QAAQ,CAAC,CAAG,kCAAkC;AAClD,CAAC;AAFD,gCAEC"}

package/lib/screenplay/interactions/debug/index.d.ts

@@ -0,0 +1 @@
+export * from './Debug';

package/lib/screenplay/interactions/debug/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Debug"), exports);
+//# sourceMappingURL=index.js.map

package/lib/screenplay/interactions/debug/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/interactions/debug/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB"}

package/lib/screenplay/interactions/debug/viewer.d.ts

@@ -0,0 +1,6 @@
+import { Answerable } from '../../Answerable';
+import { Answered } from '../../Answered';
+import { DebuggingResult } from './DebuggingResult';
+export declare function viewer<Values extends Array<Answerable<unknown>>>(results: {
+    [Index in keyof Values]: DebuggingResult<Answered<Values[Index]>>;
+}): void;

package/lib/screenplay/interactions/debug/viewer.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.viewer = void 0;
+/* istanbul ignore next */
+function viewer(results) {
+    /**
+     *  Use your debugger to inspect the `results` array.
+     *  Note that every entry in `results` contains:
+     *  - description - a string description produced by invoking d`${ value }` on the original value
+     *  - value - the result of invoking `await actor.answer(value)` on the original value
+     *  - error - `Error`, if thrown when invoking `await actor.answer(value)` on the original value
+     *
+     *  @see {d}
+     *  @see {Actor#answer}
+     */
+    debugger; // eslint-disable-line no-debugger
+}
+exports.viewer = viewer;
+//# sourceMappingURL=viewer.js.map

package/lib/screenplay/interactions/debug/viewer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.js","sourceRoot":"","sources":["../../../../src/screenplay/interactions/debug/viewer.ts"],"names":[],"mappings":";;;AAIA,0BAA0B;AAC1B,SAAgB,MAAM,CAA4C,OAAgF;IAC9I;;;;;;;;;OASG;IACH,QAAQ,CAAC,CAAG,kCAAkC;AAClD,CAAC;AAZD,wBAYC"}

package/lib/screenplay/interactions/index.d.ts

@@ -1,3 +1,4 @@
+export * from './debug';
 export * from './Log';
 export * from './Wait';
 export * from './WaitBuilder';

package/lib/screenplay/interactions/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./debug"), exports);
 __exportStar(require("./Log"), exports);
 __exportStar(require("./Wait"), exports);
 __exportStar(require("./WaitBuilder"), exports);

package/lib/screenplay/interactions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wCAAsB;AACtB,yCAAuB;AACvB,gDAA8B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,wCAAsB;AACtB,yCAAuB;AACvB,gDAA8B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-js/core",
-  "version": "3.0.0-rc.23",
+  "version": "3.0.0-rc.24",
   "description": "Serenity/JS Screenplay, reporting engine and core interfaces.",
   "author": {
     "name": "Jan Molak",
@@ -71,5 +71,5 @@
     "node": "^14 || ^16 || ^18",
     "npm": "^6 || ^7 || ^8"
   },
-  "gitHead": "debd05ecd17b48de66a53afbef8f7aa7f457ba6b"
+  "gitHead": "76443ef557e876727b7dae9ef66d4e6612a3034b"
 }

package/src/screenplay/Answered.ts

@@ -0,0 +1,6 @@
+import { Question } from './Question';
+
+export type Answered<T> =
+    T extends null | undefined ? T :          // special case for `null | undefined` when not in `--strictNullChecks` mode
+        T extends Question<Promise<infer A>> | Question<infer A> | Promise<infer A> ? Awaited<A> :
+            T;

package/src/screenplay/index.ts

@@ -4,6 +4,7 @@ export * from './AbilityType';
 export * from './Activity';
 export * from './actor';
 export * from './Answerable';
+export * from './Answered';
 export * from './Interaction';
 export * from './interactions';
 export * from './notes';

package/src/screenplay/interactions/Log.ts

@@ -1,7 +1,6 @@
-import { formatted } from '../../io';
+import { d } from '../../io';
 import { inspected } from '../../io/inspected';
-import { Name } from '../../model';
-import { LogEntry } from '../../model/artifacts';
+import { LogEntry, Name } from '../../model';
 import { AnswersQuestions, CollectsArtifacts, UsesAbilities } from '../actor';
 import { Answerable } from '../Answerable';
 import { Interaction } from '../Interaction';
@@ -37,7 +36,7 @@ export class Log extends Interaction {
     }
 
     /**
-     * @param {...items: any[]} items
+     * @param {Array<Answerable<any>>} items
      *  The items to be logged
      */
     constructor(
@@ -59,14 +58,16 @@ export class Log extends Interaction {
      * @see {@link AnswersQuestions}
      * @see {@link CollectsArtifacts}
      */
-    performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
-        return Promise
-            .all(this.items.map(item => actor.answer(item)))
-            .then(items =>
-                items.forEach((item, i) =>
-                    actor.collect(LogEntry.fromJSON({ data: inspected(item) }), new Name(inspected(this.items[i]))),
-                ),
+    async performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
+        for (const item of this.items) {
+
+            const data = await actor.answer(item);
+
+            actor.collect(
+                LogEntry.fromJSON({ data: inspected(data) }),
+                new Name(d`${ item }`)
             );
+        }
     }
 
     /**
@@ -76,6 +77,6 @@ export class Log extends Interaction {
      * @returns {string}
      */
     toString(): string {
-        return `#actor logs: ${ this.items.map(item => formatted`${ item }`).join(', ') }`;
+        return `#actor logs: ${ this.items.map(item => d`${ item }`).join(', ') }`;
     }
 }

package/src/screenplay/interactions/debug/Debug.ts

@@ -0,0 +1,155 @@
+import { d, ErrorSerialiser } from '../../../io';
+import { inspected } from '../../../io/inspected';
+import { LogEntry, Name } from '../../../model';
+import { AnswersQuestions, CollectsArtifacts, UsesAbilities } from '../../actor';
+import { Answerable } from '../../Answerable';
+import { Answered } from '../../Answered';
+import { Interaction } from '../../Interaction';
+import { breakpoint } from './breakpoint';
+import { DebuggingResult } from './DebuggingResult';
+import { viewer } from './viewer';
+
+/**
+ * @desc
+ *  Instructs the {@link Actor} to set a breakpoint and optionally evaluate and log the provided {@link Answerable} values.
+ *
+ *  Since this interaction sets a breakpoint using the [`debugger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) statement,
+ *  the best way to use it is while running the test scenario via a Node.js debugger.
+ *
+ * @example <caption>Setting a breakpoint to pause the scenario</caption>
+ *  import { actorCalled, Debug } from '@serenity-js/core';
+ *  import { Navigate } from '@serenity-js/web';
+ *
+ *  await actorCalled('Debbie').attemptsTo(
+ *      Navigate.to('http://example.org'),
+ *      Debug.setBreakpoint(),
+ *      // ... other activities
+ *  );
+ *
+ * @example <caption>Debugging Answerable values</caption>
+ *  import { actorCalled, Debug } from '@serenity-js/core';
+ *  import { Navigate, Page } from '@serenity-js/web';
+ *
+ *  // Running the below through the Node.js debugger makes the actor resolve the provided values
+ *  // and return them to the debugger function, where you can investigate their contents,
+ *  // or inspect any Errors the evaluation has resulted with.
+ *  await actorCalled('Debbie').attemptsTo(
+ *      Navigate.to('http://example.org'),
+ *      Debug.values(Page.current().title(), Page.current().url()), // accepts multiple values
+ *  );
+ *
+ * @extends {Interaction}
+ */
+export class Debug<Values extends Array<Answerable<unknown>>> extends Interaction {
+
+    /**
+     * @desc
+     *  Invokes a debugger function that sets a breakpoint.
+     *
+     *   To use this interaction, run your test scenario in the Node.js debugger.
+     *
+     * @returns {Interaction}
+     */
+    static setBreakpoint(): Interaction {
+        /* istanbul ignore next can't test using a debugger in an automated test */
+        return new Debug<Array<Answerable<any>>>(
+            `#actor sets a breakpoint`,
+            breakpoint,
+            []
+        );
+    }
+
+    /**
+     * @desc
+     *  Instructs the Actor to evaluate the provided `values`,
+     *  log the results, and then pass them to a debugger function.
+     *
+     *  To use this interaction, run your test scenario in the Node.js debugger.
+     *
+     * @param {...items: Array<Answerable<any>>} values
+     *  The values to be debugged
+     *
+     * @returns {Interaction}
+     */
+    static values(...values: Array<Answerable<any>>): Interaction {
+        /* istanbul ignore next can't test using a debugger in an automated test */
+        return new Debug<Array<Answerable<any>>>(
+            `#actor debugs ${ values.length } values`,
+            viewer,
+            values
+        );
+    }
+
+    /**
+     * @param {string} description
+     *  Description of this interaction
+     * @param debuggerFunction
+     *  Callback function to receive the results of debugging
+     * @param {Array<Answerable<any>>} values
+     *  Values to be evaluated by the actor, and provided to debuggerFunction
+     */
+    constructor(
+        private readonly description: string,
+        private readonly debuggerFunction: (args: { [ Index in keyof Values ]: DebuggingResult<Answered<Values[Index]>> }) => void,
+        private readonly values: Values,
+    ) {
+        super();
+    }
+
+    /**
+     * @desc
+     *  Makes the provided {@link Actor}
+     *  perform this {@link Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions & CollectsArtifacts} actor
+     * @returns {Promise<void>}
+     *
+     * @see {@link Actor}
+     * @see {@link UsesAbilities}
+     * @see {@link AnswersQuestions}
+     * @see {@link CollectsArtifacts}
+     */
+    async performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void> {
+        const results = [] as { [ Index in keyof Values ]: DebuggingResult<Answered<Values[Index]>> };
+
+        for (const value of this.values) {
+
+            const result: DebuggingResult<unknown> = {
+                description: d`${ value }`,
+                value: undefined,
+                error: undefined,
+            }
+
+            try {
+                result.value = await actor.answer(value);
+            }
+            catch(error) {
+                result.error = error;
+            }
+
+            actor.collect(
+                LogEntry.fromJSON({
+                    data: JSON.stringify({
+                        value: inspected(result.value),
+                        error: result.error ? ErrorSerialiser.serialise(result.error) : result.error
+                    }),
+                }),
+                new Name(result.description)
+            );
+
+            results.push(result)
+        }
+
+        this.debuggerFunction(results);
+    }
+
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link Activity}.
+     *
+     * @returns {string}
+     */
+    toString(): string {
+        return this.description;
+    }
+}

package/src/screenplay/interactions/debug/DebuggingResult.ts

@@ -0,0 +1,5 @@
+export interface DebuggingResult<T> {
+    description: string;
+    value: T | undefined;
+    error: Error | undefined;
+}

package/src/screenplay/interactions/debug/breakpoint.ts

@@ -0,0 +1,4 @@
+/* istanbul ignore next */
+export function breakpoint(): void {
+    debugger;   // eslint-disable-line no-debugger
+}

package/src/screenplay/interactions/debug/index.ts

@@ -0,0 +1 @@
+export * from './Debug';

package/src/screenplay/interactions/debug/viewer.ts

@@ -0,0 +1,18 @@
+import { Answerable } from '../../Answerable';
+import { Answered } from '../../Answered';
+import { DebuggingResult } from './DebuggingResult';
+
+/* istanbul ignore next */
+export function viewer<Values extends Array<Answerable<unknown>>>(results: { [ Index in keyof Values ]: DebuggingResult<Answered<Values[Index]>> }): void {
+    /**
+     *  Use your debugger to inspect the `results` array.
+     *  Note that every entry in `results` contains:
+     *  - description - a string description produced by invoking d`${ value }` on the original value
+     *  - value - the result of invoking `await actor.answer(value)` on the original value
+     *  - error - `Error`, if thrown when invoking `await actor.answer(value)` on the original value
+     *
+     *  @see {d}
+     *  @see {Actor#answer}
+     */
+    debugger;   // eslint-disable-line no-debugger
+}

package/src/screenplay/interactions/index.ts

@@ -1,3 +1,4 @@
+export * from './debug';
 export * from './Log';
 export * from './Wait';
 export * from './WaitBuilder';