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

package/lib/screenplay/questions/Expectation.js

@@ -4,98 +4,224 @@ exports.Expectation = void 0;
 const io_1 = require("../../io");
 const __1 = require("../");
 /**
- * @desc
- *  Defines an expectation to be used with [assertions](/modules/assertions)
- *  and {@link Question}s like {@link List}.
+ * Defines an expectation to be used with {@apilink @apilink Wait.until}, {@apilink Check.whether}, {@apilink Ensure.that}
+ * and as part of the Page Element Query Language with {@apilink PageElements.where} and {@apilink List.where}.
  *
- * @extends {Question}
+ * @group Expectations
  */
 class Expectation {
-    constructor(subject, predicate) {
-        this.subject = subject;
-        this.predicate = predicate;
+    /**
+     * A factory method to that makes defining custom {@apilink Expectation|expectations} easier
+     *
+     * #### Defining a custom expectation
+     *
+     * ```ts
+     * import { Expectation } from '@serenity-js/core'
+     * import { PageElement } from '@serenity-js/web'
+     *
+     * const isEmpty = Expectation.define(
+     *   'isEmpty',         // name of the expectation function to be used when producing an AssertionError
+     *   'become empty',    // human-readable description of the relationship between expected and actual values
+     *   async (actual: PageElement) => {
+     *     const value = await actual.value();
+     *     return value.length === 0;
+     *   }
+     * )
+     * ```
+     *
+     * #### Using a custom expectation in an assertion
+     *
+     * ```ts
+     * import { Ensure } from '@serenity-js/assertions'
+     * import { actorCalled } from '@serenity-js/core'
+     * import { By, Clear, PageElement } from '@serenity-js/web'
+     *
+     * const nameField = () =>
+     *   PageElement.located(By.css('[data-test-id="name"]')).describedAs('name field');
+     *
+     * await actorCalled('Izzy').attemptsTo(
+     *   Clear.the(nameField()),
+     *   Ensure.that(nameField(), isEmpty())
+     * )
+     * ```
+     *
+     * #### Using a custom expectation in a control flow statement
+     *
+     * ```ts
+     * import { not } from '@serenity-js/assertions'
+     * import { actorCalled, Check, Duration, Wait } from '@serenity-js/core'
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * const nameField = () =>
+     *   PageElement.located(By.css('[data-test-id="name"]')).describedAs('name field');
+     *
+     * await actorCalled('Izzy').attemptsTo(
+     *   Check.whether(nameField(), isEmpty())
+     *     .andIfSo(
+     *       Enter.theValue(actorInTheSpotlight().name).into(nameField()),
+     *     ),
+     * )
+     * ```
+     *
+     * #### Using a custom expectation in a synchronisation statement
+     *
+     * ```ts
+     * import { not } from '@serenity-js/assertions'
+     * import { actorCalled, Duration, Wait } from '@serenity-js/core'
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * const nameField = () =>
+     *   PageElement.located(By.css('[data-test-id="name"]')).describedAs('name field');
+     *
+     * await actorCalled('Izzy').attemptsTo(
+     *   Enter.theValue(actorInTheSpotlight().name).into(nameField()),
+     *
+     *   Wait.upTo(Duration.ofSeconds(2))
+     *     .until(nameField(), not(isEmpty())),
+     * )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Ensure}
+     * - {@apilink Check}
+     * - {@apilink Wait}
+     *
+     * @param functionName
+     *  Name of the expectation function to be used when producing an {@apilink AssertionError}
+     *
+     * @param relationship
+     *  Human-readable description of the relationship between the `expected` and the `actual` values.
+     *  Used when reporting {@apilink Activity|activities} performed by an {@apilink Actor|actor}
+     *
+     * @param predicate
+     */
+    static define(functionName, relationship, predicate) {
+        return Object.defineProperty(function (...answerableArguments) {
+            const description = typeof relationship === 'function' ? relationship(...answerableArguments)
+                : (answerableArguments.length === 1 ? relationship.trim() + (0, io_1.d) ` ${answerableArguments[0]}`
+                    : relationship);
+            return new Expectation(functionName, description, async (actor, actualValue) => {
+                const predicateArguments = await (0, io_1.asyncMap)(answerableArguments, answerableArgument => actor.answer(answerableArgument));
+                const actual = await actor.answer(actualValue);
+                const result = await predicate(actual, ...predicateArguments);
+                const expectationDetails = __1.ExpectationDetails.of(functionName, ...predicateArguments);
+                const expected = predicateArguments.length > 0
+                    ? predicateArguments[0]
+                    : true; // the only parameter-less expectations are boolean ones like `isPresent`, `isActive`, etc.
+                return result
+                    ? new __1.ExpectationMet(description, expectationDetails, expected, actual)
+                    : new __1.ExpectationNotMet(description, expectationDetails, expected, actual);
+            });
+        }, 'name', { value: functionName, writable: false });
     }
     /**
-     * @desc
-     *  Used to define a simple {@link Expectation}
+     * Used to define a simple {@apilink Expectation}
+     *
+     * #### Simple parameterised expectation
      *
-     * @example
-     *  import { actorCalled, Expectation } from '@serenity-js/core';
-     *  import { Ensure } from '@serenity-js/assertions';
+     * ```ts
+     *  import { actorCalled, Expectation } from '@serenity-js/core'
+     *  import { Ensure } from '@serenity-js/assertions'
      *
      *  function isDivisibleBy(expected: Answerable<number>): Expectation<number> {
      *      return Expectation.thatActualShould<number, number>('have value divisible by', expected)
      *          .soThat((actualValue, expectedValue) => actualValue % expectedValue === 0);
      *  }
      *
-     *  actorCalled('Erica').attemptsTo(
+     *  await actorCalled('Erica').attemptsTo(
      *      Ensure.that(4, isDivisibleBy(2)),
-     *  );
+     *  )
+     * ```
      *
-     * @param {string} relationshipName
-     * @param {@serenity-js/core/lib/screenplay~Answerable<E>} expectedValue
+     * @param relationshipName
+     *  Name of the relationship between the `actual` and the `expected`. Use format `have value <adjective>`
+     *  so that the description works in both positive and negative contexts, e.g. `Waited until 5 does have value greater than 2`,
+     *  `Expected 5 to not have value greater than 2`.
      *
-     * @returns {"soThat": function(predicate: Predicate<Expected, Actual>): Expectation<Expected, Actual>}
+     * @param expectedValue
      */
     static thatActualShould(relationshipName, expectedValue) {
         return ({
             soThat: (simplifiedPredicate) => {
-                const subject = relationshipName + ' ' + (0, io_1.d) `${expectedValue}`;
-                return new Expectation(subject, async (actor, actualValue) => {
+                const message = relationshipName + ' ' + (0, io_1.d) `${expectedValue}`;
+                return new Expectation('unknown', message, async (actor, actualValue) => {
                     const expected = await actor.answer(expectedValue);
                     const actual = await actor.answer(actualValue);
                     const result = await simplifiedPredicate(actual, expected);
+                    const expectationDetails = __1.ExpectationDetails.of('unknown');
                     return result
-                        ? new __1.ExpectationMet(subject, expected, actual)
-                        : new __1.ExpectationNotMet(subject, expected, actual);
+                        ? new __1.ExpectationMet(message, expectationDetails, expected, actual)
+                        : new __1.ExpectationNotMet(message, expectationDetails, expected, actual);
                 });
             },
         });
     }
     /**
-     * @desc
-     *  Used to compose {@link Expectation}s.
-     *
-     * @example
-     *  import { actorCalled, Expectation } from '@serenity-js/core';
-     *  import { Ensure, and, or, isGreaterThan, isLessThan, equals  } from '@serenity-js/assertions';
-     *
-     *  function isWithin(lowerBound: number, upperBound: number) {
-     *      return Expectation
-     *          .to(`have value within ${ lowerBound } and ${ upperBound }`)
-     *          .soThatActual(and(
-     *              or(isGreaterThan(lowerBound), equals(lowerBound)),
-     *              or(isLessThan(upperBound), equals(upperBound)),
-     *          ));
+     * Used to compose {@apilink Expectation|expectations}.
+     *
+     * #### Composing {@apilink Expectation|expectations}
+     *
+     * ```ts
+     * import { actorCalled, Expectation } from '@serenity-js/core'
+     * import { Ensure, and, or, isGreaterThan, isLessThan, equals  } from '@serenity-js/assertions'
+     *
+     * function isWithin(lowerBound: number, upperBound: number) {
+     *   return Expectation
+     *     .to(`have value within ${ lowerBound } and ${ upperBound }`)
+     *     .soThatActual(
+     *       and(
+     *         or(isGreaterThan(lowerBound), equals(lowerBound)),
+     *         or(isLessThan(upperBound), equals(upperBound)),
+     *       )
+     *     )
      *  }
      *
-     *  actorCalled('Erica').attemptsTo(
+     *  await actorCalled('Erica').attemptsTo(
      *      Ensure.that(5, isWithin(3, 6)),
-     *  );
-     *
-     * @param {string} relationshipName
+     *  )
+     * ```
      *
-     * @returns {"soThat": function(...expectations: Array<Expectation<any, A>>): Expectation<any, A>}
+     * @param relationshipName
+     *  Name of the relationship between the `actual` and the `expected`. Use format `have value <adjective>`
+     *  so that the description works in both positive and negative contexts, e.g. `Waited until 5 does have value greater than 2`,
+     *  `Expected 5 to not have value greater than 2`.
      */
     static to(relationshipName) {
         return {
             soThatActual: (expectation) => {
-                return new Expectation(relationshipName, async (actor, actualValue) => {
-                    const outcome = await actor.answer(expectation.isMetFor(actualValue));
-                    return outcome;
+                return new Expectation('unknown', relationshipName, async (actor, actualValue) => {
+                    return await actor.answer(expectation.isMetFor(actualValue));
                 });
             },
         };
     }
+    constructor(functionName, description, predicate) {
+        this.functionName = functionName;
+        this.description = description;
+        this.predicate = predicate;
+    }
+    /**
+     * Returns a {@apilink QuestionAdapter} that resolves to {@apilink ExpectationOutcome}
+     * indicating that the {@apilink ExpectationMet|expectation was met}
+     * or that the {@apilink ExpectationNotMet|expectation was not met}
+     *
+     * @param actual
+     */
     isMetFor(actual) {
-        return __1.Question.about(this.subject, actor => this.predicate(actor, actual));
+        return __1.Question.about(this.description, actor => this.predicate(actor, actual));
     }
+    /**
+     * @inheritDoc
+     */
     describedAs(subject) {
-        this.subject = subject;
+        this.description = subject;
         return this;
     }
+    /**
+     * @inheritDoc
+     */
     toString() {
-        return this.subject;
+        return this.description;
     }
 }
 exports.Expectation = Expectation;

package/lib/screenplay/questions/Expectation.js.map

@@ -1 +1 @@
-{"version":3,"file":"Expectation.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Expectation.ts"],"names":[],"mappings":";;;AAAA,iCAA6B;AAC7B,2BAAiH;AAYjH;;;;;;GAMG;AACH,MAAa,WAAW;IA0FpB,YACY,OAAe,EACN,SAA4B;QADrC,YAAO,GAAP,OAAO,CAAQ;QACN,cAAS,GAAT,SAAS,CAAmB;IAEjD,CAAC;IA5FD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,gBAAgB,CAAO,gBAAwB,EAAE,aAA6B;QAGjF,OAAO,CAAC;YACJ,MAAM,EAAE,CAAC,mBAAqF,EAAkB,EAAE;gBAC9G,MAAM,OAAO,GAAG,gBAAgB,GAAG,GAAG,GAAG,IAAA,MAAC,EAAA,GAAG,aAAa,EAAE,CAAC;gBAE7D,OAAO,IAAI,WAAW,CAClB,OAAO,EACP,KAAK,EAAE,KAAuB,EAAE,WAA0B,EAAqC,EAAE;oBAC7F,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;oBACnD,MAAM,MAAM,GAAK,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;oBAEjD,MAAM,MAAM,GAAK,MAAM,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;oBAE7D,OAAO,MAAM;wBACT,CAAC,CAAC,IAAI,kBAAc,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC;wBAC/C,CAAC,CAAC,IAAI,qBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAC3D,CAAC,CACJ,CAAC;YACN,CAAC;SACJ,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,EAAE,CAAO,gBAAwB;QAGpC,OAAO;YACH,YAAY,EAAE,CAAC,WAA2B,EAAkB,EAAE;gBAC1D,OAAO,IAAI,WAAW,CAClB,gBAAgB,EAChB,KAAK,EAAE,KAAuB,EAAE,WAA0B,EAAqC,EAAE;oBAC7F,MAAM,OAAO,GAAI,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;oBAEvE,OAAO,OAAmC,CAAC;gBAC/C,CAAC,CACJ,CAAC;YACN,CAAC;SACJ,CAAC;IACN,CAAC;IAQD,QAAQ,CAAC,MAA0B;QAC/B,OAAO,YAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,WAAW,CAAC,OAAe;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,QAAQ;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ;AA5GD,kCA4GC"}
+{"version":3,"file":"Expectation.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Expectation.ts"],"names":[],"mappings":"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"}

package/lib/screenplay/questions/List.d.ts

@@ -1,9 +1,17 @@
-import { Actor, AnswersQuestions, UsesAbilities } from '../actor';
+import { UsesAbilities } from '../abilities';
+import { Actor } from '../Actor';
 import { Answerable } from '../Answerable';
 import { Question, QuestionAdapter } from '../Question';
+import { AnswersQuestions } from '../questions';
 import { Task } from '../Task';
 import { Expectation } from './Expectation';
 import { MetaQuestion } from './MetaQuestion';
+/**
+ * Serenity/JS Screenplay Pattern-style wrapper around {@apilink Array}
+ * and array-like structures - see {@apilink PageElements}.
+ *
+ * @group Questions
+ */
 export declare class List<Item_Type> extends Question<Promise<Item_Type[]>> {
     protected readonly collection: Answerable<Array<Item_Type>>;
     private subject;
@@ -15,12 +23,16 @@ export declare class List<Item_Type> extends Question<Promise<Item_Type[]>> {
     count(): QuestionAdapter<number>;
     first(): QuestionAdapter<Item_Type>;
     last(): QuestionAdapter<Item_Type>;
-    get(index: number): QuestionAdapter<Item_Type>;
+    nth(index: number): QuestionAdapter<Item_Type>;
     answeredBy(actor: AnswersQuestions & UsesAbilities): Promise<Array<Item_Type>>;
     describedAs(subject: string): this;
     toString(): string;
 }
+/**
+ * @group Questions
+ */
 export interface CurrentItem<Item_Type> {
     item: Item_Type;
     actor: Actor;
 }
+//# sourceMappingURL=List.d.ts.map

package/lib/screenplay/questions/List.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"List.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/List.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,IAAI,CAAC,SAAS,CAAE,SAAQ,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAQ3D,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAP/D,OAAO,CAAC,OAAO,CAAS;IAExB,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;gBAKnC,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAM/D,YAAY,CAAC,gBAAgB,EACzB,QAAQ,EAAE,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC,GAChF,IAAI,CAAC,gBAAgB,CAAC;IAMzB,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAI1H,KAAK,CAAC,WAAW,EACb,QAAQ,EAAE,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,EACrE,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,GACtC,IAAI;IAMP,KAAK,IAAI,eAAe,CAAC,MAAM,CAAC;IAOhC,KAAK,IAAI,eAAe,CAAC,SAAS,CAAC;IAYnC,IAAI,IAAI,eAAe,CAAC,SAAS,CAAC;IAYlC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC;IAYxC,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAUpF,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKlC,QAAQ,IAAI,MAAM;CAGrB;AAyID;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,SAAS;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;CAChB"}

package/lib/screenplay/questions/List.js

@@ -6,15 +6,21 @@ const io_1 = require("../../io");
 const Question_1 = require("../Question");
 const Task_1 = require("../Task");
 const expectations_1 = require("./expectations");
+/**
+ * Serenity/JS Screenplay Pattern-style wrapper around {@apilink Array}
+ * and array-like structures - see {@apilink PageElements}.
+ *
+ * @group Questions
+ */
 class List extends Question_1.Question {
+    static of(collection) {
+        return new List(collection);
+    }
     constructor(collection) {
         super();
         this.collection = collection;
         this.subject = (0, io_1.d) `${collection}`;
     }
-    static of(collection) {
-        return new List(collection);
-    }
     eachMappedTo(question) {
         return new List(new EachMappedTo(this.collection, question, this.subject));
     }
@@ -34,7 +40,7 @@ class List extends Question_1.Question {
         return Question_1.Question.about(`the first of ${this.subject}`, async (actor) => {
             const items = await this.answeredBy(actor);
             if (items.length === 0) {
-                throw new errors_1.LogicError((0, io_1.d) `Can't retrieve the first item from a list with 0 items: ${items}`);
+                throw new errors_1.ListItemNotFoundError((0, io_1.d) `Can't retrieve the first item from a list with 0 items: ${items}`);
             }
             return items[0];
         });
@@ -43,16 +49,16 @@ class List extends Question_1.Question {
         return Question_1.Question.about(`the last of ${this.subject}`, async (actor) => {
             const items = await this.answeredBy(actor);
             if (items.length === 0) {
-                throw new errors_1.LogicError((0, io_1.d) `Can't retrieve the last item from a list with 0 items: ${items}`);
+                throw new errors_1.ListItemNotFoundError((0, io_1.d) `Can't retrieve the last item from a list with 0 items: ${items}`);
             }
             return items[items.length - 1];
         });
     }
-    get(index) {
+    nth(index) {
         return Question_1.Question.about(`the ${ordinal(index + 1)} of ${this.subject}`, async (actor) => {
             const items = await this.answeredBy(actor);
             if (index < 0 || items.length <= index) {
-                throw new errors_1.LogicError(`Can't retrieve the ${ordinal(index)} item from a list with ${items.length} items: ` + (0, io_1.d) `${items}`);
+                throw new errors_1.ListItemNotFoundError(`Can't retrieve the ${ordinal(index)} item from a list with ${items.length} items: ` + (0, io_1.d) `${items}`);
             }
             return items[index];
         });
@@ -160,7 +166,7 @@ class EachMappedTo extends Question_1.Question {
  */
 class ForEachLoop extends Task_1.Task {
     constructor(collection, subject, fn) {
-        super();
+        super(`#actor iterates over ${subject}`);
         this.collection = collection;
         this.subject = subject;
         this.fn = fn;
@@ -171,8 +177,5 @@ class ForEachLoop extends Task_1.Task {
             await this.fn({ actor, item }, index, collection);
         }
     }
-    toString() {
-        return `#actor iterates over ${this.subject}`;
-    }
 }
 //# sourceMappingURL=List.js.map

package/lib/screenplay/questions/List.js.map

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

package/lib/screenplay/questions/MetaQuestion.d.ts

@@ -1,38 +1,34 @@
 import { Answerable } from '../Answerable';
 import { Question } from '../Question';
 /**
- * @desc
- *  A {@link Question} about another {@link Answerable}, used to retrieve a transformed version of the value it holds, or to compose {@link Question}s.
+ * A "meta question" is a {@apilink Question} about another {@apilink Answerable},
+ * used to retrieve a transformed version of the value that answerable holds.
  *
- *  For example, the question [`Text.of`](/modules/protractor/class/src/screenplay/questions/text/Text.ts~Text.html)
- *  returns text content of an {@link ElementFinder} returned by [`Target`](/modules/protractor/class/src/screenplay/questions/targets/Target.ts~Target.html),
- *  which is a `Question<ElementFinder>`.
+ * For example, the question {@apilink Text.of}
+ * returns text content of a {@apilink PageElement}.
  *
- *  `MetaQuestion`s are typically used when filtering a {@link List}.
+ * {@apilink MetaQuestion|Meta questions} are typically used when filtering a {@apilink List}.
  *
- * @see {@link List}
+ * ## Learn more
+ * - {@apilink List}
  *
- * @public
- * @interface
+ * @group Questions
  */
 export interface MetaQuestion<Supported_Answerable_Type extends Answerable<any>, Answer> {
     /**
-     * @desc
-     *  Transforms a given `answerable`
-     *  to another {@link Question}.
+     * Transforms a given `answerable` to another {@apilink Question}.
      *
-     * @type {function<T>(another: Answerable): Question<Answer>}
-     * @public
-     *
-     * @see {@link List}
+     * #### Learn more
+     * - {@apilink List}
      */
-    of: (answerable: Supported_Answerable_Type) => Question<Answer>;
+    of(answerable: Supported_Answerable_Type): Question<Answer>;
     /**
-     * @desc
-     *  Human-readable description of a given {@link MetaQuestion},
+     * Human-readable description of this {@apilink MetaQuestion},
+     * typically involving the description of the subject.
      *
-     * @type {function(): string}
-     * @public
+     * For example, a description of a meta question obout "the text of an element"
+     * would be `text of ${ element.toString() }`
      */
-    toString: () => string;
+    toString(): string;
 }
+//# sourceMappingURL=MetaQuestion.d.ts.map

package/lib/screenplay/questions/MetaQuestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetaQuestion.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/MetaQuestion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY,CAAC,yBAAyB,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM;IAEnF;;;;;OAKG;IACH,EAAE,CAAC,UAAU,EAAE,yBAAyB,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE5D;;;;;;OAMG;IACH,QAAQ,IAAI,MAAM,CAAC;CACtB"}

package/lib/screenplay/questions/Unanswered.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+import { JSONValue, TinyType } from 'tiny-types';
+import * as util from 'util';
+/**
+ * A placeholder value signifying that a {@apilink Question}
+ * has not been answered by an {@apilink Actor} when producing an {@apilink 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 declare class Unanswered extends TinyType {
+    [util.inspect.custom](): string;
+    toString(): string;
+    toJSON(): JSONValue;
+}
+//# sourceMappingURL=Unanswered.d.ts.map

package/lib/screenplay/questions/Unanswered.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Unanswered.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/Unanswered.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,qBAAa,UAAW,SAAQ,QAAQ;IACpC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM;IAI/B,QAAQ,IAAI,MAAM;IAIlB,MAAM,IAAI,SAAS;CAGtB"}

package/lib/screenplay/questions/Unanswered.js

@@ -0,0 +1,52 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Unanswered = void 0;
+const tiny_types_1 = require("tiny-types");
+const util = __importStar(require("util")); // eslint-disable-line unicorn/import-style
+/**
+ * A placeholder value signifying that a {@apilink Question}
+ * has not been answered by an {@apilink Actor} when producing an {@apilink 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
+ */
+class Unanswered extends tiny_types_1.TinyType {
+    [util.inspect.custom]() {
+        return `<<unanswered>>`;
+    }
+    toString() {
+        return 'unanswered';
+    }
+    toJSON() {
+        return undefined; // eslint-disable-line unicorn/no-useless-undefined
+    }
+}
+exports.Unanswered = Unanswered;
+//# sourceMappingURL=Unanswered.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Unanswered.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Unanswered.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,2CAAiD;AACjD,2CAA6B,CAAG,2CAA2C;AAE3E;;;;;;;;;;GAUG;AACH,MAAa,UAAW,SAAQ,qBAAQ;IACpC,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,CAAG,mDAAmD;IAC3E,CAAC;CACJ;AAZD,gCAYC"}

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

@@ -0,0 +1,24 @@
+import { JSONObject, JSONValue, TinyType } from 'tiny-types';
+import { Name } from '../../../model';
+import { Unanswered } from '../Unanswered';
+/**
+ * Used with {@apilink ExpectationOutcome} to describe an {@apilink 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/lib/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,EAA8B,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGzF,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;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"}