Skip to main content

Expectation <Actual>

Defines an expectation to be used with Wait.until, Check.whether, Ensure.that and as part of the Page Element Query Language with PageElements.where and List.where.

Index

Methods

Methods

staticdefine

  • define<Actual_Type, PredicateArguments>(functionName: string, relationship: string | (...answerableArguments: AnswerableArguments<PredicateArguments>) => string, predicate: (actual: Actual_Type, ...predicateArguments: PredicateArguments) => boolean | Promise<boolean>): (...answerableArguments: AnswerableArguments<PredicateArguments>) => Expectation<Actual_Type>

  • A factory method to that makes defining custom expectations easier

    Defining a custom expectation

    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

    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

    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

    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

    Type parameters

    • Actual_Type
    • PredicateArguments: unknown[]

    Parameters

    • functionName: string

      Name of the expectation function to be used when producing an AssertionError

    • relationship: string | (...answerableArguments: AnswerableArguments<PredicateArguments>) => string

      Human-readable description of the relationship between the expected and the actual values. Used when reporting activities performed by an actor

    • predicate: (actual: Actual_Type, ...predicateArguments: PredicateArguments) => boolean | Promise<boolean>

    Returns (...answerableArguments: AnswerableArguments<PredicateArguments>) => Expectation<Actual_Type>

      • (...answerableArguments: AnswerableArguments<PredicateArguments>): Expectation<Actual_Type>

      • A factory method to that makes defining custom expectations easier

        Defining a custom expectation

        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

        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

        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

        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

        Parameters

        • rest...answerableArguments: AnswerableArguments<PredicateArguments>

        Returns Expectation<Actual_Type>

staticthatActualShould

  • thatActualShould<Expected_Type, Actual_Type>(relationshipName: string, expectedValue?: Answerable<Expected_Type>): { soThat: (simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => boolean | Promise<boolean>) => Expectation<Actual_Type> }

  • Used to define a simple Expectation

    Simple parameterised expectation

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

    Type parameters

    • Expected_Type
    • Actual_Type

    Parameters

    • relationshipName: string

      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.

    • optionalexpectedValue: Answerable<Expected_Type>

    Returns { soThat: (simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => boolean | Promise<boolean>) => Expectation<Actual_Type> }

    • soThat: (simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => boolean | Promise<boolean>) => Expectation<Actual_Type>
        • (simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => boolean | Promise<boolean>): Expectation<Actual_Type>

        • Parameters

          • simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => boolean | Promise<boolean>

          Returns Expectation<Actual_Type>

staticto

  • to<Actual_Type>(relationshipName: string): { soThatActual: (expectation: Expectation<Actual_Type>) => Expectation<Actual_Type> }

  • Used to compose expectations.

    Composing expectations

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

    Type parameters

    • Actual_Type

    Parameters

    • relationshipName: string

      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.

    Returns { soThatActual: (expectation: Expectation<Actual_Type>) => Expectation<Actual_Type> }

isMetFor

describedAs

  • @inheritDoc

    Parameters

    • subject: string

    Returns Expectation<Actual>

toString

  • toString(): string
  • @inheritDoc

    Returns string