Expectation <Actual>
Index
Methods
staticdefine
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 theactual
values. Used when reporting activities performed by an actorpredicate: (actual: Actual_Type, ...predicateArguments: PredicateArguments) => boolean | Promise<boolean>
Returns (...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
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 theexpected
. Use formathave 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>
Parameters
simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => boolean | Promise<boolean>
Returns Expectation<Actual_Type>
staticto
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 theexpected
. Use formathave 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> }
soThatActual: (expectation: Expectation<Actual_Type>) => Expectation<Actual_Type>
Parameters
expectation: Expectation<Actual_Type>
Returns Expectation<Actual_Type>
isMetFor
Returns a QuestionAdapter that resolves to ExpectationOutcome indicating that the expectation was met or that the expectation was not met
Parameters
actual: Answerable<Actual>
Returns QuestionAdapter<ExpectationOutcome>
describedAs
Parameters
subject: string
Returns Expectation<Actual>
toString
Returns string
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.