@serenity-js/assertions/lib/EnsureEventually.js

Serenity/JS universal assertion library supporting all types of functional tests, including both web and REST API scenarios

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.EnsureEventually = void 0;
const core_1 = require("@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
 */
class EnsureEventually extends core_1.Interaction {
    actual;
    expectation;
    timeout;
    /**
     * @param actual
     * @param expectation
     * @param location
     * @param timeout
     */
    constructor(actual, expectation, location, timeout) {
        super((0, core_1.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 core_1.ScheduleWork.as(actor).repeatUntil(() => actor.answer(this.expectation.isMetFor(this.actual)), {
            exitCondition: outcome => outcome instanceof core_1.ExpectationMet,
            delayBetweenInvocations: (invocation) => invocation === 0
                ? core_1.Duration.ofMilliseconds(0) // perform the first evaluation straight away
                : core_1.Duration.ofMilliseconds(2 ** invocation * 100), // use simple exponential backoff strategy for subsequent calls
            timeout: this.timeout,
            errorHandler: (error, outcome) => {
                if (error instanceof core_1.ListItemNotFoundError) {
                    return; // ignore, lists might get populated later
                }
                if (error instanceof core_1.TimeoutExpiredError) {
                    const actualDescription = (0, core_1.d) `${this.actual}`;
                    const message = outcome ? `Expected ${actualDescription} to eventually ${outcome?.message}` : error.message;
                    throw core_1.RaiseErrors.as(actor).create(core_1.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 core_1.Interaction.where(this.toString(), async (actor) => {
            try {
                await this.performAs(actor);
            }
            catch (error) {
                throw core_1.RaiseErrors.as(actor).create(typeOfRuntimeError, {
                    message: message ?? error.message,
                    location,
                    cause: error,
                });
            }
        });
    }
}
exports.EnsureEventually = EnsureEventually;
//# sourceMappingURL=EnsureEventually.js.map