@serenity-js/assertions

Serenity/JS

Serenity/JS is a framework designed to make acceptance and regression testing of modern full-stack applications faster, more collaborative and easier to scale.

Visit serenity-js.org for the latest tutorials and API docs, and follow @SerenityJS and @JanMolak on Twitter for project updates.

Learning Serenity/JS

To learn more about Serenity/JS, check out the video below, read the tutorial, review the examples, and create your own test suite with Serenity/JS template projects.

If you have any questions, join us on Serenity/JS Community Chat.

Serenity/JS Assertions

@serenity-js/assertions is an assertions library implementing the Screenplay Pattern.

Installation

To install this module, run the following command in your computer terminal:

npm install --save-dev @serenity-js/{core,assertions}

Performing verifications using Ensure

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 using Check

import { actorCalled } from '@serenity-js/core';
import { Check } from '@serenity-js/assertions'; 
import { Click, isVisible } from '@serenity-js/protractor';

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

Synchronising the test with the System Under Test using Wait

import { actorCalled } from '@serenity-js/core';
import { Click, isVisible, Wait } from '@serenity-js/protractor';

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

Defining custom expectations using Expectation.thatActualShould

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 using Expectation.to

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

Changelog

3.0.0-rc.41 (2023-02-07)

Bug Fixes

• assertions: custom errors thrown via Ensure now include activity location (1fdf7a2), closes #1102
• assertions: interaction to Ensure no longer emits an AssertionReport artifact (db3e5ae), closes #1486
• core: corrected issue in asyncMap that led lists of lists to be flat-mapped not mapped (d7a6f1d)
• core: easier configuration and automatic colour support detection for AnsiDiffFormatter (637ed44), closes #1486
• core: further improvements to how the expected vs received values are rendered in VS Code (e2101d0), closes #1486
• core: improved support for Node 14 (f828b45)
• core: introduced ExpectationDetails to provide more accurate info re failed expectations (02b8f33), closes #1102
• core: removed AssertionReport and AssertionReportDiffer as they're no longer needed (a968ac5), closes #1480
• core: removed the legacy Error (de-)serialisation mechanism (7ea2b10)
• core: typeOf now correctly recognises Proxy objects (3ca68a3)
• core: updated npm-failsafe to 1.0.0 (df80731), closes #1486
• playwright: upgraded Playwright to 1.30.0 (305a2c2)
• web: renamed internal function inspector to inspected (4d2b147)

Features

• assertions: diffs included in RuntimeErrors are now colour-coded (f88efb4), closes #1486
• core: assertion and synchronisation errors include location of the activity that threw them (f06f378), closes #1102
• core: assertion errors include precise information about unmet expectations and improved diffs (1eb09b1), closes #1102
• core: better assertion errors reporting in Visual Studio Code (3b94b7d), closes #1486
• core: error factory is now configurable, which allows for the diffs to include colours (dac293d), closes #1486
• core: new ability to RaiseErrors (4617d39), closes #1102
• core: overridable abilities (03966cc)
• protractor: improved assertion error reporting for Protractor (8f8f91c), closes #1102
• webdriverio: improved assertion error reporting for WebdriverIO (7513752), closes #1102