@serenity-js/playwright

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.

Subscribe to Serenity/JS YouTube channel to get notified when new demos and video tutorials are available.

Learning Serenity/JS

To learn more about Serenity/JS, follow 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 Playwright

@serenity-js/playwright module is a Screenplay Pattern-style adapter for Playwright, that helps with testing Web-based apps.

Installation

To install this module, run the following command in your Playwright project directory:

npm install --save-dev @serenity-js/{assertions,console-reporter,core,serenity-bdd,web,playwright}

Usage with Mocha

import { Ensure, equals } from '@serenity-js/assertions';
import { actorCalled, Actor, ArtifactArchiver, Cast, configure, Duration } from '@serenity-js/core';
import { ConsoleReporter } from '@serenity-js/console-reporter';
import { BrowseTheWebWithPlaywright, PlaywrightOptions } from '@serenity-js/playwright';
import { SerenityBDDReporter } from '@serenity-js/serenity-bdd';
import { By, Navigate, PageElement, Photographer, TakePhotosOfFailures, Text } from '@serenity-js/web';

import { describe, it, beforeAll, afterAll } from 'mocha';
import * as playwright from 'playwright';

// example Lean Page Object describing a widget we interact with in the test
class SerenityJSWebsite {                   
    static header = () => 
        PageElement.located(By.css('h1'))   // selector to identify the interactable element
            .describedAs('header');         // description to be used in reports
}

// example Actors class, confgures Serenity/JS actors to use Playwright
class Actors implements Cast {              
    constructor(                            
        private readonly browser: playwright.Browser,
        private readonly options: PlaywrightOptions,
    ) {
    }

    prepare(actor: Actor): Actor {
        return actor.whoCan(
            BrowseTheWebWithPlaywright.using(this.browser, this.options),
            // ... add other abilities as needed, like CallAnApi or TakeNotes
        );
    }
}

describe('Serenity/JS', () => {

    let browser: playwright.Browser;
    
    beforeAll(async () => {
        // Start a single browser before all the tests,
        // Serenity/JS will open new tabs
        // and manage Playwright browser context as needed  
        browser = await playwright.chromium.launch({
            headless: true
        });

        // Configure Serenity/JS providing your Actors
        // and required "stage crew memebers" (a.k.a. reporting services)
        configure({
            actors: new Actors(browser, {
                    baseURL: `https://serenity-js.org`,
                    defaultNavigationTimeout:   Duration.ofSeconds(2).inMilliseconds(),
                    defaultTimeout:             Duration.ofMilliseconds(750).inMilliseconds(),
            }),
            crew: [
                ArtifactArchiver.storingArtifactsAt(`./target/site/serenity`),
                Photographer.whoWill(TakePhotosOfFailures),
                new SerenityBDDReporter(),
                ConsoleReporter.forDarkTerminals(),
            ]
        });
    });
    
    it('supports Playwright', async () => {
        // actorCalled(name) instantiates or retrieves an existing actor identified by name
        // Actors class configures the actors to use Playwright 
        await actorCalled('William')                                
            .attemptsTo(
                Navigate.to('https://serenity-js.org'),
                Ensure.that(
                    Text.of(SerenityJSWebsite.header()),
                    equals('Next generation acceptance testing')
                ),
            )
    })

    afterAll(async () => {
        // Close the browser after all the tests are finished
        if (browser) {
            await browser.close()
        }
    });
});

Next steps:

• Add @serenity-js/mocha adapter to produce the reports
• Learn about the Screenplay Pattern
• Explore @serenity-js/web and @serenity-js/assertions APIs

Usage with @playwright/test

See @serenity-js/playwright-test.

Usage with Cucumber

Tutorial coming soon!

Follow @SerenityJS on Twitter to get notified about new tutorials.

More coming soon!

New features, tutorials, and demos are coming soon, so follow us on Twitter and join the Serenity/JS Community chat channel to stay up to date!

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