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