@serenity-js/core 3.41.1 → 3.42.0

package/esm/screenplay/time/TellsTime.d.ts

@@ -0,0 +1,19 @@
+import type { Timestamp } from './models/index.js';
+/**
+ * Describes an [`Actor`](https://serenity-js.org/api/core/class/Actor/) or a supporting class capable of telling
+ * the current wall clock time.
+ *
+ * ## Learn more
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * - [`Serenity`](https://serenity-js.org/api/core/class/Serenity/)
+ * - [`Stage`](https://serenity-js.org/api/core/class/Stage/)
+ *
+ * @group Time
+ */
+export interface TellsTime {
+    /**
+     * Returns current wall clock time.
+     */
+    currentTime(): Timestamp;
+}
+//# sourceMappingURL=TellsTime.d.ts.map

package/esm/screenplay/time/TellsTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TellsTime.d.ts","sourceRoot":"","sources":["../../../src/screenplay/time/TellsTime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,WAAW,IAAI,SAAS,CAAC;CAC5B"}

package/esm/screenplay/time/TellsTime.js

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

package/esm/screenplay/time/TellsTime.js.map

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

package/esm/screenplay/time/abilities/ScheduleWork.d.ts

@@ -0,0 +1,26 @@
+import type { Discardable, SerialisedAbility } from '../../abilities/index.js';
+import { Ability } from '../../abilities/index.js';
+import type { Clock, DelayedCallback, Duration, RepeatUntilLimits } from '../models/index.js';
+/**
+ * An [`Ability`](https://serenity-js.org/api/core/class/Ability/) that enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to schedule a callback function
+ * to be executed with a delay, or until some condition is met.
+ *
+ * Used internally by the [interaction](https://serenity-js.org/api/core/class/Interaction/) to [`Wait`](https://serenity-js.org/api/core/class/Wait/).
+ *
+ * @experimental
+ *
+ * @group Time
+ */
+export declare class ScheduleWork extends Ability implements Discardable {
+    private readonly scheduler;
+    constructor(clock: Clock, interactionTimeout: Duration);
+    /**
+     * @param callback
+     * @param limits
+     */
+    repeatUntil<Result>(callback: DelayedCallback<Result>, limits?: RepeatUntilLimits<Result>): Promise<Result>;
+    waitFor(delay: Duration): Promise<void>;
+    discard(): void;
+    toJSON(): SerialisedAbility;
+}
+//# sourceMappingURL=ScheduleWork.d.ts.map

package/esm/screenplay/time/abilities/ScheduleWork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleWork.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/time/abilities/ScheduleWork.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG9F;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,OAAQ,YAAW,WAAW;IAE5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,KAAK,EAAE,KAAK,EAAE,kBAAkB,EAAE,QAAQ;IAKtD;;;OAGG;IACH,WAAW,CAAC,MAAM,EACd,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,EACjC,MAAM,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,GACnC,OAAO,CAAC,MAAM,CAAC;IAIlB,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,OAAO,IAAI,IAAI;IAIN,MAAM,IAAI,iBAAiB;CAQvC"}

package/esm/screenplay/time/abilities/ScheduleWork.js

@@ -0,0 +1,41 @@
+import { Ability } from '../../abilities/index.js';
+import { Scheduler } from '../models/index.js';
+/**
+ * An [`Ability`](https://serenity-js.org/api/core/class/Ability/) that enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to schedule a callback function
+ * to be executed with a delay, or until some condition is met.
+ *
+ * Used internally by the [interaction](https://serenity-js.org/api/core/class/Interaction/) to [`Wait`](https://serenity-js.org/api/core/class/Wait/).
+ *
+ * @experimental
+ *
+ * @group Time
+ */
+export class ScheduleWork extends Ability {
+    scheduler;
+    constructor(clock, interactionTimeout) {
+        super();
+        this.scheduler = new Scheduler(clock, interactionTimeout);
+    }
+    /**
+     * @param callback
+     * @param limits
+     */
+    repeatUntil(callback, limits) {
+        return this.scheduler.repeatUntil(callback, limits);
+    }
+    waitFor(delay) {
+        return this.scheduler.waitFor(delay);
+    }
+    discard() {
+        this.scheduler.stop();
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            options: {
+                scheduler: this.scheduler.toJSON(),
+            },
+        };
+    }
+}
+//# sourceMappingURL=ScheduleWork.js.map

package/esm/screenplay/time/abilities/ScheduleWork.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleWork.js","sourceRoot":"","sources":["../../../../src/screenplay/time/abilities/ScheduleWork.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,OAAO,YAAa,SAAQ,OAAO;IAEpB,SAAS,CAAY;IAEtC,YAAY,KAAY,EAAE,kBAA4B;QAClD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,SAAS,GAAG,IAAI,SAAS,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,WAAW,CACP,QAAiC,EACjC,MAAkC;QAElC,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,CAAC,KAAe;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,OAAO;QACH,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAEQ,MAAM;QACX,OAAO;YACH,GAAG,KAAK,CAAC,MAAM,EAAE;YACjB,OAAO,EAAE;gBACL,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE;aACrC;SACJ,CAAC;IACN,CAAC;CACJ"}

package/esm/screenplay/time/abilities/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ScheduleWork.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/screenplay/time/abilities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/time/abilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/esm/screenplay/time/abilities/index.js

@@ -0,0 +1,2 @@
+export * from './ScheduleWork.js';
+//# sourceMappingURL=index.js.map

package/esm/screenplay/time/abilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/time/abilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/esm/screenplay/time/activities/Wait.d.ts

@@ -0,0 +1,214 @@
+import type { UsesAbilities } from '../../abilities/index.js';
+import type { Answerable } from '../../Answerable.js';
+import { Interaction } from '../../Interaction.js';
+import type { AnswersQuestions, Expectation } from '../../questions/index.js';
+import { Duration } from '../models/index.js';
+/**
+ * `Wait` is a synchronisation statement that instructs the [actor](https://serenity-js.org/api/core/class/Actor/)
+ * to wait before proceeding with their next [activity](https://serenity-js.org/api/core/class/Activity/),
+ * either for a set [duration](https://serenity-js.org/api/core/class/Duration/), or until a given [expectation](https://serenity-js.org/api/core/class/Expectation/) is met.
+ *
+ * You can configure the timeout of the interaction to [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until):
+ * - globally, using [`SerenityConfig.interactionTimeout`](https://serenity-js.org/api/core/class/SerenityConfig/#interactionTimeout)
+ * - locally, on a per-interaction basis using [`Wait.upTo`](https://serenity-js.org/api/core/class/Wait/#upTo)
+ *
+ * :::tip Portable waiting
+ * Serenity/JS implements `Wait` from scratch, so that the behaviour is consistent no matter the integration tool you use (Playwright, WebdriverIO, Selenium, etc.)
+ * or the type of testing you do (Web, REST API, component testing, etc.)
+ * :::
+ *
+ * ## Wait with Web-based tests
+ *
+ * ### Example widget
+ *
+ * ```html
+ * <!--
+ *     After about 1 second, the text will change from 'Loading...' to 'Ready!'
+ * -->
+ * <h1 id="status">Loading...</h1>
+ * <script>
+ *     (function () {
+ *         setTimeout(function () {
+ *             document.getElementById('status').textContent = 'Ready!'
+ *         }, 1000);
+ *     })();
+ * </script>
+ * ```
+ *
+ * ### Lean Page Object describing the widget
+ *
+ * ```ts
+ * import { By, PageElement, Text } from '@serenity-js/web'
+ *
+ * class App {
+ *   static status = () =>
+ *      Text.of(PageElement.located(By.id('status'))
+ *          .describedAs('status widget'))
+ *  }
+ * ```
+ *
+ * ### Waiting for a set duration
+ *
+ * ```ts
+ * import { actorCalled, Duration, Wait } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch({ headless: true })
+ *
+ * await actorCalled('Inês')
+ *   .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *   .attemptsTo(
+ *       Wait.for(Duration.ofMilliseconds(1_500)),
+ *       Ensure.that(App.status(), equals('Ready!')),
+ *   );
+ * ```
+ *
+ * **Please note** that while the above implementation works,
+ * this approach is inefficient because at best
+ * the actor might wait too long and at worst the test
+ * might become "flaky" if any external interference
+ * (like network glitches, animations taking a bit too long etc.)
+ * makes the actor wait not long enough.
+ *
+ * ### Waiting until a condition is met
+ *
+ * ```ts
+ * import { actorCalled, Wait } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { equals } from '@serenity-js/assertions'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch({ headless: true })
+ *
+ * await actorCalled('Wendy')
+ *     .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *     .attemptsTo(
+ *         Wait.until(App.status(), equals('Ready!')),
+ *         // app is ready, proceed with the scenario
+ *     );
+ * ```
+ *
+ * `Wait.until` makes the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * keep asking the [`Question`](https://serenity-js.org/api/core/class/Question/),
+ * in this case `Text.of(App.status)`, until the answer meets
+ * the expectation, or a timeout expires (default: 5s).
+ *
+ * **Please note** that both Ensure and Wait can be used with
+ * the same expectations, like `equals` or `includes`.
+ *
+ * ### Changing the default timeout
+ *
+ * ```ts
+ *  import { actorCalled, Duration, Wait } from '@serenity-js/core';
+ *  import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright';
+ *  import { equals } from '@serenity-js/assertions';
+ *  import { Browser, chromium } from 'playwright';
+ *
+ *  const browser: Browser = await chromium.launch({ headless: true });
+ *
+ *  await actorCalled('Polly')
+ *      .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *      .attemptsTo(
+ *          Wait.upTo(Duration.ofSeconds(3))
+ *              .until(App.status(), equals('Ready!')),
+ *          // app is ready, proceed with the scenario
+ *      );
+ * ```
+ *
+ * ## Learn more
+ * - [`SerenityConfig.interactionTimeout`](https://serenity-js.org/api/core/class/SerenityConfig/#interactionTimeout)
+ * - [`Duration`](https://serenity-js.org/api/core/class/Duration/)
+ * - [`Expectation`](https://serenity-js.org/api/core/class/Expectation/)
+ *
+ * @group Time
+ */
+export declare class Wait {
+    /**
+     * Minimum timeout that can be used with [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until),
+     * defaults to 250 milliseconds,
+     */
+    static readonly minimumTimeout: Duration;
+    /**
+     * The amount of time [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until) should wait between condition checks,
+     * defaults to 500ms.
+     *
+     * Use [`WaitUntil.pollingEvery`](https://serenity-js.org/api/core/class/WaitUntil/#pollingEvery) to override it for a given interaction.
+     *
+     * @type {Duration}
+     */
+    static readonly defaultPollingInterval: Duration;
+    /**
+     * Minimum polling interval of 50ms between condition checks, used with [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until).
+     */
+    static readonly minimumPollingInterval: Duration;
+    /**
+     * Instantiates a version of this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/)
+     * configured to wait for a set duration.
+     *
+     * @param duration
+     *  A set duration the [`Actor`](https://serenity-js.org/api/core/class/Actor/) should wait for before proceeding.
+     */
+    static for(duration: Answerable<Duration>): Interaction;
+    /**
+     * Instantiates a version of this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/)
+     * configured to wait until the answer to the question `actual` meets the `expectation`,
+     * or the `timeout` expires.
+     *
+     * @param timeout
+     *  Custom timeout to override [`SerenityConfig.interactionTimeout`](https://serenity-js.org/api/core/class/SerenityConfig/#interactionTimeout)
+     */
+    static upTo(timeout: Duration): {
+        until: <Actual>(actual: Answerable<Actual>, expectation: Expectation<Actual>) => WaitUntil<Actual>;
+    };
+    /**
+     * Instantiates a version of this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/) configured to
+     * poll every [`Wait.defaultPollingInterval`](https://serenity-js.org/api/core/class/Wait/#defaultPollingInterval) for the result of the provided
+     * question (`actual`) until it meets the `expectation`,
+     * or the timeout expires.
+     *
+     * @param actual
+     *  An [`Answerable`](https://serenity-js.org/api/core/#Answerable) that the [`Actor`](https://serenity-js.org/api/core/class/Actor/) will keep answering
+     *  until the answer meets the [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) provided, or the timeout expires.
+     *
+     * @param expectation
+     *  An [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) to be met before proceeding
+     */
+    static until<Actual>(actual: Answerable<Actual>, expectation: Expectation<Actual>): WaitUntil<Actual>;
+}
+/**
+ * Synchronisation statement that instructs the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to wait before proceeding until a given [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) is met.
+ *
+ * :::tip
+ * To instantiate the [interaction](https://serenity-js.org/api/core/class/Interaction/) to [`WaitUntil`](https://serenity-js.org/api/core/class/WaitUntil/),
+ * use the factory method [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until).
+ * :::
+ *
+ * ## Learn more
+ * * [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until)
+ *
+ * @group Time
+ */
+export declare class WaitUntil<Actual> extends Interaction {
+    private readonly actual;
+    private readonly expectation;
+    private readonly pollingInterval;
+    private readonly timeout?;
+    constructor(actual: Answerable<Actual>, expectation: Expectation<Actual>, pollingInterval: Duration, timeout?: Duration);
+    /**
+     * Configure how frequently the [`Actor`](https://serenity-js.org/api/core/class/Actor/) should check if the answer meets the expectation.
+     *
+     * Note that the polling interval defines the delay between subsequent attempts
+     * to evaluate the expected value, and doesn't include the amount of time
+     * it take the actor to evaluate the value itself.
+     *
+     * @param interval
+     */
+    pollingEvery(interval: Duration): Interaction;
+    /**
+     * @inheritDoc
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+}
+//# sourceMappingURL=Wait.d.ts.map

package/esm/screenplay/time/activities/Wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Wait.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/time/activities/Wait.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAqB,MAAM,0BAA0B,CAAC;AAIjG,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwHG;AACH,qBAAa,IAAI;IAEb;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,cAAc,WAAgC;IAE9D;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,CAAC,sBAAsB,WAAgC;IAEtE;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,sBAAsB,WAA+B;IAErE;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,WAAW;IAIvD;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC,MAAM,CAAC,CAAA;KAAE;IAOtI;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;CAGxG;AAiBD;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS,CAAC,MAAM,CAAE,SAAQ,WAAW;IAE1C,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAHR,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAC1B,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,eAAe,EAAE,QAAQ,EACzB,OAAO,CAAC,EAAE,QAAQ;IAYvC;;;;;;;;OAQG;IACH,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW;IAI7C;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAmC1E"}

package/esm/screenplay/time/activities/Wait.js

@@ -0,0 +1,273 @@
+import { ensure, isGreaterThanOrEqualTo, isInRange } from 'tiny-types';
+import { AssertionError, ListItemNotFoundError, RaiseErrors, TimeoutExpiredError } from '../../../errors/index.js';
+import { d } from '../../../io/index.js';
+import { Interaction } from '../../Interaction.js';
+import { the } from '../../questions/index.js';
+import { ExpectationMet } from '../../questions/index.js';
+import { ScheduleWork } from '../abilities/index.js';
+import { Duration } from '../models/index.js';
+/**
+ * `Wait` is a synchronisation statement that instructs the [actor](https://serenity-js.org/api/core/class/Actor/)
+ * to wait before proceeding with their next [activity](https://serenity-js.org/api/core/class/Activity/),
+ * either for a set [duration](https://serenity-js.org/api/core/class/Duration/), or until a given [expectation](https://serenity-js.org/api/core/class/Expectation/) is met.
+ *
+ * You can configure the timeout of the interaction to [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until):
+ * - globally, using [`SerenityConfig.interactionTimeout`](https://serenity-js.org/api/core/class/SerenityConfig/#interactionTimeout)
+ * - locally, on a per-interaction basis using [`Wait.upTo`](https://serenity-js.org/api/core/class/Wait/#upTo)
+ *
+ * :::tip Portable waiting
+ * Serenity/JS implements `Wait` from scratch, so that the behaviour is consistent no matter the integration tool you use (Playwright, WebdriverIO, Selenium, etc.)
+ * or the type of testing you do (Web, REST API, component testing, etc.)
+ * :::
+ *
+ * ## Wait with Web-based tests
+ *
+ * ### Example widget
+ *
+ * ```html
+ * <!--
+ *     After about 1 second, the text will change from 'Loading...' to 'Ready!'
+ * -->
+ * <h1 id="status">Loading...</h1>
+ * <script>
+ *     (function () {
+ *         setTimeout(function () {
+ *             document.getElementById('status').textContent = 'Ready!'
+ *         }, 1000);
+ *     })();
+ * </script>
+ * ```
+ *
+ * ### Lean Page Object describing the widget
+ *
+ * ```ts
+ * import { By, PageElement, Text } from '@serenity-js/web'
+ *
+ * class App {
+ *   static status = () =>
+ *      Text.of(PageElement.located(By.id('status'))
+ *          .describedAs('status widget'))
+ *  }
+ * ```
+ *
+ * ### Waiting for a set duration
+ *
+ * ```ts
+ * import { actorCalled, Duration, Wait } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch({ headless: true })
+ *
+ * await actorCalled('Inês')
+ *   .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *   .attemptsTo(
+ *       Wait.for(Duration.ofMilliseconds(1_500)),
+ *       Ensure.that(App.status(), equals('Ready!')),
+ *   );
+ * ```
+ *
+ * **Please note** that while the above implementation works,
+ * this approach is inefficient because at best
+ * the actor might wait too long and at worst the test
+ * might become "flaky" if any external interference
+ * (like network glitches, animations taking a bit too long etc.)
+ * makes the actor wait not long enough.
+ *
+ * ### Waiting until a condition is met
+ *
+ * ```ts
+ * import { actorCalled, Wait } from '@serenity-js/core'
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+ * import { equals } from '@serenity-js/assertions'
+ * import { Browser, chromium } from 'playwright'
+ *
+ * const browser = await chromium.launch({ headless: true })
+ *
+ * await actorCalled('Wendy')
+ *     .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *     .attemptsTo(
+ *         Wait.until(App.status(), equals('Ready!')),
+ *         // app is ready, proceed with the scenario
+ *     );
+ * ```
+ *
+ * `Wait.until` makes the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * keep asking the [`Question`](https://serenity-js.org/api/core/class/Question/),
+ * in this case `Text.of(App.status)`, until the answer meets
+ * the expectation, or a timeout expires (default: 5s).
+ *
+ * **Please note** that both Ensure and Wait can be used with
+ * the same expectations, like `equals` or `includes`.
+ *
+ * ### Changing the default timeout
+ *
+ * ```ts
+ *  import { actorCalled, Duration, Wait } from '@serenity-js/core';
+ *  import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright';
+ *  import { equals } from '@serenity-js/assertions';
+ *  import { Browser, chromium } from 'playwright';
+ *
+ *  const browser: Browser = await chromium.launch({ headless: true });
+ *
+ *  await actorCalled('Polly')
+ *      .whoCan(BrowseTheWebWithPlaywright.using(browser))
+ *      .attemptsTo(
+ *          Wait.upTo(Duration.ofSeconds(3))
+ *              .until(App.status(), equals('Ready!')),
+ *          // app is ready, proceed with the scenario
+ *      );
+ * ```
+ *
+ * ## Learn more
+ * - [`SerenityConfig.interactionTimeout`](https://serenity-js.org/api/core/class/SerenityConfig/#interactionTimeout)
+ * - [`Duration`](https://serenity-js.org/api/core/class/Duration/)
+ * - [`Expectation`](https://serenity-js.org/api/core/class/Expectation/)
+ *
+ * @group Time
+ */
+export class Wait {
+    /**
+     * Minimum timeout that can be used with [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until),
+     * defaults to 250 milliseconds,
+     */
+    static minimumTimeout = Duration.ofMilliseconds(250);
+    /**
+     * The amount of time [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until) should wait between condition checks,
+     * defaults to 500ms.
+     *
+     * Use [`WaitUntil.pollingEvery`](https://serenity-js.org/api/core/class/WaitUntil/#pollingEvery) to override it for a given interaction.
+     *
+     * @type {Duration}
+     */
+    static defaultPollingInterval = Duration.ofMilliseconds(500);
+    /**
+     * Minimum polling interval of 50ms between condition checks, used with [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until).
+     */
+    static minimumPollingInterval = Duration.ofMilliseconds(50);
+    /**
+     * Instantiates a version of this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/)
+     * configured to wait for a set duration.
+     *
+     * @param duration
+     *  A set duration the [`Actor`](https://serenity-js.org/api/core/class/Actor/) should wait for before proceeding.
+     */
+    static for(duration) {
+        return new WaitFor(duration);
+    }
+    /**
+     * Instantiates a version of this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/)
+     * configured to wait until the answer to the question `actual` meets the `expectation`,
+     * or the `timeout` expires.
+     *
+     * @param timeout
+     *  Custom timeout to override [`SerenityConfig.interactionTimeout`](https://serenity-js.org/api/core/class/SerenityConfig/#interactionTimeout)
+     */
+    static upTo(timeout) {
+        return {
+            until: (actual, expectation) => new WaitUntil(actual, expectation, Wait.defaultPollingInterval.isLessThan(timeout) ? Wait.defaultPollingInterval : timeout, timeout),
+        };
+    }
+    /**
+     * Instantiates a version of this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/) configured to
+     * poll every [`Wait.defaultPollingInterval`](https://serenity-js.org/api/core/class/Wait/#defaultPollingInterval) for the result of the provided
+     * question (`actual`) until it meets the `expectation`,
+     * or the timeout expires.
+     *
+     * @param actual
+     *  An [`Answerable`](https://serenity-js.org/api/core/#Answerable) that the [`Actor`](https://serenity-js.org/api/core/class/Actor/) will keep answering
+     *  until the answer meets the [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) provided, or the timeout expires.
+     *
+     * @param expectation
+     *  An [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) to be met before proceeding
+     */
+    static until(actual, expectation) {
+        return new WaitUntil(actual, expectation, Wait.defaultPollingInterval);
+    }
+}
+/**
+ * @package
+ */
+class WaitFor extends Interaction {
+    duration;
+    constructor(duration) {
+        super(the `#actor waits for ${duration}`);
+        this.duration = duration;
+    }
+    async performAs(actor) {
+        const duration = await actor.answer(this.duration);
+        return ScheduleWork.as(actor).waitFor(duration);
+    }
+}
+/**
+ * Synchronisation statement that instructs the [`Actor`](https://serenity-js.org/api/core/class/Actor/) to wait before proceeding until a given [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) is met.
+ *
+ * :::tip
+ * To instantiate the [interaction](https://serenity-js.org/api/core/class/Interaction/) to [`WaitUntil`](https://serenity-js.org/api/core/class/WaitUntil/),
+ * use the factory method [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until).
+ * :::
+ *
+ * ## Learn more
+ * * [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until)
+ *
+ * @group Time
+ */
+export class WaitUntil extends Interaction {
+    actual;
+    expectation;
+    pollingInterval;
+    timeout;
+    constructor(actual, expectation, pollingInterval, timeout) {
+        super(the `#actor waits until ${actual} does ${expectation}`);
+        this.actual = actual;
+        this.expectation = expectation;
+        this.pollingInterval = pollingInterval;
+        this.timeout = timeout;
+        if (timeout) {
+            ensure('Timeout', timeout.inMilliseconds(), isGreaterThanOrEqualTo(Wait.minimumTimeout.inMilliseconds()));
+            ensure('Polling interval', pollingInterval.inMilliseconds(), isInRange(Wait.minimumPollingInterval.inMilliseconds(), timeout.inMilliseconds()));
+        }
+        ensure('Polling interval', pollingInterval.inMilliseconds(), isGreaterThanOrEqualTo(Wait.minimumPollingInterval.inMilliseconds()));
+    }
+    /**
+     * Configure how frequently the [`Actor`](https://serenity-js.org/api/core/class/Actor/) should check if the answer meets the expectation.
+     *
+     * Note that the polling interval defines the delay between subsequent attempts
+     * to evaluate the expected value, and doesn't include the amount of time
+     * it take the actor to evaluate the value itself.
+     *
+     * @param interval
+     */
+    pollingEvery(interval) {
+        return new WaitUntil(this.actual, this.expectation, interval, this.timeout);
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        await ScheduleWork.as(actor).repeatUntil(() => actor.answer(this.expectation.isMetFor(this.actual)), {
+            exitCondition: outcome => outcome instanceof ExpectationMet,
+            delayBetweenInvocations: (invocation) => invocation === 0
+                ? Duration.ofMilliseconds(0)
+                : this.pollingInterval,
+            timeout: this.timeout,
+            errorHandler: (error, outcome) => {
+                if (error instanceof ListItemNotFoundError) {
+                    return; // ignore, lists might get populated later
+                }
+                if (error instanceof TimeoutExpiredError) {
+                    throw RaiseErrors.as(actor).create(AssertionError, {
+                        message: error.message + d ` while waiting for ${this.actual} to ${this.expectation}`,
+                        expectation: outcome?.expectation,
+                        diff: outcome && { expected: outcome?.expected, actual: outcome?.actual },
+                        location: this.instantiationLocation(),
+                        cause: error,
+                    });
+                }
+                throw error;
+            }
+        });
+    }
+}
+//# sourceMappingURL=Wait.js.map

package/esm/screenplay/time/activities/Wait.js.map

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

package/esm/screenplay/time/activities/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Wait.js';
+//# sourceMappingURL=index.d.ts.map

package/esm/screenplay/time/activities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/screenplay/time/activities/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/esm/screenplay/time/activities/index.js

@@ -0,0 +1,2 @@
+export * from './Wait.js';
+//# sourceMappingURL=index.js.map

package/esm/screenplay/time/activities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/screenplay/time/activities/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

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

@@ -0,0 +1,5 @@
+export * from './abilities/index.js';
+export * from './activities/index.js';
+export * from './models/index.js';
+export * from './TellsTime.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/time/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}