externalEnsureEventually <Actual>

experimental

The interaction to EnsureEventually verifies if the resolved value of the provided Answerable meets the specified Expectation within the expected timeframe.

If the expectation is not met by the time the timeout expires, the interaction throws an AssertionError. EnsureEventually retries the evaluation if resolving the actual results in an ListItemNotFoundError, but rethrows any other errors.

Use the factory method

Use the factory method [Ensure.eventually](/api/assertions/class/Ensure/#eventually] to instantiate this interaction.

Basic usage with dynamic values

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

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

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`)
)

Hierarchy

• Interaction
  • EnsureEventually

Index

Constructors

• constructor

Methods

• timeoutAfter
• performAs
• otherwiseFailWith
• instantiationLocation
• describedBy
• toString

Constructors

externalconstructor

• new EnsureEventually<Actual>(actual: Answerable<Actual>, expectation: Expectation<Actual>, location: FileSystemLocation, timeout?: Duration): EnsureEventually<Actual>

• Overrides Interaction.constructor

  Type parameters

  • Actual

  Parameters

  • externalactual: Answerable<Actual>

  • externalexpectation: Expectation<Actual>

  • externallocation: FileSystemLocation

  • externaloptionaltimeout: Duration

  Returns EnsureEventually<Actual>

Methods

externaltimeoutAfter

• timeoutAfter(timeout: Duration): EnsureEventually<Actual>

• Override the default timeout set via SerenityConfig.interactionTimeout.

  ---

  Parameters

  • externaltimeout: Duration

  Returns EnsureEventually<Actual>

externalperformAs

• performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void>

• Overrides Interaction.performAs

  @inheritDoc

  ---

  Parameters

  • externalactor: UsesAbilities & AnswersQuestions & CollectsArtifacts

  Returns Promise<void>

externalotherwiseFailWith

• otherwiseFailWith(typeOfRuntimeError: new (message: string, cause?: Error) => RuntimeError, message?: string): Interaction

• Overrides the default AssertionError thrown when the actual value does not meet the expectation.

  ---

  Parameters

  • externaltypeOfRuntimeError: new (message: string, cause?: Error) => RuntimeError

    A constructor function producing a subtype of RuntimeError to throw, e.g. TestCompromisedError

  • externaloptionalmessage: string

    The message explaining the failure

  Returns Interaction

externalinstantiationLocation

• instantiationLocation(): FileSystemLocation

• Inherited from Interaction.instantiationLocation

  Returns the location where this Activity was instantiated.

  ---

  Returns FileSystemLocation

externaldescribedBy

• describedBy(actor: AnswersQuestions & UsesAbilities & { name: string }): Promise<string>

• Inherited from Interaction.describedBy

  Resolves the description of this object in the context of the provided actor.

  ---

  Parameters

  • externalactor: AnswersQuestions & UsesAbilities & { name: string }

  Returns Promise<string>

externaltoString

• toString(): string

• Inherited from Interaction.toString

  Returns a human-readable description of this object.

  ---

  Returns string