Serenity/JS Assertions



@serenity-js/assertions
provides a rich set of Screenplay Pattern-compatible assertions and expectations for verifying the system under test and synchronising the test flow.

Features

- Fluent, expressive assertions following the Screenplay Pattern for readable and maintainable tests.
- Seamless integration with all supported test runners.
- Rich set of built-in matchers for common scenarios, with easy support for custom matchers.
- TypeScript-first design with strong typing for safer, more predictable test code.

Installation

``sh
npm install --save-dev @serenity-js/core @serenity-js/assertions
`

See the Serenity/JS Installation Guide.

Quick Start

`typescript
import { actorCalled } from '@serenity-js/core';
import { Ensure, equals } from '@serenity-js/assertions';

await actorCalled('Alice').attemptsTo(
Ensure.that(2 + 2, equals(4))
)
`

Explore practical examples and in-depth explanations in the Serenity/JS Handbook.

Usage Examples

$3

To perform an assertion, use the Ensure.that
or Ensure.eventually tasks,
along with an appropriate expectation:

`typescript
import { Ensure, endsWith } from '@serenity-js/assertions'
import { actorCalled } from '@serenity-js/core'
import { Navigate, Page } from '@serenity-js/web'

await actorCalled('Erica').attemptsTo(
Navigate.to('https://serenity-js.org'),
Ensure.that(
Page.current().title(),
endsWith('Serenity/JS')
),
)
`

$3

To control the execution flow based on certain conditions, use the Check.whether task:

`typescript
import { actorCalled } from '@serenity-js/core'
import { Check } from '@serenity-js/assertions'
import { Click, isVisible } from '@serenity-js/web'

await actorCalled('Erica').attemptsTo(
Check.whether(NewsletterModal, isVisible())
.andIfSo(Click.on(CloseModalButton)),
)
`

$3

To synchronise the test flow with the state of the System Under Test,
use the Wait.until task:

`typescript
import { actorCalled } from '@serenity-js/core'
import { Click, isVisible, Wait } from '@serenity-js/web'

await actorCalled('Erica').attemptsTo(
Wait.until(CloseModalButton, isVisible()),
Click.on(CloseModalButton)
)
`

$3

To define a custom expectation,
use the Expectation.thatActualShould method:

`typescript
import { actorCalled } from '@serenity-js/core'
import { Expectation, Ensure } from '@serenity-js/assertions'

function isDivisibleBy(expected: Answerable): Expectation {
return Expectation.thatActualShould('have value divisible by', expected)
.soThat((actualValue, expectedValue) => actualValue % expectedValue === 0)
}

await actorCalled('Erica').attemptsTo(
Ensure.that(4, isDivisibleBy(2)),
)
`

$3

To compose complex expectations, use the Expectation.to method:

`typescript
import { actorCalled } from '@serenity-js/core'
import { Expectation, 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)),
)
``

Documentation

- API Reference
- Screenplay Pattern Guide
- Serenity/JS Project Templates
- Tutorial: First Web Scenario
- Tutorial: First API Scenario

Contributing

Contributions of all kinds are welcome! Get started with the Contributing Guide.

Community

- Community Chat
- Discussions Forum
- Visit the 💡How to... ? section for answers to common questions

If you enjoy using Serenity/JS, make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

License

The Serenity/JS code base is licensed under the Apache-2.0 license,
while its documentation and the Serenity/JS Handbook are licensed under the Creative Commons BY-NC-SA 4.0 International.

See the Serenity/JS License.

Support

Support ongoing development through GitHub Sponsors. Sponsors gain access to Serenity/JS Playbooks
and priority help in the Discussions Forum.

For corporate sponsorship or commercial support, please contact Jan Molak.