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!

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.35.2 (2025-10-06)

Bug Fixes

• deps: update dependency typescript to v5.9.3 (fb0bbf6)
• deps: update playwright dependencies to v1.56.0 (053db06)

3.35.1 (2025-09-28)

Bug Fixes

• deps: update playwright dependencies to v1.55.1 (53a98fe)

3.35.0 (2025-09-07)

Features

• web: support for identifying page elements by their ARIA role (cf3672a)

3.34.2 (2025-09-07)

Note: Version bump only for package @serenity-js/playwright

3.34.1 (2025-08-20)

Bug Fixes

• deps: update dependency tiny-types to v1.24.1 (14c705a)
• deps: update playwright dependencies to v1.55.0 (6b501cb)

3.34.0 (2025-08-01)

Bug Fixes

• deps: update dependency typescript to v5.9.2 (8a40483)
• deps: update playwright dependencies to v1.54.2 (b6b9413)

3.33.1 (2025-07-28)

Note: Version bump only for package @serenity-js/playwright

3.32.5 (2025-07-28)

Note: Version bump only for package @serenity-js/playwright

3.32.4 (2025-07-13)

Bug Fixes

• core: removed unnecessary tsconfig files from build artifacts (6e4d4fa)
• deps: update playwright dependencies to v1.54.1 (d7fda0e)

3.32.3 (2025-07-07)

Bug Fixes

• core: use 'node:' prefix for core node module imports (b1775d5)
• deps: update playwright dependencies to v1.53.2 (40ac26d)

3.32.2 (2025-06-21)

Note: Version bump only for package @serenity-js/playwright

3.32.1 (2025-06-20)

Bug Fixes

• playwright-test: added SerenityFixtures and SerenityWorkerFixtures to API docs (887a7cf)

3.32.0 (2025-06-20)

Bug Fixes

• deps: update playwright dependencies to v1.53.1 (6ea14ce)
• playwright: marked all properties of ExtraBrowserContextOptions as optional (3ee0145)

Features

• playwright: refactored SerenityFixtures, corrected BrowseTheWebWithPlaywright parameters (9c62723)

3.31.17 (2025-06-16)

Bug Fixes

• deps: update playwright dependencies to v1.53.0 (3404f12)

3.31.16 (2025-06-05)

Note: Version bump only for package @serenity-js/playwright

3.31.15 (2025-05-06)

Note: Version bump only for package @serenity-js/playwright

3.31.14 (2025-04-28)

Bug Fixes

• deps: update dependency typescript to v5.8.3 (b19c09b)
• deps: update playwright dependencies to v1.52.0 (fc5faed)

3.31.13 (2025-03-20)

Bug Fixes

• deps: update playwright dependencies to v1.51.1 (8d059c2)

3.31.12 (2025-03-12)

Bug Fixes

• deps: update playwright dependencies to v1.51.0 (81dfdd4)

3.31.10 (2025-03-05)

Bug Fixes

• deps: update dependency typescript to v5.8.2 (228c7fd)

3.31.9 (2025-02-20)

Note: Version bump only for package @serenity-js/playwright

3.31.8 (2025-02-04)

Bug Fixes

• deps: update playwright dependencies to v1.50.1 (66f4946)

3.31.7 (2025-01-24)

Bug Fixes

• deps: update playwright dependencies to v1.50.0 (30ca259)

3.31.6 (2025-01-16)

Note: Version bump only for package @serenity-js/playwright

3.31.5 (2025-01-11)

Bug Fixes

• deps: update dependency typescript to v5.7.3 (cd87dd8)

3.31.4 (2025-01-01)

Note: Version bump only for package @serenity-js/playwright

3.31.3 (2025-01-01)

Bug Fixes

• core: migrated to PNPM (43dbe6f), closes #2664

3.31.2 (2024-12-26)

Note: Version bump only for package @serenity-js/playwright

3.31.1 (2024-12-17)

Bug Fixes

• deps: update playwright dependencies to v1.49.1 (7f576dd)
• playwright: support playwright ~1.49.0 (d2e3bae)

3.31.0 (2024-12-12)

Note: Version bump only for package @serenity-js/playwright

3.30.0 (2024-11-19)

Bug Fixes

• deps: update playwright dependencies to v1.49.0 (9d98f8e)

3.29.5 (2024-11-03)

Bug Fixes

• deps: update playwright dependencies to v1.48.2 (e8dc2bd)

3.29.4 (2024-10-08)

Bug Fixes

• deps: update playwright dependencies to v1.48.0 (54e8c32)

3.29.3 (2024-10-08)

Note: Version bump only for package @serenity-js/playwright

3.29.2 (2024-09-25)

Note: Version bump only for package @serenity-js/playwright

3.29.1 (2024-09-24)

Note: Version bump only for package @serenity-js/playwright

3.29.0 (2024-09-24)

Bug Fixes

• deps: update playwright dependencies to v1.47.2 (be26cb2)

3.28.0 (2024-09-11)

Note: Version bump only for package @serenity-js/playwright

3.27.0 (2024-09-06)

Bug Fixes

• core: updated npm tags to improve discoverability (432d331)
• deps: update playwright dependencies to v1.47.0 (0641e49)

Features

• core: added support for Node 22, dropped support for Node 16 (d5dea01), closes #2518

3.26.1 (2024-09-03)

Note: Version bump only for package @serenity-js/playwright

3.26.0 (2024-08-27)

Note: Version bump only for package @serenity-js/playwright

3.25.5 (2024-08-18)

Bug Fixes

• deps: update dependency tiny-types to v1.23.0 (1c9a897)
• deps: update playwright dependencies to v1.46.1 (5cbed5d)

3.25.4 (2024-08-07)

Bug Fixes

• deps: update playwright dependencies to v1.46.0 (000d43a)

3.25.3 (2024-07-25)

Bug Fixes

• deps: update playwright dependencies to v1.45.3 (89775e6)
• playwright: playwright is now a peer dependency (d9c7307)

3.25.2 (2024-07-17)

Bug Fixes

• deps: update playwright dependencies to v1.45.2 (bf1d934)

3.25.1 (2024-07-10)

Bug Fixes

• core: all the API docs now link to the online Serenity/JS API documentation (f8f451d)

3.25.0 (2024-07-03)

Bug Fixes

• deps: update playwright dependencies to v1.45.1 (16cb866)
• web: renamed PageElement.outerHtml to PageElement.html for consistency with other methods (9df6e0f)

Features

• web: outerHtml lets you retrieve the HTML content of the given PageElement (1bb6c6a)

3.24.1 (2024-06-26)

Bug Fixes

• deps: update playwright dependencies to v1.45.0 (ef7eb4a)

3.24.0 (2024-06-18)

Note: Version bump only for package @serenity-js/playwright

3.23.2 (2024-05-24)

Bug Fixes

• deps: update playwright dependencies to v1.44.1 (8a602c9)

3.23.1 (2024-05-20)

Note: Version bump only for package @serenity-js/playwright

3.23.0 (2024-05-12)

Features

• playwright: standardised ExecuteScript argument transmission across WebdriverIO and Playwright (adfc171)
• web: scripts injected into the browser accept data structures containing PageElement objects (2fbddf5)

3.22.4 (2024-05-07)

Bug Fixes

• deps: update playwright dependencies to v1.44.0 (ae659d6)

3.22.3 (2024-05-01)

Bug Fixes

• playwright: ensure ExecuteScript runs in the context of the currently active iframe (3592ca0)

3.22.2 (2024-04-20)

Note: Version bump only for package @serenity-js/playwright

3.22.1 (2024-04-17)

Bug Fixes

• deps: update playwright dependencies to v1.43.1 (fbbb2d4)

3.22.0 (2024-04-11)

Bug Fixes

• deps: update playwright dependencies to v1.43.0 (f9a2f9d)

3.21.2 (2024-03-31)

Note: Version bump only for package @serenity-js/playwright

3.21.1 (2024-03-16)

Bug Fixes

• core: upgraded dependency on tiny-types to 1.22.0 (2c0bb2a)

3.21.0 (2024-03-04)

Note: Version bump only for package @serenity-js/playwright

3.20.0 (2024-03-02)

Bug Fixes

• deps: update playwright dependencies to v1.42.1 (dc20ed5)

3.19.0 (2024-03-01)

Note: Version bump only for package @serenity-js/playwright

3.18.1 (2024-02-23)

Note: Version bump only for package @serenity-js/playwright

3.18.0 (2024-02-17)

Note: Version bump only for package @serenity-js/playwright

3.17.0 (2024-02-10)

Note: Version bump only for package @serenity-js/playwright

3.16.2 (2024-02-05)

Note: Version bump only for package @serenity-js/playwright

3.16.1 (2024-02-03)

Bug Fixes

• core: build with TypeScript 5.2 (2f261ee)
• deps: update playwright dependencies to v1.41.2 (0975517)

3.16.0 (2024-02-01)

Bug Fixes

• deps: update playwright dependencies to v1.41.1 (a1a39ee)

3.15.1 (2024-01-19)

Bug Fixes

• deps: update playwright dependencies to v1.41.0 (bb2dc99)

3.15.0 (2024-01-12)

Note: Version bump only for package @serenity-js/playwright

3.14.2 (2023-12-12)

Bug Fixes

• playwright-test: fixed switching between multiple pages (375f3aa)
• playwright: ignore taking the screenshot if the page is already closed (fdedeb8)

3.14.1 (2023-12-10)

Bug Fixes

• core: added provenance statements (04c2d87)
• core: pinned all the direct dependencies (498b336)

3.14.0 (2023-12-02)

Bug Fixes

• deps: update playwright dependencies to ^1.40.1 (da2e7ba)

Features

• core: nested error cause is now added to the main error message (815c8ce), closes #1823

3.13.3 (2023-11-22)

Bug Fixes

• deps: update playwright dependencies to ^1.40.0 (56c6ec0)

3.13.2 (2023-11-14)

Note: Version bump only for package @serenity-js/playwright

3.13.1 (2023-11-07)

Bug Fixes

• deps: update dependency tiny-types to ^1.21.0 (d4921f9)

3.13.0 (2023-10-19)

Bug Fixes

• deps: update playwright dependencies to ^1.39.0 (32af6b0)

3.12.0 (2023-10-09)

Note: Version bump only for package @serenity-js/playwright

3.11.1 (2023-10-04)

Note: Version bump only for package @serenity-js/playwright

3.11.0 (2023-10-03)

Note: Version bump only for package @serenity-js/playwright

3.10.4 (2023-09-22)

Bug Fixes

• deps: update playwright dependencies to ^1.38.1 (0072ddb)

3.10.3 (2023-09-15)

Bug Fixes

• deps: update playwright dependencies to ^1.38.0 (0b8074b)

3.10.2 (2023-09-10)

Bug Fixes

• core: updated installation instruction in the README (ec3f277), closes #1915

3.10.1 (2023-09-01)

Note: Version bump only for package @serenity-js/playwright

3.10.0 (2023-08-23)

Features

• web: chainable PageElements (#1864) (4d0c7eb)

3.9.1 (2023-08-18)

Bug Fixes

• deps: update playwright dependencies to ^1.37.1 (3a13bba)

3.9.0 (2023-08-04)

Note: Version bump only for package @serenity-js/playwright

3.8.0 (2023-08-01)

Note: Version bump only for package @serenity-js/playwright

3.7.2 (2023-07-26)

Bug Fixes

• deps: update playwright dependencies to ^1.36.2 (f9cc78f)

3.7.1 (2023-07-22)

Note: Version bump only for package @serenity-js/playwright

3.7.0 (2023-07-20)

Bug Fixes

• deps: update playwright dependencies to ^1.36.1 (b86289b)

Features

• playwright: support for parentElement.closestTo(childElement) API (cee2c48), closes #1784

3.6.1 (2023-07-11)

Bug Fixes

• deps: update playwright dependencies to ^1.36.0 (8b60383)

3.6.0 (2023-07-11)

Bug Fixes

• deps: update dependency tiny-types to ^1.20.0 (6d7bf43)

Features

• playwright-test: enable BrowseTheWebWithPlaywright to reuse an existing page instance (5c2deb1), closes #1784
• web: you can now use Serenity/JS Screenplay Pattern APIs for UI component testing (3c9aa4b), closes #1784

3.5.0 (2023-07-02)

Bug Fixes

• core: code clean-up: use type-only TypeScript imports where possible (aa49150)

3.4.2 (2023-06-30)

Note: Version bump only for package @serenity-js/playwright

3.4.1 (2023-06-23)

Bug Fixes

• deps: update playwright dependencies to ^1.35.1 (9124e2e)

3.4.0 (2023-06-10)

Bug Fixes

• deps: update playwright dependencies to ^1.35.0 (fb4359f)

Features

• core: compile Serenity/JS against ES2021 (6b31184)

3.3.1 (2023-06-08)

Note: Version bump only for package @serenity-js/playwright

3.3.0 (2023-06-01)

Bug Fixes

• playwright: support for Playwright 1.34.0 (5d591c7)
• playwright: updated Playwright to 1.34.2 (c944031)
• playwright: upgraded to Playwright 1.34.3 (0ded19e)

Features

• playwright-test: much more detailed Playwright Test reports (5980a1e), closes #1717
• playwright: support Playwright auto-waiting (8f1750f), closes #1717

3.2.1 (2023-05-15)

Note: Version bump only for package @serenity-js/playwright

3.2.0 (2023-05-05)

Bug Fixes

• core: use "types" instead of "typings" in package.json files (0696639), closes #1682
• deps: update playwright dependencies to ^1.33.0 (e1cebc4)

Features

• core: introduced support for Node.js 20, dropped support for Node.js 14 (d0f58a6), closes #1678

3.1.6 (2023-04-18)

Bug Fixes

• webdriverio: upgraded to TypeScript 5 and WebdriverIO 7.31.1 (15b1ba7), closes #1558 #1651

3.1.5 (2023-04-18)

Note: Version bump only for package @serenity-js/playwright

3.1.3 (2023-04-14)

Bug Fixes

• playwright: updated Playwright to 1.32.3 (1d7f77b)

3.1.2 (2023-04-07)

Note: Version bump only for package @serenity-js/playwright

3.1.1 (2023-04-05)

Bug Fixes

• deps: update playwright dependencies to ^1.32.2 (8398ec3)

3.1.0 (2023-04-02)

Note: Version bump only for package @serenity-js/playwright

3.0.1 (2023-03-25)

Bug Fixes

• deps: update playwright dependencies to ^1.32.1 (3ba8d4c)

3.0.0 (2023-03-23)

Note: Version bump only for package @serenity-js/playwright

3.0.0-rc.45 (2023-03-22)

Bug Fixes

• playwright: it's now easier to inspect PlaywrightPage using the new interaction to Debug (cbf210a)

3.0.0-rc.44 (2023-03-19)

Bug Fixes

• core: support for NPM 9 (0493474)
• deps: update dependency tiny-types to ^1.19.1 (ce335eb)

3.0.0-rc.43 (2023-03-10)

Bug Fixes

• deps: update playwright dependencies to ^1.31.2 (ebac2ff)

3.0.0-rc.42 (2023-02-12)

Note: Version bump only for package @serenity-js/playwright

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

Bug Fixes

• playwright: upgraded Playwright to 1.30.0 (305a2c2)

Features

• core: overridable abilities (03966cc)

3.0.0-rc.40 (2023-01-06)

Note: Version bump only for package @serenity-js/playwright

3.0.0-rc.39 (2023-01-05)

Features

• playwright-test: interoperability between Serenity/JS default actor and page (91803de)

3.0.0-rc.38 (2022-12-28)

Bug Fixes

• playwright: introduced an explicit dependency on Playwright (2136132)

3.0.0-rc.37 (2022-12-18)

Features

• playwright: support for Playwright 1.29.0 (3dd0635)

3.0.0-rc.36 (2022-11-28)

Note: Version bump only for package @serenity-js/playwright

3.0.0-rc.35 (2022-11-25)

Bug Fixes

• playwright: upgraded to Playwright 1.28.1 (e9c4c1c)

3.0.0-rc.34 (2022-11-21)

Note: Version bump only for package @serenity-js/playwright

3.0.0-rc.33 (2022-11-07)

Bug Fixes

• playwright: updated Playwright to 1.27.1 (a1fcecc)
• playwright: upgraded Playwright to 1.27.1 (1345644)

3.0.0-rc.32 (2022-10-12)

Note: Version bump only for package @serenity-js/playwright

3.0.0-rc.31 (2022-10-07)

Bug Fixes

• playwright: upgraded Playwright to 1.26.1 (b056613)

3.0.0-rc.30 (2022-10-05)

Bug Fixes

• web: all web modules now correctly support handling iframe context for the current page (bcb8672), closes #1310

3.0.0-rc.29 (2022-10-01)

Note: Version bump only for package @serenity-js/playwright

3.0.0-rc.28 (2022-09-30)

Bug Fixes

• core: activity is now able to detect invocation location on Node 14 (41f4776), closes #1240
• playwright-test: support for Playwright Test Babel loader (f9a5412), closes #1240
• playwright: corrected not(isPresent()) for PlaywrightPageElement (0693b2f), closes #1240
• playwright: upgraded Playwright to 1.25.2 (fcbfdda)
• playwright: upgraded Playwright to 1.26.0 (a13ab3c)

3.0.0-rc.27 (2022-08-26)

Bug Fixes

• playwright: support for Playwright 1.25.1 (e0ab058)

3.0.0-rc.26 (2022-08-15)

Note: Version bump only for package @serenity-js/playwright

3.0.0-rc.25 (2022-08-15)

Bug Fixes

• core: extracted common TypeScript configuration (0108370)
• deps: updated TinyTypes to 1.19.0 (f6d53e4)
• playwright: corrected internal imports from playwright to playwright-core (c42e7f3)
• playwright: updated Playwright (3fa7c7e)
• playwright: updated Playwright to 1.24.2 (9283910)

3.0.0-rc.24 (2022-07-23)

Bug Fixes

• playwright: upgraded Playwright to 1.24.0 (9f8d491)

3.0.0-rc.23 (2022-07-19)

Bug Fixes

• node: support for Node 18 (73212bc), closes #1243

3.0.0-rc.22 (2022-07-15)

3.0.0-rc.21 (2022-07-11)

3.0.0-rc.20 (2022-07-11)

Bug Fixes

• web: renamed PagesContext to BrowsingSession to make the name more descriptive (6b4e998), closes #1236

Features

• core: interactions to Wait.for and Wait.until are now browser-independent (d115142), closes #1035 #1236
• playwright: configurable navigation and interaction timeouts for BrowseTheWebWithPlaywright (142b78e), closes #1236
• playwright: configurable navigation waitUntil timeout (2458fcb), closes #1236
• playwright: initial support for Playwright (87e88a1), closes #493 #563 #911
• playwright: interaction to Select option(s) from a <select /> dropdown (009041d), closes #1236
• playwright: interactions to Scroll, Press, and TakeScreenshot (1c039d2), closes #493 #563 #911
• playwright: isActive check for PlaywrightPageElement (dbf44eb), closes #1236
• playwright: support for executing in-browser JavaScript (630bedd), closes #493 #563 #911
• playwright: support for isClickable (afc8587), closes #1236
• playwright: support for isVisible, plus consistent visibility checks across the board (2c5c929), closes #1236
• playwright: support for working with cookies (1215a8f), closes #1237
• playwright: support for working with frames (89d4621), closes #1236
• web: introduced PagesContext and implemented PlaywrightPage (0045a72), closes #1236
• web: new portable APIs to handle ModalDialog windows (c94d0ec), closes #1236 #805 #1156
• web: standardised support for deep CSS selectors across the Web integration modules (e9e3f28), closes #1238