@serenity-js/playwright

Serenity/JS

Serenity/JS is an innovative open-source framework designed to make acceptance and regression testing of complex software systems faster, more collaborative and easier to scale.

⭐️ Get started with Serenity/JS!

• Serenity/JS web testing tutorial
• Serenity/JS + Playwright Test deep dive
• Serenity/JS Handbook
• API documentation
• Serenity/JS Project Templates

👋 Join the Serenity/JS Community!

• Meet other Serenity/JS developers and maintainers on the Serenity/JS Community chat channel,
• Find answers to your Serenity/JS questions on the Serenity/JS Forum,
• Learn how to contribute to Serenity/JS,
• Support the project and gain access to Serenity/JS Playbooks by becoming a Serenity/JS GitHub Sponsor!

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 @serenity-js/console-reporter @serenity-js/core @serenity-js/serenity-bdd @serenity-js/web @serenity-js/playwright

Usage with @playwright/test

Follow the Using Serenity/JS with Playwright Test guide

Usage with Cucumber

Follow the Serenity/JS configuration guide for Cucumber and review the Serenity/JS Cucumber and Playwright Project Template.

Usage with Mocha

import { Ensure, equals } from '@serenity-js/assertions'
import { actorCalled, Actor, Cast, configure, Duration } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright, ExtraBrowserContextOptions } from '@serenity-js/playwright'
import { By, Navigate, PageElement, 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 contextOptions: playwright.BrowserContextOptions,
        private readonly extraContextOptions: ExtraBrowserContextOptions,
    ) {
    }

    prepare(actor: Actor): Actor {
        return actor.whoCan(
            BrowseTheWebWithPlaywright.using(
                this.browser,
                this.contextOptions,
                this.extraContextOptions
            ),
            // ... 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: [
                [ '@serenity-js/console-reporter', { theme: 'auto' } ],
                [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
                [ '@serenity-js/web:Photographer', {
                    strategy: 'TakePhotosOfFailures',
                    // strategy: 'TakePhotosOfInteractions',
                } ],
                [ '@serenity-js/serenity-bdd', { specDirectory: 'spec' } ],
            ]
        })
    })
    
    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

📣 Stay up to date

New features, tutorials, and demos are coming soon! Follow Serenity/JS on LinkedIn, subscribe to Serenity/JS channel on YouTube and join the Serenity/JS Community Chat to stay up to date! Please also make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

💛 Support Serenity/JS

If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!