@serenity-js/core 3.41.1 → 3.42.0

package/esm/screenplay/questions/Unanswered.js

@@ -0,0 +1,31 @@
+import util from 'node:util';
+import { TinyType } from 'tiny-types';
+/**
+ * A placeholder value signifying that a [`Question`](https://serenity-js.org/api/core/class/Question/)
+ * has not been answered by an [`Actor`](https://serenity-js.org/api/core/class/Actor/) when producing an [`ExpectationOutcome`](https://serenity-js.org/api/core/class/ExpectationOutcome/).
+ * This happens when Serenity/JS decides that answering a given question
+ * won't affect the outcome.
+ *
+ * For example, making the actor answer questions about the expected value
+ * and the actual value of each list item is unnecessary if we already know that the list itself is empty.
+ *
+ * @group Questions
+ */
+export class Unanswered extends TinyType {
+    constructor() {
+        super();
+    }
+    static isUnanswered(value) {
+        return value instanceof Unanswered;
+    }
+    [util.inspect.custom]() {
+        return `<<unanswered>>`;
+    }
+    toString() {
+        return 'unanswered';
+    }
+    toJSON() {
+        return undefined;
+    }
+}
+//# sourceMappingURL=Unanswered.js.map

package/esm/screenplay/questions/Unanswered.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Unanswered.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Unanswered.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,OAAO,UAAW,SAAQ,QAAQ;IAEpC;QACI,KAAK,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,KAAc;QAC9B,OAAO,KAAK,YAAY,UAAU,CAAC;IACvC,CAAC;IAED,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACjB,OAAO,gBAAgB,CAAC;IAC5B,CAAC;IAED,QAAQ;QACJ,OAAO,YAAY,CAAC;IACxB,CAAC;IAED,MAAM;QACF,OAAO,SAAS,CAAC;IACrB,CAAC;CACJ"}

package/esm/screenplay/questions/expectations/ExpectationDetails.d.ts

@@ -0,0 +1,25 @@
+import type { JSONObject, JSONValue } from 'tiny-types';
+import { TinyType } from 'tiny-types';
+import { Name } from '../../../model/index.js';
+import { Unanswered } from '../Unanswered.js';
+/**
+ * Used with [`ExpectationOutcome`](https://serenity-js.org/api/core/class/ExpectationOutcome/) to describe an [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) and the arguments it's been executed with.
+ *
+ * @group Expectations
+ */
+export declare class ExpectationDetails extends TinyType {
+    readonly name: Name;
+    readonly args: Array<JSONValue | ExpectationDetails | Unanswered>;
+    static of(functionName: string, ...functionArguments: Array<JSONValue | ExpectationDetails | Unanswered>): ExpectationDetails;
+    static fromJSON(o: JSONObject): ExpectationDetails;
+    protected constructor(name: Name, args: Array<JSONValue | ExpectationDetails | Unanswered>);
+    toString(): string;
+    toJSON(): {
+        name: string;
+        args: Array<{
+            type: string;
+            value: JSONValue;
+        }>;
+    };
+}
+//# sourceMappingURL=ExpectationDetails.d.ts.map

package/esm/screenplay/questions/expectations/ExpectationDetails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationDetails.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationDetails.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAC,MAAM,YAAY,CAAC;AACvD,OAAO,EAA8B,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGlE,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;aAuBxB,IAAI,EAAE,IAAI;aACV,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,kBAAkB,GAAG,UAAU,CAAC;IAtB5E,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,iBAAiB,EAAE,KAAK,CAAC,SAAS,GAAG,kBAAkB,GAAG,UAAU,CAAC,GAAG,kBAAkB;IAI7H,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,UAAU,GAAG,kBAAkB;IAgBlD,SAAS,aACW,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,kBAAkB,GAAG,UAAU,CAAC;IAO5E,QAAQ,IAAI,MAAM;IAUlB,MAAM,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,SAAS,CAAA;SAAE,CAAC,CAAA;KAAE;CAW9E"}

package/esm/screenplay/questions/expectations/ExpectationDetails.js

@@ -0,0 +1,53 @@
+import { ensure, isArray, isDefined, TinyType } from 'tiny-types';
+import { inspected, ValueInspector } from '../../../io/index.js';
+import { Name } from '../../../model/index.js';
+import { Unanswered } from '../Unanswered.js';
+/**
+ * Used with [`ExpectationOutcome`](https://serenity-js.org/api/core/class/ExpectationOutcome/) to describe an [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) and the arguments it's been executed with.
+ *
+ * @group Expectations
+ */
+export class ExpectationDetails extends TinyType {
+    name;
+    args;
+    static of(functionName, ...functionArguments) {
+        return new ExpectationDetails(new Name(functionName), functionArguments);
+    }
+    static fromJSON(o) {
+        return new ExpectationDetails(Name.fromJSON(o.name), o.args.map(arg => {
+            if (arg.type === Unanswered.name) {
+                return new Unanswered();
+            }
+            if (arg.type === ExpectationDetails.name) {
+                return ExpectationDetails.fromJSON(arg.value);
+            }
+            // must be a JSONValue then
+            return arg.value;
+        }));
+    }
+    constructor(name, args) {
+        super();
+        this.name = name;
+        this.args = args;
+        ensure('name', name, isDefined());
+        ensure('args', args, isArray());
+    }
+    toString() {
+        const argumentValues = this.args.map(arg => arg instanceof ExpectationDetails
+            ? arg.toString()
+            : inspected(arg, { compact: true })).join(', ');
+        return `${this.name.value}(${argumentValues})`;
+    }
+    toJSON() {
+        return {
+            name: this.name.value,
+            args: this.args.map(arg => ({
+                type: ValueInspector.typeOf(arg),
+                value: arg['toJSON']
+                    ? arg.toJSON()
+                    : arg,
+            })),
+        };
+    }
+}
+//# sourceMappingURL=ExpectationDetails.js.map

package/esm/screenplay/questions/expectations/ExpectationDetails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationDetails.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationDetails.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAElE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,QAAQ;IAuBxB;IACA;IAtBpB,MAAM,CAAC,EAAE,CAAC,YAAoB,EAAE,GAAG,iBAAqE;QACpG,OAAO,IAAI,kBAAkB,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,CAAa;QACzB,OAAO,IAAI,kBAAkB,CACzB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAc,CAAC,EAC9B,CAAC,CAAC,IAAkD,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;YAC5D,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC,IAAI,EAAE,CAAC;gBAC/B,OAAO,IAAI,UAAU,EAAE,CAAC;YAC5B,CAAC;YACD,IAAI,GAAG,CAAC,IAAI,KAAK,kBAAkB,CAAC,IAAI,EAAE,CAAC;gBACvC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAmB,CAAC,CAAA;YAC/D,CAAC;YACD,2BAA2B;YAC3B,OAAO,GAAG,CAAC,KAAK,CAAC;QACrB,CAAC,CAAC,CACL,CAAC;IACN,CAAC;IAED,YACoB,IAAU,EACV,IAAwD;QAExE,KAAK,EAAE,CAAC;QAHQ,SAAI,GAAJ,IAAI,CAAM;QACV,SAAI,GAAJ,IAAI,CAAoD;QAGxE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,QAAQ;QACJ,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CACvC,GAAG,YAAY,kBAAkB;YAC7B,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;YAChB,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,OAAO,GAAI,IAAI,CAAC,IAAI,CAAC,KAAM,IAAK,cAAe,GAAG,CAAC;IACvD,CAAC;IAED,MAAM;QACF,OAAO;YACH,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACxB,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC;gBAChC,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC;oBAChB,CAAC,CAAE,GAAW,CAAC,MAAM,EAAE;oBACvB,CAAC,CAAC,GAAG;aACZ,CAAC,CAAC;SACN,CAAA;IACL,CAAC;CACJ"}

package/esm/screenplay/questions/expectations/ExpectationMet.d.ts

@@ -0,0 +1,9 @@
+import { ExpectationOutcome } from './ExpectationOutcome.js';
+/**
+ * Indicates that an [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) was met.
+ *
+ * @group Expectations
+ */
+export declare class ExpectationMet extends ExpectationOutcome {
+}
+//# sourceMappingURL=ExpectationMet.d.ts.map

package/esm/screenplay/questions/expectations/ExpectationMet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationMet.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationMet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;CAAG"}

package/esm/screenplay/questions/expectations/ExpectationMet.js

@@ -0,0 +1,9 @@
+import { ExpectationOutcome } from './ExpectationOutcome.js';
+/**
+ * Indicates that an [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) was met.
+ *
+ * @group Expectations
+ */
+export class ExpectationMet extends ExpectationOutcome {
+}
+//# sourceMappingURL=ExpectationMet.js.map

package/esm/screenplay/questions/expectations/ExpectationMet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationMet.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationMet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,kBAAkB;CAAG"}

package/esm/screenplay/questions/expectations/ExpectationNotMet.d.ts

@@ -0,0 +1,9 @@
+import { ExpectationOutcome } from './ExpectationOutcome.js';
+/**
+ * Indicates that an [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) was not met.
+ *
+ * @group Expectations
+ */
+export declare class ExpectationNotMet extends ExpectationOutcome {
+}
+//# sourceMappingURL=ExpectationNotMet.d.ts.map

package/esm/screenplay/questions/expectations/ExpectationNotMet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationNotMet.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationNotMet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;CAAG"}

package/esm/screenplay/questions/expectations/ExpectationNotMet.js

@@ -0,0 +1,9 @@
+import { ExpectationOutcome } from './ExpectationOutcome.js';
+/**
+ * Indicates that an [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) was not met.
+ *
+ * @group Expectations
+ */
+export class ExpectationNotMet extends ExpectationOutcome {
+}
+//# sourceMappingURL=ExpectationNotMet.js.map

package/esm/screenplay/questions/expectations/ExpectationNotMet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationNotMet.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationNotMet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,kBAAkB;CAAG"}

package/esm/screenplay/questions/expectations/ExpectationOutcome.d.ts

@@ -0,0 +1,16 @@
+import { TinyType } from 'tiny-types';
+import type { ExpectationDetails } from './ExpectationDetails.js';
+/**
+ * An outcome of an [`Expectation`](https://serenity-js.org/api/core/class/Expectation/),
+ * which could be either [met](https://serenity-js.org/api/core/class/ExpectationMet/) or [not met](https://serenity-js.org/api/core/class/ExpectationNotMet/).
+ *
+ * @group Expectations
+ */
+export declare class ExpectationOutcome extends TinyType {
+    readonly message: string;
+    readonly expectation: ExpectationDetails;
+    readonly expected: unknown;
+    readonly actual: unknown;
+    constructor(message: string, expectation: ExpectationDetails, expected: unknown, actual: unknown);
+}
+//# sourceMappingURL=ExpectationOutcome.d.ts.map

package/esm/screenplay/questions/expectations/ExpectationOutcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationOutcome.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationOutcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;aAExB,OAAO,EAAE,MAAM;aACf,WAAW,EAAE,kBAAkB;aAC/B,QAAQ,EAAE,OAAO;aACjB,MAAM,EAAE,OAAO;gBAHf,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,kBAAkB,EAC/B,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,OAAO;CAItC"}

package/esm/screenplay/questions/expectations/ExpectationOutcome.js

@@ -0,0 +1,21 @@
+import { TinyType } from 'tiny-types';
+/**
+ * An outcome of an [`Expectation`](https://serenity-js.org/api/core/class/Expectation/),
+ * which could be either [met](https://serenity-js.org/api/core/class/ExpectationMet/) or [not met](https://serenity-js.org/api/core/class/ExpectationNotMet/).
+ *
+ * @group Expectations
+ */
+export class ExpectationOutcome extends TinyType {
+    message;
+    expectation;
+    expected;
+    actual;
+    constructor(message, expectation, expected, actual) {
+        super();
+        this.message = message;
+        this.expectation = expectation;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+//# sourceMappingURL=ExpectationOutcome.js.map

package/esm/screenplay/questions/expectations/ExpectationOutcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpectationOutcome.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/ExpectationOutcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,QAAQ;IAExB;IACA;IACA;IACA;IAJpB,YACoB,OAAe,EACf,WAA+B,EAC/B,QAAiB,EACjB,MAAe;QAE/B,KAAK,EAAE,CAAC;QALQ,YAAO,GAAP,OAAO,CAAQ;QACf,gBAAW,GAAX,WAAW,CAAoB;QAC/B,aAAQ,GAAR,QAAQ,CAAS;QACjB,WAAM,GAAN,MAAM,CAAS;IAGnC,CAAC;CACJ"}

package/esm/screenplay/questions/expectations/index.d.ts

@@ -0,0 +1,5 @@
+export * from './ExpectationDetails.js';
+export * from './ExpectationMet.js';
+export * from './ExpectationNotMet.js';
+export * from './ExpectationOutcome.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/screenplay/questions/expectations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC"}

package/esm/screenplay/questions/expectations/index.js

@@ -0,0 +1,5 @@
+export * from './ExpectationDetails.js';
+export * from './ExpectationMet.js';
+export * from './ExpectationNotMet.js';
+export * from './ExpectationOutcome.js';
+//# sourceMappingURL=index.js.map

package/esm/screenplay/questions/expectations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/questions/expectations/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC"}

package/esm/screenplay/questions/index.d.ts

@@ -0,0 +1,14 @@
+export * from './AnswersQuestions.js';
+export * from './ChainableMetaQuestion.js';
+export * from './Check.js';
+export * from './Describable.js';
+export * from './DescriptionFormattingOptions.js';
+export * from './Expectation.js';
+export * from './expectations/index.js';
+export * from './List.js';
+export * from './Masked.js';
+export * from './MetaQuestion.js';
+export * from './Numeric.js';
+export * from './tag-functions.js';
+export * from './Unanswered.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/screenplay/questions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mCAAmC,CAAC;AAClD,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/esm/screenplay/questions/index.js

@@ -0,0 +1,14 @@
+export * from './AnswersQuestions.js';
+export * from './ChainableMetaQuestion.js';
+export * from './Check.js';
+export * from './Describable.js';
+export * from './DescriptionFormattingOptions.js';
+export * from './Expectation.js';
+export * from './expectations/index.js';
+export * from './List.js';
+export * from './Masked.js';
+export * from './MetaQuestion.js';
+export * from './Numeric.js';
+export * from './tag-functions.js';
+export * from './Unanswered.js';
+//# sourceMappingURL=index.js.map

package/esm/screenplay/questions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/questions/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mCAAmC,CAAC;AAClD,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/esm/screenplay/questions/tag-functions.d.ts

@@ -0,0 +1,230 @@
+import type { Answerable } from '../Answerable.js';
+import type { MetaQuestionAdapter, QuestionAdapter } from '../Question.js';
+import type { DescriptionFormattingOptions } from './DescriptionFormattingOptions.js';
+import type { MetaQuestion } from './MetaQuestion.js';
+/**
+ * Creates a single-line description of an [`Activity`](https://serenity-js.org/api/core/class/Activity/) by transforming
+ * a [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates),
+ * parameterised with [primitive data types](https://developer.mozilla.org/en-US/docs/Glossary/Primitive),
+ * [complex data structures](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects),
+ * or any other [answerables](https://serenity-js.org/api/core/#Answerable),
+ * into a [`QuestionAdapter<string>`](https://serenity-js.org/api/core/#QuestionAdapter)
+ * that can be used with [`Task.where`](https://serenity-js.org/api/core/class/Task/#where) and [`Interaction.where`](https://serenity-js.org/api/core/class/Interaction/#where) methods.
+ *
+ * ```ts
+ * const dial = (phoneNumber: Answerable<string>) =>
+ *  Task.where(the `#actor dials ${ phoneNumber }`, /* *\/)
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   dial('(555) 123-4567'),
+ *   // reported as: Alice dials "(555) 123-4567"
+ * )
+ * ```
+ *
+ * ## Trimming the output
+ *
+ * Use [`DescriptionFormattingOptions`](http://serenity-js.org/api/core/interface/DescriptionFormattingOptions/)
+ * to trim the descriptions of template parameters.
+ * By default, the output is displayed in full.
+ *
+ * ```ts
+ * import { actorCalled, Task, the } from '@serenity-js/core'
+ *
+ * const dial = (phoneNumber: Answerable<string>) =>
+ *  Task.where(dial({ maxLength: 10 }) `#actor dials ${ phoneNumber }`, /* *\/)
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   dial('(555) 123-4567'),
+ *   // reported as: Alice dials "(555) 123-...'
+ * )
+ * ```
+ *
+ * ## Using with Questions
+ *
+ * When `the` is parameterised with [questions](https://serenity-js.org/api/core/class/Question/),
+ * it retrieves their description by calling [`Question.describedBy`](https://serenity-js.org/api/core/class/Question/#describedBy)
+ * in the context of the [`Actor`](https://serenity-js.org/api/core/class/Actor/) performing the [`Activity`](https://serenity-js.org/api/core/class/Activity/).
+ *
+ * ```ts
+ * import { actorCalled, Question, Task, the } from '@serenity-js/core'
+ *
+ * const phoneNumber = (areaCode: string, centralOfficeCode: string, lineNumber: string) =>
+ *  Question.about('phone number', actor => {
+ *     return `(${ this.areaCode }) ${ this.centralOfficeCode }-${ this.lineNumber }`
+ *   })
+ *
+ * const dial = (phoneNumber: Answerable<string>) =>
+ *  Task.where(dial({ maxLength: 10 }) `#actor dials ${ phoneNumber }`, /* *\/)
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   dial(phoneNumber('555', '123', '4567'),
+ *   // reported as: Alice dials phone number
+ * )
+ * ```
+ *
+ * If you'd like the question to be described using its formatted value instead of its description, use [`Question.formattedValue`](https://serenity-js.org/api/core/class/Question/#formattedValue).
+ *
+ * ```ts
+ * import { actorCalled, Question, Task, the } from '@serenity-js/core'
+ *
+ * const phoneNumber = (areaCode: string, centralOfficeCode: string, lineNumber: string) =>
+ *   Question.about('phone number', actor => {
+ *     return `(${ this.areaCode }) ${ this.centralOfficeCode }-${ this.lineNumber }`
+ *   }).describedAs(Question.formattedValue())
+ *
+ * const dial = (phoneNumber: Answerable<string>) =>
+ *  Task.where(dial({ maxLength: 10 }) `#actor dials ${ phoneNumber }`, /* *\/)
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   dial(phoneNumber('555', '123', '4567'),
+ *   // reported as: Alice dials "(555) 123-4567"
+ * )
+ * ```
+ *
+ * ## Using with objects with a custom `toString` method
+ *
+ * When `the` is parameterised with objects that have
+ * a custom [`toString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) method,
+ * or [answerables](https://serenity-js.org/api/core/#Answerable) resolving to such objects, the `toString()` method is called to produce the resulting description.
+ *
+ * ```ts
+ * import { actorCalled, description, Task } from '@serenity-js/core'
+ *
+ * class PhoneNumber {
+ *   constructor(
+ *     private readonly areaCode: string,
+ *     private readonly centralOfficeCode: string,
+ *     private readonly lineNumber: string,
+ *   ) {}
+ *
+ *   toString() {
+ *     return `(${ this.areaCode }) ${ this.centralOfficeCode }-${ this.lineNumber }`
+ *   }
+ * }
+ *
+ * const dial = (phoneNumber: Answerable<PhoneNumber>) =>
+ *  Task.where(description `#actor dials ${ phoneNumber }`, /* *\/)
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   dial(new PhoneNumber('555', '123', '4567')),
+ *   // reported as: Alice dials (555) 123-4567
+ * )
+ * ```
+ *
+ * ## Using with objects without a custom `toString` method
+ *
+ * When `the` is parameterised with complex objects that don't have a custom `toString()` method,
+ * or [`Answerable`](https://serenity-js.org/api/core/#Answerable)s resolving to such objects,
+ * the resulting description will contain a JSON-like string representation of the object.
+ *
+ * ```ts
+ * import { actorCalled, description, Task } from '@serenity-js/core'
+ *
+ * interface PhoneNumber {
+ *   areaCode: string;
+ *   centralOfficeCode: string;
+ *   lineNumber: string;
+ * }
+ *
+ * const dial = (phoneNumber: Answerable<PhoneNumber>) =>
+ *  Task.where(the `#actor dials ${ phoneNumber }`, /* *\/)
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   dial({ areaCode: '555', centralOfficeCode: '123', lineNumber: '4567' }),
+ *   // reported as: Alice dials { areaCode: "555", centralOfficeCode: "123", lineNumber: "4567" }
+ * )
+ * ```
+ *
+ * ## Using with masked values
+ *
+ * When `the` is parameterised with [masked values](https://serenity-js.org/api/core/class/Masked/),
+ * the resulting description will contain a masked representation of the values.
+ *
+ * ```ts
+ * import { actorCalled, description, Task } from '@serenity-js/core'
+ *
+ * const dial = (phoneNumber: Answerable<string>) =>
+ *  Task.where(description `#actor dials ${ phoneNumber }`, /* *\/)
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   dial(Masked.valueOf('(555) 123-4567')),
+ *   // reported as: Alice dials [a masked value]
+ * )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+ * - [`Question`](https://serenity-js.org/api/core/class/Question/)
+ * - [`Question.describedAs`](https://serenity-js.org/api/core/class/Question/#describedAs)
+ * - [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ * - [`Masked`](https://serenity-js.org/api/core/class/Masked/)
+ *
+ * @group Questions
+ */
+export declare function the(options: DescriptionFormattingOptions): <Supported_Context_Type>(templates: TemplateStringsArray, ...placeholders: Array<MetaQuestion<Supported_Context_Type, any> | any>) => MetaQuestionAdapter<Supported_Context_Type, string>;
+export declare function the<Supported_Context_Type>(templates: TemplateStringsArray, ...parameters: Array<MetaQuestion<Supported_Context_Type, any> | any>): MetaQuestionAdapter<Supported_Context_Type, string>;
+/**
+ * A Serenity/JS Screenplay Pattern-flavour
+ * of a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates),
+ * `q` is a tag function capable of resolving any `Answerable<string>` or `Answerable<number>`
+ * you parametrise it with, and returning a `QuestionAdapter<string>`.
+ *
+ * Use `q` to concatenate `string` and `number` values returned from synchronous and asynchronous sources.
+ *
+ * ## Interpolating questions
+ *
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ * import { Text } from '@serenity-js/web'
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`
+ *   ))
+ * )
+ * ```
+ *
+ * ## Using a custom description
+ *
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`.describedAs('/articles/:id')
+ *   ))
+ * )
+ * ```
+ *
+ * ## Transforming the interpolated string
+ *
+ * The mechanism presented below relies on [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter).
+ *
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`.toLocaleLowerCase()
+ *   ))
+ * )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+ * - [`Question`](https://serenity-js.org/api/core/class/Question/)
+ * - [`Question.describedAs`](https://serenity-js.org/api/core/class/Question/#describedAs)
+ * - [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ *
+ * @group Questions
+ *
+ * @param templates
+ * @param parameters
+ */
+export declare function q(templates: TemplateStringsArray, ...parameters: Array<Answerable<string | number>>): QuestionAdapter<string>;
+//# sourceMappingURL=tag-functions.d.ts.map

package/esm/screenplay/questions/tag-functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-functions.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/tag-functions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI3E,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+JG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,4BAA4B,GAAG,CAAC,sBAAsB,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC,sBAAsB,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,KAAK,mBAAmB,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAA;AACrP,wBAAgB,GAAG,CAAC,sBAAsB,EAAE,SAAS,EAAE,oBAAoB,EAAE,GAAG,UAAU,EAAE,KAAK,CAAC,YAAY,CAAC,sBAAsB,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,mBAAmB,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAA;AAYxM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAgB,CAAC,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAc7H"}

package/esm/screenplay/questions/tag-functions.js

@@ -0,0 +1,110 @@
+import { asyncMap, ValueInspector } from '../../io/index.js';
+import { Question } from '../Question.js';
+import { Describable } from './Describable.js';
+export function the(...args) {
+    if (ValueInspector.isPlainObject(args[0])) {
+        const descriptionFormattingOptions = args[0];
+        return (templates, ...parameters) => templateToQuestion(templates, parameters, createParameterToDescriptionMapper(descriptionFormattingOptions), createParameterValueToDescriptionMapper(descriptionFormattingOptions));
+    }
+    return templateToQuestion(args[0], args.slice(1), createParameterToDescriptionMapper(), createParameterValueToDescriptionMapper());
+}
+/**
+ * A Serenity/JS Screenplay Pattern-flavour
+ * of a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates),
+ * `q` is a tag function capable of resolving any `Answerable<string>` or `Answerable<number>`
+ * you parametrise it with, and returning a `QuestionAdapter<string>`.
+ *
+ * Use `q` to concatenate `string` and `number` values returned from synchronous and asynchronous sources.
+ *
+ * ## Interpolating questions
+ *
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ * import { Text } from '@serenity-js/web'
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`
+ *   ))
+ * )
+ * ```
+ *
+ * ## Using a custom description
+ *
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`.describedAs('/articles/:id')
+ *   ))
+ * )
+ * ```
+ *
+ * ## Transforming the interpolated string
+ *
+ * The mechanism presented below relies on [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter).
+ *
+ * ```ts
+ * import { q, actorCalled } from '@serenity-js/core'
+ * import { Send, DeleteRequest } from '@serenity-js/rest'
+ *
+ * await actorCalled('Alice').attemptsTo(
+ *   Send.a(DeleteRequest.to(
+ *     q `/articles/${ Text.of(Article.id()) }`.toLocaleLowerCase()
+ *   ))
+ * )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+ * - [`Question`](https://serenity-js.org/api/core/class/Question/)
+ * - [`Question.describedAs`](https://serenity-js.org/api/core/class/Question/#describedAs)
+ * - [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter)
+ *
+ * @group Questions
+ *
+ * @param templates
+ * @param parameters
+ */
+export function q(templates, ...parameters) {
+    return templateToQuestion(templates, parameters, (parameter) => {
+        // return static string and number parameter values as is
+        if (typeof parameter === 'string' || typeof parameter === 'number') {
+            return String(parameter);
+        }
+        // for Questions, Promises and other Answerables, return their description
+        return `{${createParameterToDescriptionMapper()(parameter)}}`;
+    }, createParameterValueMapper());
+}
+function createParameterToDescriptionMapper(options) {
+    return (parameter) => parameter === undefined
+        ? 'undefined'
+        : Question.formattedValue(options).of(parameter).toString();
+}
+function createParameterValueToDescriptionMapper(options) {
+    return async (actor, parameter) => parameter instanceof Describable
+        ? parameter.describedBy(actor)
+        : actor.answer(Question.formattedValue(options).of(parameter));
+}
+function createParameterValueMapper() {
+    return async (actor, parameter) => actor.answer(parameter);
+}
+function templateToQuestion(templates, parameters, descriptionMapper, valueMapper) {
+    const description = interpolate(templates, parameters.map(parameter => descriptionMapper(parameter)));
+    return Question.about(description, async (actor) => {
+        const descriptions = await asyncMap(parameters, parameter => valueMapper(actor, parameter));
+        return interpolate(templates, descriptions);
+    }, (context) => templateToQuestion(templates, parameters.map(parameter => Question.isAMetaQuestion(parameter)
+        ? parameter.of(context)
+        : parameter), descriptionMapper, valueMapper));
+}
+function interpolate(templates, parameters) {
+    return templates.flatMap((template, i) => i < parameters.length
+        ? [template, parameters[i]]
+        : [template]).join('');
+}
+//# sourceMappingURL=tag-functions.js.map

package/esm/screenplay/questions/tag-functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-functions.js","sourceRoot":"","sources":["../../../src/screenplay/questions/tag-functions.ts"],"names":[],"mappings":"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"}