Skip to main content

externalExpectation <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.

Hierarchy

Index

Methods

Methods

staticexternaldefine

  • define<Actual_Type, PredicateArguments>(functionName: string, relationship: Answerable<string> | (...answerableArguments: AnswerableArguments<PredicateArguments>) => Answerable<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

    • externalfunctionName: string

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

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

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

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

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

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

          • Parameters

            • externalrest...answerableArguments: AnswerableArguments<PredicateArguments>

            Returns Expectation<Actual_Type>

      staticexternalthatActualShould

      • 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

        • externalrelationshipName: 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.

        • externaloptionalexpectedValue: Answerable<Expected_Type>

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

        • externalsoThat: (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

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

                Returns Expectation<Actual_Type>

        staticexternalto

        • 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

          • externalrelationshipName: 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> }

        externaldescribedBy

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

          Parameters

          Returns Promise<string>

        externaltoString

        • toString(): string

        • Returns a human-readable description of this object.

          Returns string

        externalisMetFor

        externaldescribedAs

        • describedAs(description: Answerable<string>): this
        • @inheritDoc

          Parameters

          Returns this