Skip to main content

Extending Playwright Test with Serenity/JS

Serenity/JS offers excellent support for Playwright, including Playwright Test, UI Mode, trace viewer, and auto-waiting locators! Plus, it accommodates both classic Playwright tests and Serenity/JS Screenplay Pattern scenarios, allowing you to migrate to Screenplay gradually if you'd like.

In this article, and in less than 5 minutes, you'll learn how to:

  • integrate Serenity/JS with your Playwright test suite,
  • enable Serenity BDD reports,
  • start using the Screenplay Pattern,
  • and get started with Playwright Test UI Mode!

Want to jump straight into the code? Check out:

About Serenity/JS​

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

For test suites based on Playwright Test, Serenity/JS offers:

Creating a Playwright Test project​

You can add Serenity/JS to an existing Playwright Test project, or create a new project using the Playwright Test installation wizard:

npm init playwright@latest

Installing Serenity/JS​

To install Serenity/JS from NPM, run the following command:

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

Learn more about Serenity/JS architecture and Serenity/JS modules:

Configuring Serenity/JS​

To enable Serenity/JS reporting services, configure Playwright Test as follows:

playwright.config.ts
import { defineConfig, devices } from '@playwright/test'
import type { SerenityOptions } from '@serenity-js/playwright-test'

export default defineConfig<SerenityOptions>({
    reporter: [
        // Serenity/JS reporting services
        [ '@serenity-js/playwright-test', {
            crew: [
                '@serenity-js/console-reporter',
                '@serenity-js/serenity-bdd',
                [
                    '@serenity-js/core:ArtifactArchiver',
                    { outputDirectory: 'target/site/serenity' }
                ],
            ]
        }],

        // Any other native Playwright Test reporters
        [ 'html', { open: 'never' } ],
    ],

    use: {
        // Serenity/JS configuration options
        crew: [
            // Automatically take screenshots upon an assertion failure
            ['@serenity-js/web:Photographer', { strategy: 'TakePhotosOfFailures' }]
        ],
        defaultActorName: 'Tess',
    },

    // Other Playwright Test configuration options
});

Learn more about:

Producing extended Playwright HTML reports​

Serenity/JS automatically augments the built-in Playwright HTML reports to include information about your Screenplay Pattern tasks.

To use this feature, simply start using the Screenplay Pattern APIs in your Playwright Test scenarios and enable the Playwright HTML reporter in your Playwright configuration.

View live Playwright Test report on GitHub 👀

Enhanced reporting with Playwright Test HTML reporter (source)

To learn more about the Screenplay Pattern, check out:

Using Playwright Test UI Mode​

Serenity/JS supports Playwright Test UI Mode, which means that all your Screenplay Pattern tasks are automatically presented in the Playwright Test UI runner.

Using Serenity/JS Screenplay Pattern with Playwright Test UI Mode (source)

To use Playwright Test UI Mode, run the following command in your Playwright Test project:

npx playwright test --ui

To learn more about the Playwright Test UI Mode, check out:

Using Playwright Test Trace Viewer​

Serenity/JS supports Playwright Test Trace Viewer, which means that all your Screenplay Pattern tasks are automatically presented in the Trace Viewer UI.

To use this feature, simply start using the Screenplay Pattern APIs in your Playwright Test scenarios and enable tracing in Playwright Test configuration.

Using Serenity/JS Screenplay Pattern with Playwright Test Trace Viewer (source)

To learn more about the Playwright Test Trace Viewer, check out:

Producing Serenity BDD reports​

Serenity reports and living documentation are a powerful feature enabled by Serenity BDD. They aim not only to report test results, but also to document how features are tested, and what your application does.

Serenity BDD reports are generated by Serenity BDD CLI, a Java program downloaded and managed by the @serenity-js/serenity-bdd module.

View live Serenity BDD report on GitHub 👀

Example Serenity BDD report (source)

To produce Serenity BDD reports, your test suite must:

  • download the Serenity BDD CLI, by calling serenity-bdd update (which caches the CLI jar locally)
  • produce intermediate Serenity BDD .json reports, by registering SerenityBDDReporter as per the configuration instructions
  • invoke the Serenity BDD CLI when you want to produce the report, by calling serenity-bdd run

The pattern used by all the Serenity/JS Project Templates relies on using:

  • a postinstall NPM script to download the Serenity BDD CLI
  • npm-failsafe to run the reporting process even if the test suite itself has failed (which is precisely when you need test reports the most...).
  • rimraf as a convenience method to remove any test reports left over from the previous run
package.json
{
  "scripts": {
    "postinstall": "serenity-bdd update",
    "clean": "rimraf target",
    "test": "failsafe clean test:execute test:report",
    "test:execute": "playwright test",
    "test:report": "serenity-bdd run",
  }
}

To learn more about the SerenityBDDReporter, please consult:

Using Serenity/JS Screenplay Pattern APIs​

The Screenplay Pattern is an innovative, user-centred approach to writing high-quality automated acceptance tests. It steers you towards an effective use of layers of abstraction, helps your test scenarios capture the business vernacular of your domain, and encourages good testing and software engineering habits on your team.

@serenity-js/playwright-test module offers fixtures that integrate Playwright Test with Serenity/JS Screenplay Pattern APIs.

By default, Serenity/JS configures a default cast of actors, where every actor can:

This should be enough to help you get started with introducing test scenarios that follow the Screenplay Pattern even to an existing test suite, for example:

specs/example.spec.ts
// import { test, expect } from '@playwright/test'          // replace this
import { test, expect } from '@serenity-js/playwright-test' // with this

import { Navigate, Page } from '@serenity-js/web'
import { Ensure, matches } from '@serenity-js/assertions'

test.describe('My awesome website', () => {

    test('can have test scenarios that follow the Screenplay Pattern', async ({ actor }) => {
        await actor.attemptsTo(
            Navigate.to(`https://playwright.dev`),
            Ensure.that(
                Page.current().title(),
                matches(/Fast and reliable end-to-end testing for modern web apps.*/)
            ),
        )
    })

    test('can have non-Screenplay scenarios too', async ({ page }) => {
        await page.goto('https://playwright.dev')
        await expect(page)
            .toHaveTitle(/Fast and reliable end-to-end testing for modern web apps.*/);
    })
})

To learn more about the Screenplay Pattern, check out:

Next steps​

Well done, your Playwright Test suite is now integrated with Serenity/JS! 🎉🎉🎉

To take things further, check out:

Remember, 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!

Follow Serenity/JS on LinkedIn Watch Serenity/JS on YouTube Join Serenity/JS Community Chat GitHub stars