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

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

@@ -1,83 +1,65 @@
+import { PerformsActivities } from '../activities';
 import { Activity } from '../Activity';
-import { AnswersQuestions, PerformsActivities } from '../actor';
 import { Answerable } from '../Answerable';
+import { AnswersQuestions } from '../questions';
 import { Task } from '../Task';
 import { Expectation } from './Expectation';
 /**
- * @desc
- *  A control flow statement that enables the {@link @serenity-js/core/lib/screenplay/actor~Actor}
- *  either to choose whether or not to perform a series of activities,
- *  or to choose which of the two provided series of activities to perform.
+ * A [flow control statement](https://en.wikipedia.org/wiki/Control_flow)
+ * that enables an {@apilink Actor} to decide between two alternate series of {@apilink Activity|activities}.
  *
- * @example <caption>Choose from two alternatives</caption>
- *  import { equals } from '@serenity-js/assertions';
- *  import { Check } from '@serenity-js/core';
+ * Think of it as a Screenplay Pattern equivalent of the traditional `if` statement.
  *
- *  actor.attemptsTo(
- *      Check.whether(process.env.MODE, equals('prod'))
- *          .andIfSo(
- *              LogInAsProdUser(),
- *          )
- *          .otherwise(
- *              LogInAsTestUser(),
- *          )
- *  );
+ * ## Choose between two alternative sequences of activities
  *
- * @example <caption>Choose whether or not to perform an activity</caption>
- *  import { equals } from '@serenity-js/assertions';
- *  import { Check } from '@serenity-js/core';
- *  import { isDisplayed } from '@serenity-js/protractor';
+ * ```ts
+ * import { equals } from '@serenity-js/assertions'
+ * import { actorCalled, Check } from '@serenity-js/core'
  *
- *  actor.attemptsTo(
- *      Check.whether(NewsletterModal(), isDisplayed())
- *          .andIfSo(
- *              DismissModal(),
- *          )
- *  );
+ * await actorCalled('Chuck').attemptsTo(
+ *   Check.whether(process.env.MODE, equals('prod'))
+ *     .andIfSo(
+ *       LogInAsProdUser(),
+ *     )
+ *     .otherwise(
+ *       LogInAsTestUser(),
+ *     )
+ * )
+ * ```
  *
- * @extends {@serenity-js/core/lib/screenplay~Task}
+ * ## Perform a sequence of activities when a condition is met
  *
- * @see https://en.wikipedia.org/wiki/Control_flow
+ * ```ts
+ * import { actorCalled, Check } from '@serenity-js/core'
+ * import { isVisible } from '@serenity-js/web'
+ *
+ * await actorCalled('Chuck').attemptsTo(
+ *   Check.whether(CookieConsentBanner(), isVisible())
+ *     .andIfSo(
+ *         AcceptNecessaryCookies(),
+ *     )
+ * )
+ * ```
+ *
+ * @group Activities
  */
 export declare class Check<Actual> extends Task {
     private readonly actual;
     private readonly expectation;
     private readonly activities;
     private readonly alternativeActivities;
-    static whether<A>(actual: Answerable<A>, expectation: Expectation<A>): {
-        andIfSo: (...activities: Activity[]) => Check<A>;
+    static whether<Actual_Type>(actual: Answerable<Actual_Type>, expectation: Expectation<Actual_Type>): {
+        andIfSo: (...activities: Activity[]) => Check<Actual_Type>;
     };
+    protected constructor(actual: Answerable<Actual>, expectation: Expectation<Actual>, activities: Activity[], alternativeActivities?: Activity[]);
     /**
-     *
-     * @param actual
-     * @param expectation
-     * @param activities
      * @param alternativeActivities
-     */
-    constructor(actual: Answerable<Actual>, expectation: Expectation<Actual>, activities: Activity[], alternativeActivities?: Activity[]);
-    /**
-     * @param {...@serenity-js/core/lib/screenplay~Activity[]} alternativeActivities
-     * @return {@serenity-js/core/lib/screenplay~Task}
+     *  A sequence of {@apilink Activity|activities} to perform when the {@apilink Expectation} is not met.
      */
     otherwise(...alternativeActivities: Activity[]): Task;
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Task}.
-     *
-     * @param {AnswersQuestions & PerformsActivities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~PerformsActivities}
+     * @inheritDoc
      */
     performAs(actor: AnswersQuestions & PerformsActivities): Promise<void>;
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string;
 }
+//# sourceMappingURL=Check.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Check.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/Check.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,KAAK,CAAC,MAAM,CAAE,SAAQ,IAAI;IAU/B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,qBAAqB;IAX1C,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC,GAAG,UAAU,EAAE,QAAQ,EAAE,KAAK,KAAK,CAAC,WAAW,CAAC,CAAA;KAAE;IAOnK,SAAS,aACY,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAC1B,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,UAAU,EAAE,QAAQ,EAAE,EACtB,qBAAqB,GAAE,QAAQ,EAAO;IAK3D;;;OAGG;IACH,SAAS,CAAC,GAAG,qBAAqB,EAAE,QAAQ,EAAE,GAAG,IAAI;IAIrD;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;CAO/E"}

package/lib/screenplay/questions/Check.js

@@ -5,80 +5,67 @@ const io_1 = require("../../io");
 const Task_1 = require("../Task");
 const expectations_1 = require("./expectations");
 /**
- * @desc
- *  A control flow statement that enables the {@link @serenity-js/core/lib/screenplay/actor~Actor}
- *  either to choose whether or not to perform a series of activities,
- *  or to choose which of the two provided series of activities to perform.
+ * A [flow control statement](https://en.wikipedia.org/wiki/Control_flow)
+ * that enables an {@apilink Actor} to decide between two alternate series of {@apilink Activity|activities}.
  *
- * @example <caption>Choose from two alternatives</caption>
- *  import { equals } from '@serenity-js/assertions';
- *  import { Check } from '@serenity-js/core';
+ * Think of it as a Screenplay Pattern equivalent of the traditional `if` statement.
  *
- *  actor.attemptsTo(
- *      Check.whether(process.env.MODE, equals('prod'))
- *          .andIfSo(
- *              LogInAsProdUser(),
- *          )
- *          .otherwise(
- *              LogInAsTestUser(),
- *          )
- *  );
+ * ## Choose between two alternative sequences of activities
  *
- * @example <caption>Choose whether or not to perform an activity</caption>
- *  import { equals } from '@serenity-js/assertions';
- *  import { Check } from '@serenity-js/core';
- *  import { isDisplayed } from '@serenity-js/protractor';
+ * ```ts
+ * import { equals } from '@serenity-js/assertions'
+ * import { actorCalled, Check } from '@serenity-js/core'
  *
- *  actor.attemptsTo(
- *      Check.whether(NewsletterModal(), isDisplayed())
- *          .andIfSo(
- *              DismissModal(),
- *          )
- *  );
+ * await actorCalled('Chuck').attemptsTo(
+ *   Check.whether(process.env.MODE, equals('prod'))
+ *     .andIfSo(
+ *       LogInAsProdUser(),
+ *     )
+ *     .otherwise(
+ *       LogInAsTestUser(),
+ *     )
+ * )
+ * ```
  *
- * @extends {@serenity-js/core/lib/screenplay~Task}
+ * ## Perform a sequence of activities when a condition is met
  *
- * @see https://en.wikipedia.org/wiki/Control_flow
+ * ```ts
+ * import { actorCalled, Check } from '@serenity-js/core'
+ * import { isVisible } from '@serenity-js/web'
+ *
+ * await actorCalled('Chuck').attemptsTo(
+ *   Check.whether(CookieConsentBanner(), isVisible())
+ *     .andIfSo(
+ *         AcceptNecessaryCookies(),
+ *     )
+ * )
+ * ```
+ *
+ * @group Activities
  */
 class Check extends Task_1.Task {
-    /**
-     *
-     * @param actual
-     * @param expectation
-     * @param activities
-     * @param alternativeActivities
-     */
-    constructor(actual, expectation, activities, alternativeActivities = []) {
-        super();
-        this.actual = actual;
-        this.expectation = expectation;
-        this.activities = activities;
-        this.alternativeActivities = alternativeActivities;
-    }
     // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
     static whether(actual, expectation) {
         return {
             andIfSo: (...activities) => new Check(actual, expectation, activities),
         };
     }
+    constructor(actual, expectation, activities, alternativeActivities = []) {
+        super((0, io_1.d) `#actor checks whether ${actual} does ${expectation}`);
+        this.actual = actual;
+        this.expectation = expectation;
+        this.activities = activities;
+        this.alternativeActivities = alternativeActivities;
+    }
     /**
-     * @param {...@serenity-js/core/lib/screenplay~Activity[]} alternativeActivities
-     * @return {@serenity-js/core/lib/screenplay~Task}
+     * @param alternativeActivities
+     *  A sequence of {@apilink Activity|activities} to perform when the {@apilink Expectation} is not met.
      */
     otherwise(...alternativeActivities) {
         return new Check(this.actual, this.expectation, this.activities, alternativeActivities);
     }
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Task}.
-     *
-     * @param {AnswersQuestions & PerformsActivities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~PerformsActivities}
+     * @inheritDoc
      */
     async performAs(actor) {
         const outcome = await actor.answer(this.expectation.isMetFor(this.actual));
@@ -86,15 +73,6 @@ class Check extends Task_1.Task {
             ? actor.attemptsTo(...this.activities)
             : actor.attemptsTo(...this.alternativeActivities);
     }
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString() {
-        return (0, io_1.d) `#actor checks whether ${this.actual} does ${this.expectation}`;
-    }
 }
 exports.Check = Check;
 //# sourceMappingURL=Check.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"Check.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Check.ts"],"names":[],"mappings":";;;AAAA,iCAA6B;AAI7B,kCAA+B;AAE/B,iDAAgD;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAa,KAAc,SAAQ,WAAI;IAQnC;;;;;;OAMG;IACH,YACqB,MAA0B,EAC1B,WAAgC,EAChC,UAAsB,EACtB,wBAAoC,EAAE;QAEvD,KAAK,EAAE,CAAC;QALS,WAAM,GAAN,MAAM,CAAoB;QAC1B,gBAAW,GAAX,WAAW,CAAqB;QAChC,eAAU,GAAV,UAAU,CAAY;QACtB,0BAAqB,GAArB,qBAAqB,CAAiB;IAG3D,CAAC;IArBD,6EAA6E;IAC7E,MAAM,CAAC,OAAO,CAAI,MAAqB,EAAE,WAA2B;QAChE,OAAO;YACH,OAAO,EAAE,CAAC,GAAG,UAAsB,EAAE,EAAE,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC;SACrF,CAAC;IACN,CAAC;IAkBD;;;OAGG;IACH,SAAS,CAAC,GAAG,qBAAiC;QAC1C,OAAO,IAAI,KAAK,CAAS,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC;IACpG,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,SAAS,CAAC,KAA4C;QACxD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAE3E,OAAO,OAAO,YAAY,6BAAc;YACpC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;YACtC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAA,MAAC,EAAA,yBAA0B,IAAI,CAAC,MAAO,SAAU,IAAI,CAAC,WAAY,EAAE,CAAC;IAChF,CAAC;CACJ;AA7DD,sBA6DC"}
+{"version":3,"file":"Check.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Check.ts"],"names":[],"mappings":";;;AAAA,iCAA6B;AAK7B,kCAA+B;AAE/B,iDAAgD;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAa,KAAc,SAAQ,WAAI;IACnC,6EAA6E;IAC7E,MAAM,CAAC,OAAO,CAAc,MAA+B,EAAE,WAAqC;QAC9F,OAAO;YACH,OAAO,EAAE,CAAC,GAAG,UAAsB,EAAE,EAAE,CACnC,IAAI,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC;SACjD,CAAC;IACN,CAAC;IAED,YACqB,MAA0B,EAC1B,WAAgC,EAChC,UAAsB,EACtB,wBAAoC,EAAE;QAEvD,KAAK,CAAC,IAAA,MAAC,EAAA,yBAA0B,MAAO,SAAU,WAAY,EAAE,CAAC,CAAC;QALjD,WAAM,GAAN,MAAM,CAAoB;QAC1B,gBAAW,GAAX,WAAW,CAAqB;QAChC,eAAU,GAAV,UAAU,CAAY;QACtB,0BAAqB,GAArB,qBAAqB,CAAiB;IAG3D,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,GAAG,qBAAiC;QAC1C,OAAO,IAAI,KAAK,CAAS,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC;IACpG,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAA4C;QACxD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAE3E,OAAO,OAAO,YAAY,6BAAc;YACpC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;YACtC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAC1D,CAAC;CACJ;AApCD,sBAoCC"}

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

@@ -1,76 +1,187 @@
 import { Answerable, AnswersQuestions, QuestionAdapter } from '../';
 import { ExpectationOutcome } from './expectations';
 /**
- * @public
- *
- * @typedef {function(actual: Answerable<Actual>) => Promise<ExpectationOutcome<Expected, Actual>> | ExpectationOutcome<unknown, Actual>} Predicate<Actual>
+ * @group Expectations
  */
-export declare type Predicate<Actual> = (actor: AnswersQuestions, actual: Answerable<Actual>) => Promise<ExpectationOutcome<unknown, Actual>> | ExpectationOutcome<unknown, Actual>;
+export type Predicate<Actual> = (actor: AnswersQuestions, actual: Answerable<Actual>) => Promise<ExpectationOutcome> | ExpectationOutcome;
+type AnswerableArguments<Arguments extends Array<unknown>> = {
+    [Index in keyof Arguments]: Answerable<Arguments[Index]>;
+};
 /**
- * @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
  */
 export declare class Expectation<Actual> {
-    private subject;
+    private readonly functionName;
+    private description;
     private readonly predicate;
     /**
-     * @desc
-     *  Used to define a simple {@link Expectation}
+     * 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}
      *
-     * @example
-     *  import { actorCalled, Expectation } from '@serenity-js/core';
-     *  import { Ensure } from '@serenity-js/assertions';
+     * @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<Actual_Type, PredicateArguments extends Array<unknown>>(functionName: string, relationship: ((...answerableArguments: AnswerableArguments<PredicateArguments>) => string) | string, predicate: (actual: Actual_Type, ...predicateArguments: PredicateArguments) => Promise<boolean> | boolean): (...answerableArguments: AnswerableArguments<PredicateArguments>) => Expectation<Actual_Type>;
+    /**
+     * Used to define a simple {@apilink Expectation}
+     *
+     * #### Simple parameterised expectation
+     *
+     * ```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<E, A>(relationshipName: string, expectedValue?: Answerable<E>): {
-        soThat: (simplifiedPredicate: (actualValue: A, expectedValue: E) => Promise<boolean> | boolean) => Expectation<A>;
+    static thatActualShould<Expected_Type, Actual_Type>(relationshipName: string, expectedValue?: Answerable<Expected_Type>): {
+        soThat: (simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => Promise<boolean> | boolean) => Expectation<Actual_Type>;
     };
     /**
-     * @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<E, A>(relationshipName: string): {
-        soThatActual: (...expectations: Array<Expectation<A>>) => Expectation<A>;
+    static to<Actual_Type>(relationshipName: string): {
+        soThatActual: (expectation: Expectation<Actual_Type>) => Expectation<Actual_Type>;
     };
-    protected constructor(subject: string, predicate: Predicate<Actual>);
-    isMetFor(actual: Answerable<Actual>): QuestionAdapter<ExpectationOutcome<unknown, Actual>>;
+    protected constructor(functionName: string, description: string, predicate: Predicate<Actual>);
+    /**
+     * 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: Answerable<Actual>): QuestionAdapter<ExpectationOutcome>;
+    /**
+     * @inheritDoc
+     */
     describedAs(subject: string): this;
+    /**
+     * @inheritDoc
+     */
     toString(): string;
 }
+export {};
+//# sourceMappingURL=Expectation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Expectation.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/Expectation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAmE,eAAe,EAAE,MAAM,KAAK,CAAC;AACrI,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,KAChF,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;AAErD,KAAK,mBAAmB,CAAC,SAAS,SAAS,KAAK,CAAC,OAAO,CAAC,IAAI;KAAG,KAAK,IAAI,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;CAAE,CAAC;AAE1H;;;;;GAKG;AACH,qBAAa,WAAW,CAAC,MAAM;IA+NvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IA/N9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoFG;IACH,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,kBAAkB,SAAS,KAAK,CAAC,OAAO,CAAC,EAChE,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,CAAC,CAAC,GAAG,mBAAmB,EAAE,mBAAmB,CAAC,kBAAkB,CAAC,KAAK,MAAM,CAAC,GAAG,MAAM,EACpG,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,kBAAkB,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GAC1G,CAAC,GAAG,mBAAmB,EAAE,mBAAmB,CAAC,kBAAkB,CAAC,KAAK,WAAW,CAAC,WAAW,CAAC;IAiChG;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,gBAAgB,CAAC,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,aAAa,CAAC,GAAG;QACtH,MAAM,EAAE,CAAC,mBAAmB,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,KAAK,WAAW,CAAC,WAAW,CAAC,CAAC;KACrJ;IAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,MAAM,GAAG;QAC9C,YAAY,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,KAAK,WAAW,CAAC,WAAW,CAAC,CAAC;KACrF;IAcD,SAAS,aACY,YAAY,EAAE,MAAM,EAC7B,WAAW,EAAE,MAAM,EACV,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC;IAIjD;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,kBAAkB,CAAC;IAIzE;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKlC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGrB"}