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

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

See the Serenity/JS Installation Guide.

Quick Start

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

Performing assertion

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

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

Controlling execution flow

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

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

Synchronising execution with the System Under Test

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

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

Defining custom expectations

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

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

Composing expectations

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

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.