@serenity-js/core 3.41.2 → 3.42.0

package/esm/screenplay/questions/Check.js

@@ -0,0 +1,77 @@
+import { d } from '../../io/index.js';
+import { Task } from '../Task.js';
+import { ExpectationMet } from './expectations/index.js';
+/**
+ * A [flow control statement](https://en.wikipedia.org/wiki/Control_flow)
+ * that enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to decide between two alternate series of [activities](https://serenity-js.org/api/core/class/Activity/).
+ *
+ * Think of it as a Screenplay Pattern equivalent of the traditional `if` statement.
+ *
+ * ## Choose between two alternative sequences of activities
+ *
+ * ```ts
+ * import { equals } from '@serenity-js/assertions'
+ * import { actorCalled, Check } from '@serenity-js/core'
+ *
+ * await actorCalled('Chuck').attemptsTo(
+ *   Check.whether(process.env.MODE, equals('prod'))
+ *     .andIfSo(
+ *       LogInAsProdUser(),
+ *     )
+ *     .otherwise(
+ *       LogInAsTestUser(),
+ *     )
+ * )
+ * ```
+ *
+ * ## Perform a sequence of activities when a condition is met
+ *
+ * ```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 class Check extends Task {
+    actual;
+    expectation;
+    activities;
+    alternativeActivities;
+    static whether(actual, expectation) {
+        return {
+            andIfSo: (...activities) => new Check(actual, expectation, activities),
+        };
+    }
+    constructor(actual, expectation, activities, alternativeActivities = []) {
+        super(d `#actor checks whether ${actual} does ${expectation}`);
+        this.actual = actual;
+        this.expectation = expectation;
+        this.activities = activities;
+        this.alternativeActivities = alternativeActivities;
+    }
+    /**
+     * @param alternativeActivities
+     *  A sequence of [activities](https://serenity-js.org/api/core/class/Activity/) to perform when the [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) is not met.
+     */
+    otherwise(...alternativeActivities) {
+        return new Check(this.actual, this.expectation, this.activities, alternativeActivities);
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const outcome = await actor.answer(this.expectation.isMetFor(this.actual));
+        return outcome instanceof ExpectationMet
+            ? actor.attemptsTo(...this.activities)
+            : actor.attemptsTo(...this.alternativeActivities);
+    }
+}
+//# sourceMappingURL=Check.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Check.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAKtC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,OAAO,KAAc,SAAQ,IAAI;IAUd;IACA;IACA;IACA;IAXrB,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,CAAC,CAAA,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,cAAc;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"}

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

@@ -0,0 +1,27 @@
+import type { UsesAbilities } from '../abilities/UsesAbilities.js';
+import type { Answerable } from '../Answerable.js';
+import type { AnswersQuestions } from './AnswersQuestions.js';
+declare const descriptionField: unique symbol;
+/**
+ * @group Questions
+ */
+export declare abstract class Describable {
+    private [descriptionField];
+    protected constructor(description: Answerable<string>);
+    /**
+     * Resolves the description of this object in the context of the provided `actor`.
+     *
+     * @param actor
+     */
+    describedBy(actor: AnswersQuestions & UsesAbilities & {
+        name: string;
+    }): Promise<string>;
+    protected setDescription(description: Answerable<string>): void;
+    protected getDescription(): Answerable<string>;
+    /**
+     * Returns a human-readable description of this object.
+     */
+    toString(): string;
+}
+export {};
+//# sourceMappingURL=Describable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Describable.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/Describable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,QAAA,MAAM,gBAAgB,eAAwB,CAAC;AAE/C;;GAEG;AACH,8BAAsB,WAAW;IAE7B,OAAO,CAAC,CAAC,gBAAgB,CAAC,CAAqB;IAE/C,SAAS,aAAa,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC;IAIrD;;;;OAIG;IACG,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAM9F,SAAS,CAAC,cAAc,CAAC,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI;IAI/D,SAAS,CAAC,cAAc,IAAI,UAAU,CAAC,MAAM,CAAC;IAI9C;;OAEG;IACH,QAAQ,IAAI,MAAM;CAOrB"}

package/esm/screenplay/questions/Describable.js

@@ -0,0 +1,36 @@
+import { ValueInspector } from '../../io/reflection/ValueInspector.js';
+const descriptionField = Symbol('description');
+/**
+ * @group Questions
+ */
+export class Describable {
+    [descriptionField];
+    constructor(description) {
+        this[descriptionField] = description;
+    }
+    /**
+     * Resolves the description of this object in the context of the provided `actor`.
+     *
+     * @param actor
+     */
+    async describedBy(actor) {
+        const description = await actor.answer(this[descriptionField]);
+        return description.replaceAll('#actor', actor.name);
+    }
+    setDescription(description) {
+        this[descriptionField] = description;
+    }
+    getDescription() {
+        return this[descriptionField];
+    }
+    /**
+     * Returns a human-readable description of this object.
+     */
+    toString() {
+        if (ValueInspector.isPromise(this[descriptionField])) {
+            return 'Promise';
+        }
+        return String(this[descriptionField]);
+    }
+}
+//# sourceMappingURL=Describable.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Describable.js","sourceRoot":"","sources":["../../../src/screenplay/questions/Describable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAKvE,MAAM,gBAAgB,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,OAAgB,WAAW;IAErB,CAAC,gBAAgB,CAAC,CAAqB;IAE/C,YAAsB,WAA+B;QACjD,IAAI,CAAC,gBAAgB,CAAC,GAAG,WAAW,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,KAA0D;QACxE,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;QAE/D,OAAO,WAAW,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IACxD,CAAC;IAES,cAAc,CAAC,WAA+B;QACpD,IAAI,CAAC,gBAAgB,CAAC,GAAG,WAAW,CAAC;IACzC,CAAC;IAES,cAAc;QACpB,OAAO,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,QAAQ;QACJ,IAAI,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC;YACnD,OAAO,SAAS,CAAC;QACrB,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC1C,CAAC;CACJ"}

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

@@ -0,0 +1,14 @@
+/**
+ * Configuration options for [`Question.formattedValue`](https://serenity-js.org/api/core/class/Question/#formattedValue) and
+ * the [`the`](https://serenity-js.org/api/core/function/the/) function.
+ *
+ * @group Questions
+ */
+export interface DescriptionFormattingOptions {
+    /**
+     * The maximum length of the string representation of the value.
+     * String representations longer than this value will be truncated and appended with an ellipsis.
+     */
+    maxLength: number;
+}
+//# sourceMappingURL=DescriptionFormattingOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DescriptionFormattingOptions.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/DescriptionFormattingOptions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IACzC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACrB"}

package/esm/screenplay/questions/DescriptionFormattingOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=DescriptionFormattingOptions.js.map

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

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

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

@@ -0,0 +1,186 @@
+import type { Answerable, AnswersQuestions, QuestionAdapter } from '../index.js';
+import { Describable } from '../questions/index.js';
+import type { ExpectationOutcome } from './expectations/index.js';
+/**
+ * @group Expectations
+ */
+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]>;
+};
+/**
+ * Defines an expectation to be used with [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until),
+ * [`Check.whether`](https://serenity-js.org/api/core/class/Check/#whether),
+ * [`Ensure.that`](https://serenity-js.org/api/assertions/class/Ensure/#that)
+ * and as part of the Page Element Query Language with [`PageElements.where`](https://serenity-js.org/api/web/class/PageElements/#where)
+ * and [`List.where`](https://serenity-js.org/api/core/class/List/#where).
+ *
+ * @group Expectations
+ */
+export declare class Expectation<Actual> extends Describable {
+    private readonly functionName;
+    private readonly predicate;
+    /**
+     * A factory method to that makes defining custom [expectations](https://serenity-js.org/api/core/class/Expectation/) 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
+     * - [`Ensure`](https://serenity-js.org/api/assertions/class/Ensure/)
+     * - [`Check`](https://serenity-js.org/api/core/class/Check/)
+     * - [`Wait`](https://serenity-js.org/api/core/class/Wait/)
+     *
+     * @param functionName
+     *  Name of the expectation function to be used when producing an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/)
+     *
+     * @param relationship
+     *  Human-readable description of the relationship between the `expected` and the `actual` values.
+     *  Used when reporting [activities](https://serenity-js.org/api/core/class/Activity/) performed by an [actor](https://serenity-js.org/api/core/class/Actor/)
+     *
+     * @param predicate
+     */
+    static define<Actual_Type, PredicateArguments extends Array<unknown>>(functionName: string, relationship: ((...answerableArguments: AnswerableArguments<PredicateArguments>) => Answerable<string>) | Answerable<string>, predicate: (actual: Actual_Type, ...predicateArguments: PredicateArguments) => Promise<boolean> | boolean): (...answerableArguments: AnswerableArguments<PredicateArguments>) => Expectation<Actual_Type>;
+    /**
+     * Used to define a simple [`Expectation`](https://serenity-js.org/api/core/class/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);
+     *  }
+     *
+     *  await actorCalled('Erica').attemptsTo(
+     *      Ensure.that(4, isDivisibleBy(2)),
+     *  )
+     * ```
+     *
+     * @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`.
+     *
+     * @param expectedValue
+     */
+    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>;
+    };
+    /**
+     * Used to compose [expectations](https://serenity-js.org/api/core/class/Expectation/).
+     *
+     * #### Composing [expectations](https://serenity-js.org/api/core/class/Expectation/)
+     *
+     * ```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)),
+     *       )
+     *     )
+     *  }
+     *
+     *  await actorCalled('Erica').attemptsTo(
+     *      Ensure.that(5, isWithin(3, 6)),
+     *  )
+     * ```
+     *
+     * @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<Actual_Type>(relationshipName: string): {
+        soThatActual: (expectation: Expectation<Actual_Type>) => Expectation<Actual_Type>;
+    };
+    protected constructor(functionName: string, description: Answerable<string>, predicate: Predicate<Actual>);
+    /**
+     * Returns a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to [`ExpectationOutcome`](https://serenity-js.org/api/core/class/ExpectationOutcome/)
+     * indicating that the [expectation was met](https://serenity-js.org/api/core/class/ExpectationMet/)
+     * or that the [expectation was not met](https://serenity-js.org/api/core/class/ExpectationNotMet/)
+     *
+     * @param actual
+     */
+    isMetFor(actual: Answerable<Actual>): QuestionAdapter<ExpectationOutcome>;
+    /**
+     * @inheritDoc
+     */
+    describedAs(description: Answerable<string>): this;
+}
+export {};
+//# sourceMappingURL=Expectation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Expectation.d.ts","sourceRoot":"","sources":["../../../src/screenplay/questions/Expectation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,eAAe,EAAC,MAAM,aAAa,CAAC;AAGhF,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;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;;;;;;;;GAQG;AACH,qBAAa,WAAW,CAAC,MAAM,CAAE,SAAQ,WAAW;IAiO5C,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAjO9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,EAC5H,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;IAmChG;;;;;;;;;;;;;;;;;;;;;;;;;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,EACrC,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,EACd,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC;IAKjD;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,kBAAkB,CAAC;IAIzE;;OAEG;IACH,WAAW,CAAC,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI;CAKrD"}

package/esm/screenplay/questions/Expectation.js

@@ -0,0 +1,227 @@
+import { asyncMap, d } from '../../io/index.js';
+import { ExpectationDetails, ExpectationMet, ExpectationNotMet } from '..//index.js';
+import { the } from '../index.js';
+import { Question } from '../Question.js';
+import { Describable } from '../questions/index.js';
+/**
+ * Defines an expectation to be used with [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until),
+ * [`Check.whether`](https://serenity-js.org/api/core/class/Check/#whether),
+ * [`Ensure.that`](https://serenity-js.org/api/assertions/class/Ensure/#that)
+ * and as part of the Page Element Query Language with [`PageElements.where`](https://serenity-js.org/api/web/class/PageElements/#where)
+ * and [`List.where`](https://serenity-js.org/api/core/class/List/#where).
+ *
+ * @group Expectations
+ */
+export class Expectation extends Describable {
+    functionName;
+    predicate;
+    /**
+     * A factory method to that makes defining custom [expectations](https://serenity-js.org/api/core/class/Expectation/) 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
+     * - [`Ensure`](https://serenity-js.org/api/assertions/class/Ensure/)
+     * - [`Check`](https://serenity-js.org/api/core/class/Check/)
+     * - [`Wait`](https://serenity-js.org/api/core/class/Wait/)
+     *
+     * @param functionName
+     *  Name of the expectation function to be used when producing an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/)
+     *
+     * @param relationship
+     *  Human-readable description of the relationship between the `expected` and the `actual` values.
+     *  Used when reporting [activities](https://serenity-js.org/api/core/class/Activity/) performed by an [actor](https://serenity-js.org/api/core/class/Actor/)
+     *
+     * @param predicate
+     */
+    static define(functionName, relationship, predicate) {
+        return Object.defineProperty(function (...answerableArguments) {
+            const description = typeof relationship === 'function' ? relationship(...answerableArguments)
+                : (answerableArguments.length === 1 ? the `${{ toString: () => relationship }} ${answerableArguments[0]}`
+                    : relationship);
+            return new Expectation(functionName, description, async (actor, actualValue) => {
+                const predicateArguments = await asyncMap(answerableArguments, answerableArgument => actor.answer(answerableArgument));
+                const actual = await actor.answer(actualValue);
+                const result = await predicate(actual, ...predicateArguments);
+                const descriptionText = await actor.answer(description);
+                const expectationDetails = 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 ExpectationMet(descriptionText, expectationDetails, expected, actual)
+                    : new ExpectationNotMet(descriptionText, expectationDetails, expected, actual);
+            });
+        }, 'name', { value: functionName, writable: false });
+    }
+    /**
+     * Used to define a simple [`Expectation`](https://serenity-js.org/api/core/class/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);
+     *  }
+     *
+     *  await actorCalled('Erica').attemptsTo(
+     *      Ensure.that(4, isDivisibleBy(2)),
+     *  )
+     * ```
+     *
+     * @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`.
+     *
+     * @param expectedValue
+     */
+    static thatActualShould(relationshipName, expectedValue) {
+        return ({
+            soThat: (simplifiedPredicate) => {
+                const message = relationshipName + ' ' + 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 = ExpectationDetails.of('unknown');
+                    return result
+                        ? new ExpectationMet(message, expectationDetails, expected, actual)
+                        : new ExpectationNotMet(message, expectationDetails, expected, actual);
+                });
+            },
+        });
+    }
+    /**
+     * Used to compose [expectations](https://serenity-js.org/api/core/class/Expectation/).
+     *
+     * #### Composing [expectations](https://serenity-js.org/api/core/class/Expectation/)
+     *
+     * ```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)),
+     *       )
+     *     )
+     *  }
+     *
+     *  await actorCalled('Erica').attemptsTo(
+     *      Ensure.that(5, isWithin(3, 6)),
+     *  )
+     * ```
+     *
+     * @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('unknown', relationshipName, async (actor, actualValue) => {
+                    return await actor.answer(expectation.isMetFor(actualValue));
+                });
+            },
+        };
+    }
+    constructor(functionName, description, predicate) {
+        super(description);
+        this.functionName = functionName;
+        this.predicate = predicate;
+    }
+    /**
+     * Returns a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to [`ExpectationOutcome`](https://serenity-js.org/api/core/class/ExpectationOutcome/)
+     * indicating that the [expectation was met](https://serenity-js.org/api/core/class/ExpectationMet/)
+     * or that the [expectation was not met](https://serenity-js.org/api/core/class/ExpectationNotMet/)
+     *
+     * @param actual
+     */
+    isMetFor(actual) {
+        return Question.about(this.getDescription(), actor => this.predicate(actor, actual));
+    }
+    /**
+     * @inheritDoc
+     */
+    describedAs(description) {
+        super.setDescription(description);
+        return this;
+    }
+}
+//# sourceMappingURL=Expectation.js.map

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

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