@serenity-js/assertions 3.41.1 → 3.42.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.42.0](https://github.com/serenity-js/serenity-js/compare/v3.41.2...v3.42.0) (2026-03-19)
+
+
+### Features
+
+* **core:** add dual ESM/CJS build support for Wave 2 packages ([0e2631c](https://github.com/serenity-js/serenity-js/commit/0e2631ca7cdbe68da7feec343eaf4f7fe9bb64d6))
+* **core:** add ESM/CJS dual build support for web packages ([94c5a64](https://github.com/serenity-js/serenity-js/commit/94c5a6423dc369477bbabbacee5a54f8fca20209))
+
+
+
+
+
+## [3.41.2](https://github.com/serenity-js/serenity-js/compare/v3.41.1...v3.41.2) (2026-03-05)
+
+**Note:** Version bump only for package @serenity-js/assertions
+
+
+
+
+
 ## [3.41.1](https://github.com/serenity-js/serenity-js/compare/v3.41.0...v3.41.1) (2026-02-27)
 
 **Note:** Version bump only for package @serenity-js/assertions

package/esm/Ensure.d.ts

@@ -0,0 +1,110 @@
+import type { Answerable, AnswersQuestions, CollectsArtifacts, Expectation, RuntimeError, UsesAbilities } from '@serenity-js/core';
+import { Interaction } from '@serenity-js/core';
+import { EnsureEventually } from './EnsureEventually.js';
+/**
+ * The [interaction](https://serenity-js.org/api/core/class/Interaction/) to `Ensure`
+ * verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+ * meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/).
+ * If not, it throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
+ *
+ * Use `Ensure` to verify the state of the system under test.
+ *
+ * ## Basic usage with static values
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.that('Hello world!', equals('Hello world!'))
+ * )
+ * ```
+ *
+ * ## Composing expectations with `and`
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.that('Hello world!', and(startsWith('Hello'), endsWith('!'))
+ * )
+ * ```
+ *
+ * ## Overriding the type of Error thrown upon assertion failure
+ *
+ * ```ts
+ * import { actorCalled, TestCompromisedError } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ *
+ * await actorCalled('Erica')
+ *   .whoCan(CallAnApi.at('https://example.com'))
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/api/health')),
+ *     Ensure.that(LastResponse.status(), equals(200))
+ *       .otherwiseFailWith(TestCompromisedError, 'The server is down, please cheer it up!')
+ *   )
+ * ```
+ *
+ * @group Activities
+ */
+export declare class Ensure<Actual> extends Interaction {
+    protected readonly actual: Answerable<Actual>;
+    protected readonly expectation: Expectation<Actual>;
+    /**
+     * Creates an [interaction](https://serenity-js.org/api/core/class/Interaction/) to `Ensure`, which
+     * verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/).
+     * If not, it immediately throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
+     *
+     * @param {Answerable<Actual_Type>} actual
+     *  An [`Answerable`](https://serenity-js.org/api/core/#Answerable) describing the actual state of the system.
+     *
+     * @param {Expectation<Actual_Type>} expectation
+     *  An [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) you expect the `actual` value to meet
+     *
+     * @returns {Ensure<Actual_Type>}
+     */
+    static that<Actual_Type>(actual: Answerable<Actual_Type>, expectation: Expectation<Actual_Type>): Ensure<Actual_Type>;
+    /**
+     * Creates an [interaction](https://serenity-js.org/api/core/class/Interaction/) to [`EnsureEventually`](https://serenity-js.org/api/assertions/class/EnsureEventually/),
+     * which verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) within the expected timeframe.
+     *
+     * After the first try, it waits longer and longer between checks, following a simple exponential backoff pattern (2^try * 100). So 0ms the first
+     * time, then 200ms, 400ms, 800ms, 1600ms, 3200ms and so on.
+     *
+     * If the expectation is not met by the time the timeout expires, the interaction throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
+     *
+     * @param {Answerable<Actual_Type>} actual
+     *  An [`Answerable`](https://serenity-js.org/api/core/#Answerable) describing the actual state of the system.
+     *
+     * @param {Expectation<Actual_Type>} expectation
+     *  An [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) you expect the `actual` value to meet
+     *
+     * @returns {Ensure<Actual_Type>}
+     */
+    static eventually<Actual_Type>(actual: Answerable<Actual_Type>, expectation: Expectation<Actual_Type>): EnsureEventually<Actual_Type>;
+    /**
+     * @param actual
+     * @param expectation
+     * @param location
+     */
+    private constructor();
+    /**
+     * @inheritDoc
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void>;
+    /**
+     * Overrides the default [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/) thrown when
+     * the actual value does not meet the expectation.
+     *
+     * @param typeOfRuntimeError
+     *  A constructor function producing a subtype of [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/) to throw, e.g. [`TestCompromisedError`](https://serenity-js.org/api/core/class/TestCompromisedError/)
+     *
+     * @param message
+     *  The message explaining the failure
+     */
+    otherwiseFailWith(typeOfRuntimeError: new (message: string, cause?: Error) => RuntimeError, message?: string): Interaction;
+}
+//# sourceMappingURL=Ensure.d.ts.map

package/esm/Ensure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ensure.d.ts","sourceRoot":"","sources":["../src/Ensure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAMH,WAAW,EAKd,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,MAAM,CAAC,MAAM,CAAE,SAAQ,WAAW;IAgDvC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC;IA/CvD;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC;IAIrH;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,gBAAgB,CAAC,WAAW,CAAC;IAIrI;;;;OAIG;IACH,OAAO;IAQP;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB3F;;;;;;;;;OASG;IACH,iBAAiB,CAAC,kBAAkB,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW;CAgB7H"}

package/esm/Ensure.js

@@ -0,0 +1,148 @@
+import { Activity, AssertionError, ExpectationMet, ExpectationNotMet, f, Interaction, LogicError, Question, RaiseErrors, the } from '@serenity-js/core';
+import { EnsureEventually } from './EnsureEventually.js';
+/**
+ * The [interaction](https://serenity-js.org/api/core/class/Interaction/) to `Ensure`
+ * verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+ * meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/).
+ * If not, it throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
+ *
+ * Use `Ensure` to verify the state of the system under test.
+ *
+ * ## Basic usage with static values
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.that('Hello world!', equals('Hello world!'))
+ * )
+ * ```
+ *
+ * ## Composing expectations with `and`
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.that('Hello world!', and(startsWith('Hello'), endsWith('!'))
+ * )
+ * ```
+ *
+ * ## Overriding the type of Error thrown upon assertion failure
+ *
+ * ```ts
+ * import { actorCalled, TestCompromisedError } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
+ *
+ * await actorCalled('Erica')
+ *   .whoCan(CallAnApi.at('https://example.com'))
+ *   .attemptsTo(
+ *     Send.a(GetRequest.to('/api/health')),
+ *     Ensure.that(LastResponse.status(), equals(200))
+ *       .otherwiseFailWith(TestCompromisedError, 'The server is down, please cheer it up!')
+ *   )
+ * ```
+ *
+ * @group Activities
+ */
+export class Ensure extends Interaction {
+    actual;
+    expectation;
+    /**
+     * Creates an [interaction](https://serenity-js.org/api/core/class/Interaction/) to `Ensure`, which
+     * verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/).
+     * If not, it immediately throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
+     *
+     * @param {Answerable<Actual_Type>} actual
+     *  An [`Answerable`](https://serenity-js.org/api/core/#Answerable) describing the actual state of the system.
+     *
+     * @param {Expectation<Actual_Type>} expectation
+     *  An [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) you expect the `actual` value to meet
+     *
+     * @returns {Ensure<Actual_Type>}
+     */
+    static that(actual, expectation) {
+        return new Ensure(actual, expectation, Activity.callerLocation(5));
+    }
+    /**
+     * Creates an [interaction](https://serenity-js.org/api/core/class/Interaction/) to [`EnsureEventually`](https://serenity-js.org/api/assertions/class/EnsureEventually/),
+     * which verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+     * meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) within the expected timeframe.
+     *
+     * After the first try, it waits longer and longer between checks, following a simple exponential backoff pattern (2^try * 100). So 0ms the first
+     * time, then 200ms, 400ms, 800ms, 1600ms, 3200ms and so on.
+     *
+     * If the expectation is not met by the time the timeout expires, the interaction throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
+     *
+     * @param {Answerable<Actual_Type>} actual
+     *  An [`Answerable`](https://serenity-js.org/api/core/#Answerable) describing the actual state of the system.
+     *
+     * @param {Expectation<Actual_Type>} expectation
+     *  An [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) you expect the `actual` value to meet
+     *
+     * @returns {Ensure<Actual_Type>}
+     */
+    static eventually(actual, expectation) {
+        return new EnsureEventually(actual, expectation, Activity.callerLocation(5));
+    }
+    /**
+     * @param actual
+     * @param expectation
+     * @param location
+     */
+    constructor(actual, expectation, location) {
+        super(the `#actor ensures that ${actual} does ${expectation}`, location);
+        this.actual = actual;
+        this.expectation = expectation;
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const outcome = await actor.answer(this.expectation.isMetFor(this.actual));
+        if (outcome instanceof ExpectationNotMet) {
+            const actualDescription = this.actual === undefined
+                ? 'undefined'
+                : Question.formattedValue().of(this.actual);
+            const message = `Expected ${actualDescription} to ${outcome.message}`;
+            throw RaiseErrors.as(actor).create(AssertionError, {
+                message,
+                expectation: outcome.expectation,
+                diff: { expected: outcome.expected, actual: outcome.actual },
+                location: this.instantiationLocation(),
+            });
+        }
+        if (!(outcome instanceof ExpectationMet)) {
+            throw new LogicError(f `Expectation#isMetFor(actual) should return an instance of an ExpectationOutcome, not ${outcome}`);
+        }
+    }
+    /**
+     * Overrides the default [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/) thrown when
+     * the actual value does not meet the expectation.
+     *
+     * @param typeOfRuntimeError
+     *  A constructor function producing a subtype of [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/) to throw, e.g. [`TestCompromisedError`](https://serenity-js.org/api/core/class/TestCompromisedError/)
+     *
+     * @param message
+     *  The message explaining the failure
+     */
+    otherwiseFailWith(typeOfRuntimeError, message) {
+        const location = this.instantiationLocation();
+        return Interaction.where(this.toString(), async (actor) => {
+            try {
+                await this.performAs(actor);
+            }
+            catch (error) {
+                throw RaiseErrors.as(actor).create(typeOfRuntimeError, {
+                    message: message ?? error.message,
+                    location,
+                    cause: error
+                });
+            }
+        });
+    }
+}
+//# sourceMappingURL=Ensure.js.map

package/esm/Ensure.js.map

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

package/esm/EnsureEventually.d.ts

@@ -0,0 +1,98 @@
+import type { Answerable, AnswersQuestions, CollectsArtifacts, Expectation, RuntimeError, UsesAbilities } from '@serenity-js/core';
+import { Duration, Interaction } from '@serenity-js/core';
+import type { FileSystemLocation } from '@serenity-js/core/io';
+/**
+ * The [interaction](https://serenity-js.org/api/core/class/Interaction/) to `EnsureEventually`
+ * verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+ * meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) within the expected timeframe.
+ *
+ * If the expectation is not met by the time the timeout expires, the interaction throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
+ * `EnsureEventually` retries the evaluation if resolving the `actual` results in an [`ListItemNotFoundError`](https://serenity-js.org/api/core/class/ListItemNotFoundError/),
+ * but rethrows any other errors.
+ *
+ * :::tip Use the factory method
+ * Use the factory method [`Ensure.eventually`](https://serenity-js.org/api/assertions/class/Ensure/#eventually) to instantiate this interaction.
+ * :::
+ *
+ * ## Basic usage with dynamic values
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     equals('Learn Serenity/JS!')
+ *   )
+ * )
+ * ```
+ *
+ * ## Composing expectations with `and`
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     and(startsWith('Serenity'), endsWith('!'))
+ *   )
+ * )
+ * ```
+ *
+ * ## Overriding the type of Error thrown upon assertion failure
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     and(startsWith('Serenity'), endsWith('!'))
+ *   ).otherwiseFailWith(LogicError, `Looks like we're not on the right page`)
+ * )
+ * ```
+ *
+ * @experimental
+ *
+ * @group Activities
+ */
+export declare class EnsureEventually<Actual> extends Interaction {
+    protected readonly actual: Answerable<Actual>;
+    protected readonly expectation: Expectation<Actual>;
+    protected readonly timeout?: Duration;
+    /**
+     * @param actual
+     * @param expectation
+     * @param location
+     * @param timeout
+     */
+    constructor(actual: Answerable<Actual>, expectation: Expectation<Actual>, location: FileSystemLocation, timeout?: Duration);
+    /**
+     * Override the default timeout set via [`SerenityConfig.interactionTimeout`](https://serenity-js.org/api/core/class/SerenityConfig/#interactionTimeout).
+     *
+     * @param timeout
+     */
+    timeoutAfter(timeout: Duration): EnsureEventually<Actual>;
+    /**
+     * @inheritDoc
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void>;
+    /**
+     * Overrides the default [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/) thrown when
+     * the actual value does not meet the expectation.
+     *
+     * @param typeOfRuntimeError
+     *  A constructor function producing a subtype of [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/) to throw, e.g. [`TestCompromisedError`](https://serenity-js.org/api/core/class/TestCompromisedError/)
+     *
+     * @param message
+     *  The message explaining the failure
+     */
+    otherwiseFailWith(typeOfRuntimeError: new (message: string, cause?: Error) => RuntimeError, message?: string): Interaction;
+}
+//# sourceMappingURL=EnsureEventually.d.ts.map

package/esm/EnsureEventually.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnsureEventually.d.ts","sourceRoot":"","sources":["../src/EnsureEventually.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EAEX,YAAY,EACZ,aAAa,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGH,QAAQ,EAER,WAAW,EAMd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,qBAAa,gBAAgB,CAAC,MAAM,CAAE,SAAQ,WAAW;IAQjD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC;IAC7C,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC;IAEnD,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ;IAVzC;;;;;OAKG;gBAEoB,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAC1B,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EACnD,QAAQ,EAAE,kBAAkB,EACT,OAAO,CAAC,EAAE,QAAQ;IAKzC;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC;IAIzD;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC3F;;;;;;;;;OASG;IACH,iBAAiB,CAAC,kBAAkB,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW;CAe7H"}

package/esm/EnsureEventually.js

@@ -0,0 +1,142 @@
+import { AssertionError, d, Duration, ExpectationMet, Interaction, ListItemNotFoundError, RaiseErrors, ScheduleWork, the, TimeoutExpiredError } from '@serenity-js/core';
+/**
+ * The [interaction](https://serenity-js.org/api/core/class/Interaction/) to `EnsureEventually`
+ * verifies if the resolved value of the provided [`Answerable`](https://serenity-js.org/api/core/#Answerable)
+ * meets the specified [`Expectation`](https://serenity-js.org/api/core/class/Expectation/) within the expected timeframe.
+ *
+ * If the expectation is not met by the time the timeout expires, the interaction throws an [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/).
+ * `EnsureEventually` retries the evaluation if resolving the `actual` results in an [`ListItemNotFoundError`](https://serenity-js.org/api/core/class/ListItemNotFoundError/),
+ * but rethrows any other errors.
+ *
+ * :::tip Use the factory method
+ * Use the factory method [`Ensure.eventually`](https://serenity-js.org/api/assertions/class/Ensure/#eventually) to instantiate this interaction.
+ * :::
+ *
+ * ## Basic usage with dynamic values
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     equals('Learn Serenity/JS!')
+ *   )
+ * )
+ * ```
+ *
+ * ## Composing expectations with `and`
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     and(startsWith('Serenity'), endsWith('!'))
+ *   )
+ * )
+ * ```
+ *
+ * ## Overriding the type of Error thrown upon assertion failure
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { and, Ensure, startsWith, endsWith } from '@serenity-js/assertions'
+ * import { Text, PageElement, By } from '@serenity-js/web'
+ *
+ * await actorCalled('Erica').attemptsTo(
+ *   Ensure.eventually(
+ *     Text.of(PageElement.located(By.css('h1'))),
+ *     and(startsWith('Serenity'), endsWith('!'))
+ *   ).otherwiseFailWith(LogicError, `Looks like we're not on the right page`)
+ * )
+ * ```
+ *
+ * @experimental
+ *
+ * @group Activities
+ */
+export class EnsureEventually extends Interaction {
+    actual;
+    expectation;
+    timeout;
+    /**
+     * @param actual
+     * @param expectation
+     * @param location
+     * @param timeout
+     */
+    constructor(actual, expectation, location, timeout) {
+        super(the `#actor ensures that ${actual} does eventually ${expectation}`, location);
+        this.actual = actual;
+        this.expectation = expectation;
+        this.timeout = timeout;
+    }
+    /**
+     * Override the default timeout set via [`SerenityConfig.interactionTimeout`](https://serenity-js.org/api/core/class/SerenityConfig/#interactionTimeout).
+     *
+     * @param timeout
+     */
+    timeoutAfter(timeout) {
+        return new EnsureEventually(this.actual, this.expectation, this.instantiationLocation(), 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) // perform the first evaluation straight away
+                : Duration.ofMilliseconds(2 ** invocation * 100), // use simple exponential backoff strategy for subsequent calls
+            timeout: this.timeout,
+            errorHandler: (error, outcome) => {
+                if (error instanceof ListItemNotFoundError) {
+                    return; // ignore, lists might get populated later
+                }
+                if (error instanceof TimeoutExpiredError) {
+                    const actualDescription = d `${this.actual}`;
+                    const message = outcome ? `Expected ${actualDescription} to eventually ${outcome?.message}` : error.message;
+                    throw RaiseErrors.as(actor).create(AssertionError, {
+                        message,
+                        expectation: outcome?.expectation,
+                        diff: outcome && { expected: outcome?.expected, actual: outcome?.actual },
+                        location: this.instantiationLocation(),
+                        cause: error,
+                    });
+                }
+                throw error;
+            },
+        });
+    }
+    /**
+     * Overrides the default [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/) thrown when
+     * the actual value does not meet the expectation.
+     *
+     * @param typeOfRuntimeError
+     *  A constructor function producing a subtype of [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/) to throw, e.g. [`TestCompromisedError`](https://serenity-js.org/api/core/class/TestCompromisedError/)
+     *
+     * @param message
+     *  The message explaining the failure
+     */
+    otherwiseFailWith(typeOfRuntimeError, message) {
+        const location = this.instantiationLocation();
+        return Interaction.where(this.toString(), async (actor) => {
+            try {
+                await this.performAs(actor);
+            }
+            catch (error) {
+                throw RaiseErrors.as(actor).create(typeOfRuntimeError, {
+                    message: message ?? error.message,
+                    location,
+                    cause: error,
+                });
+            }
+        });
+    }
+}
+//# sourceMappingURL=EnsureEventually.js.map

package/esm/EnsureEventually.js.map

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

package/esm/expectations/and.d.ts

@@ -0,0 +1,23 @@
+import { Expectation } from '@serenity-js/core';
+/**
+ * Creates an [expectation](https://serenity-js.org/api/core/class/Expectation/) that is met when all the `expectations` are met for the given actual value.
+ *
+ * Use `and` to combine several expectations using logical "and",
+ *
+ * ## Combining several expectations
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, and, startsWith, endsWith } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that('Hello World!', and(startsWith('Hello'), endsWith('!'))),
+ * )
+ * ```
+ *
+ * @param expectations
+ *
+ * @group Expectations
+ */
+export declare function and<Actual_Type>(...expectations: Array<Expectation<Actual_Type>>): Expectation<Actual_Type>;
+//# sourceMappingURL=and.d.ts.map

package/esm/expectations/and.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"and.d.ts","sourceRoot":"","sources":["../../src/expectations/and.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAqC,MAAM,mBAAmB,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,GAAG,CAAC,WAAW,EAAE,GAAG,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,GAAG,WAAW,CAAC,WAAW,CAAC,CAE3G"}

package/esm/expectations/and.js

@@ -0,0 +1,46 @@
+import { Expectation, ExpectationMet, ExpectationNotMet } from '@serenity-js/core';
+/**
+ * Creates an [expectation](https://serenity-js.org/api/core/class/Expectation/) that is met when all the `expectations` are met for the given actual value.
+ *
+ * Use `and` to combine several expectations using logical "and",
+ *
+ * ## Combining several expectations
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, and, startsWith, endsWith } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that('Hello World!', and(startsWith('Hello'), endsWith('!'))),
+ * )
+ * ```
+ *
+ * @param expectations
+ *
+ * @group Expectations
+ */
+export function and(...expectations) {
+    return new And(expectations);
+}
+/**
+ * @package
+ */
+class And extends Expectation {
+    expectations;
+    static Separator = ' and ';
+    constructor(expectations) {
+        const description = expectations.map(expectation => expectation.toString()).join(And.Separator);
+        super('and', description, async (actor, actual) => {
+            let outcome;
+            for (const expectation of expectations) {
+                outcome = await actor.answer(expectation.isMetFor(actual));
+                if (outcome instanceof ExpectationNotMet) {
+                    return new ExpectationNotMet(description, outcome.expectation, outcome.expected, outcome.actual);
+                }
+            }
+            return new ExpectationMet(description, outcome?.expectation, outcome?.expected, outcome?.actual);
+        });
+        this.expectations = expectations;
+    }
+}
+//# sourceMappingURL=and.js.map

package/esm/expectations/and.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"and.js","sourceRoot":"","sources":["../../src/expectations/and.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,GAAG,CAAc,GAAG,YAA6C;IAC7E,OAAO,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,GAAY,SAAQ,WAAmB;IAGZ;IAFrB,MAAM,CAAU,SAAS,GAAG,OAAO,CAAC;IAE5C,YAA6B,YAAwC;QACjE,MAAM,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAEhG,KAAK,CACD,KAAK,EACL,WAAW,EACX,KAAK,EAAE,KAAuB,EAAE,MAA0B,EAAE,EAAE;YAC1D,IAAI,OAA2B,CAAC;YAEhC,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;gBACrC,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;gBAE1D,IAAI,OAAO,YAAY,iBAAiB,EAAE,CAAC;oBACvC,OAAO,IAAI,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;gBACrG,CAAC;YACL,CAAC;YAED,OAAO,IAAI,cAAc,CAAC,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACrG,CAAC,CACJ,CAAC;QAnBuB,iBAAY,GAAZ,YAAY,CAA4B;IAoBrE,CAAC"}

package/esm/expectations/contain.d.ts

@@ -0,0 +1,27 @@
+import { Expectation } from '@serenity-js/core';
+/**
+ * Produces an [expectation](https://serenity-js.org/api/core/class/Expectation/) that is met when the actual array of `Item[]` contains
+ * at least one `Item` that is equal to the resolved value of `expected`.
+ *
+ * Note that the equality check performs comparison **by value**
+ * using [TinyTypes `equal`](https://github.com/jan-molak/tiny-types/blob/master/src/objects/equal.ts).
+ *
+ * ## Ensuring that the array contains the given item
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure, and, startsWith, endsWith } from '@serenity-js/assertions'
+ *
+ * const items = [ { name: 'apples' }, { name: 'bananas' } ]
+ *
+ * await actorCalled('Ester').attemptsTo(
+ *   Ensure.that(items, contain({ name: 'bananas' })),
+ * )
+ * ```
+ *
+ * @param expected
+ *
+ * @group Expectations
+ */
+export declare const contain: <Item>(expected: import("@serenity-js/core").Answerable<Item>) => Expectation<Item[]>;
+//# sourceMappingURL=contain.d.ts.map

package/esm/expectations/contain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contain.d.ts","sourceRoot":"","sources":["../../src/expectations/contain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,OAAO,GAEf,IAAI,gFAER,CAAC"}