Skip to main content

Serenity/JS for Playwright Users

Already using Playwright Test? Good — Serenity/JS is built to work on top of it, not instead of it.

You keep Playwright's speed, auto-waiting, tracing, and parallel execution. Serenity/JS adds the structure and reporting that matter once your test suite outgrows a handful of specs.

Why add Serenity/JS?​

Serenity/JS works on top of Playwright Test — your existing test code, auto-waiting, parallel execution, Trace Viewer, UI Mode, and CI/CD pipeline all stay exactly as they are. You don't need to rewrite anything.

Here's how Serenity/JS helps you address common Playwright Test challenges:

ChallengeHow Serenity/JS helps
Duplicated selectors and test logicThe Screenplay Pattern gives you composable, reusable Tasks that separate what from how
Hard to tell what a test didStructured reports show every action, with timing and screenshots
Multi-user workflows are hard to implementMulti-actor support is built in
Stakeholders can't read test reportsSerenity BDD reports generate living documentation for both technical and business audiences
Logic duplicated across API and UI testsScreenplay Tasks work across interfaces
Slow UI-only test suitesBlended testing — use APIs for setup, UI only where it matters
Locked into one toolScreenplay Tasks are portable — switch integration tools and test runners without rewriting test logic

Get started in 5 minutes​

You don't have to adopt everything at once. The progression most teams go through looks like this:

  1. Add reporting (Steps 1–4) — configure reporters, change one import. Existing tests get better reports immediately.
  2. Use Screenplay for new tests (Step 5) — use the actor model for new scenarios. Old tests stay untouched.
  3. Extract shared Tasks — refactor common workflows into reusable building blocks.
  4. Multi-actor and cross-interface — add multi-user workflows or mixed UI + API interactions.

Step 0: Create a Playwright Test project​

Already have a Playwright Test project?

Skip this step and proceed with the remaining steps from your project directory.

Create a new directory and scaffold a Playwright Test project inside it:

mkdir my-serenity-project
cd my-serenity-project
npm init --yes playwright@latest -- --quiet

This creates a TypeScript Playwright Test project with tests in the tests/ directory, a playwright.config.ts config file, and example tests.

Want to customise the setup?

Drop the --quiet flag to get interactive prompts where you can choose your preferred language, test directory, and browsers:

npm init playwright@latest

Step 1: Install​

Prerequisites

To use Serenity/JS, you'll need a recent Node.js LTS version — Serenity/JS supports Node 20, 22, and 24, as well as Java 11+ for the Serenity BDD reports.

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

→ Learn more: Full installation guide | Why Serenity/JS?

Step 2: Configure​

Update your playwright.config.ts to add the Serenity/JS reporter. You need to make three changes:

  1. Add the SerenityFixtures and SerenityWorkerFixtures import
  2. Add type parameters to defineConfig
  3. Replace the reporter option with the Serenity/JS reporter configuration
Reading the diffs

Lines marked with + should be added to your file; lines marked with - should be removed. Don't copy the +/- prefixes themselves.

playwright.config.ts
- import { defineConfig, devices } from '@playwright/test';
+ import { defineConfig, devices } from '@playwright/test';
+ import { SerenityFixtures, SerenityWorkerFixtures } from '@serenity-js/playwright-test';

- export default defineConfig({
+ export default defineConfig<SerenityFixtures, SerenityWorkerFixtures>({
    testDir: './tests',
    // ... keep your existing settings ...
-   reporter: 'html',
+   reporter: [
+       [ 'line' ],
+       [ '@serenity-js/playwright-test', {
+           crew: [
+               '@serenity-js/console-reporter',
+               [ '@serenity-js/serenity-bdd', {
+                   specDirectory: './tests'
+               } ],
+               [ '@serenity-js/core:ArtifactArchiver', {
+                   outputDirectory: './reports/serenity'
+               } ],
+           ]
+       }]
+   ],

Next, add the following scripts to your package.json:

package.json
 {
   "scripts": {
+    "clean": "rimraf target",
+    "test": "failsafe clean test:execute [...] test:report",
+    "test:execute": "npx playwright test",
+    "test:report": "serenity-bdd run --features='./tests' --source='./reports/serenity' --destination='./reports/serenity'"
   }
 }

→ Learn more: Configuration options | Serenity BDD reporter setup | Using npm-failsafe

Step 3: Change one import​

In your test files:

- import { test, expect } from '@playwright/test';
+ import { test, expect } from '@serenity-js/playwright-test';

→ Learn more: Writing tests with Serenity/JS | Multi-actor scenarios

Step 4: Run​

npm test

That's it. Your existing tests run as before, but now produce a rich HTML report in reports/serenity/. Open reports/serenity/index.html in your browser to view it.

Running a single test

The [...] wildcard in the test script is provided by npm-failsafe and passes any arguments you provide directly to Playwright Test. For example, to run a single spec file:

npm test -- --spec=tests/website.spec.ts

Or to run tests matching a specific name:

npm test -- --grep="descriptive title"

→ Learn more: Reporting overview | Serenity BDD reports

Example Serenity BDD report generated by Serenity/JS (source)

Step 5 (optional): Write your first Screenplay test​

Steps 1–4 give you better reporting with zero changes to your test logic. When you're ready to see what the Screenplay Pattern looks like in practice, add a new test file:

tests/website.spec.ts
import { describe, it } from '@serenity-js/playwright-test';
import { Ensure, includes } from '@serenity-js/assertions';
import { Navigate, Page } from '@serenity-js/web';

describe('Website', () => {

    it('should have a descriptive title', async ({ actor }) => {
        await actor.attemptsTo(
            Navigate.to('https://serenity-js.org/'),
            Ensure.that(
                Page.current().title().describedAs('current page title'), 
                includes('Serenity/JS')
            ),
        );
    });
});

Run npm test again. In the Serenity BDD report you'll now see each interaction (Navigate.to, Ensure.that) listed as a separate step with timing — giving you a clear activity breakdown without any extra configuration.

This test does the same thing as the generated example.spec.ts, but uses the actor fixture and Screenplay interactions instead of page directly. The key differences:

  • actor replaces page as the entry point — the actor has a page, but can also interact with REST APIs, multiple browser contexts, etc.
  • Navigate.to() and Ensure.that() are composable interactions that show up as named steps in your reports.
  • describe and it come from @serenity-js/playwright-test — they work like Playwright's test() but give you richer reporting structure.

→ Learn more: Screenplay Pattern | Your first web scenario

For a more advanced example showing composable Tasks, the Lean Page Objects pattern, and masked credentials, see the Complete example below.

Want more detail?

See the full installation guide for advanced options, or the architecture overview to understand how the pieces fit together.

Reference projects​

Complete example​

A self-contained project you can copy in full. It includes:

  • tests/website.spec.ts — a simple Screenplay test using Navigate and Ensure (same pattern as Step 5)
  • tests/swag-labs.spec.ts — a more advanced test interacting with the Swag Labs demo website, using composable Task definitions and the Lean Page Objects pattern

Run npm install then npm test — the Serenity BDD HTML report lands in reports/serenity/index.html.

Credentials in examples

The password secret_sauce is hard-coded in these examples to keep them simple and self-contained. In real-world tests, load credentials from environment variables or a password vault to avoid committing secrets to your repository.

package.json
{
  "name": "my-serenity-js-project",
  "version": "1.0.0",
  "scripts": {
    "clean": "rimraf target",
    "test": "failsafe clean test:execute [...] test:report",
    "test:execute": "npx playwright test",
    "test:report": "serenity-bdd run --features='./tests' --source='./reports/serenity' --destination='./reports/serenity'"
  },
  "devDependencies": {
    "@serenity-js/assertions": "^3.43.2",
    "@serenity-js/console-reporter": "^3.43.2",
    "@serenity-js/core": "^3.43.2",
    "@serenity-js/playwright": "^3.43.2",
    "@serenity-js/playwright-test": "^3.43.2",
    "@serenity-js/serenity-bdd": "^3.43.2",
    "@serenity-js/web": "^3.43.2",
    "@playwright/test": "~1.60.0",
    "npm-failsafe": "^1.4.0",
    "rimraf": "^6.0.0",
    "typescript": "^5.7.0"
  }
}

Project templates​

If you'd rather start from a fully configured project than add Serenity/JS to an existing one, use one of these GitHub template repositories. Each comes with CI configuration, example tests, and live reports you can preview.

End-to-end testing:

StackLive Report
Playwright TestSerenity BDD · Playwright
Cucumber + PlaywrightSerenity BDD

Component testing:

StackLive Report
Playwright CT + ReactSerenity BDD · Playwright
Playwright CT + Lit/Web ComponentsSerenity BDD · Playwright

→ All project templates

FAQ​

Does it slow down my tests?​

No. Serenity/JS adds negligible overhead. Tests still run on Playwright's engine with the same parallelism and auto-waiting.

Do I have to rewrite all my tests?​

No. You can mix Screenplay and non-Screenplay tests in the same project. Start with reporting-only and introduce Screenplay gradually.

Does it work with UI Mode?​

Yes. Serenity/JS integrates with Playwright UI Mode and augments the Trace Viewer with Screenplay activity information.

What about built-in fixtures?​

Serenity/JS extends Playwright Test fixtures — it doesn't replace them. You still have page, context, browser, and all your custom fixtures. Serenity/JS adds actor, actorCalled, and other Screenplay fixtures.

Do I need Java?​

Yes, for the Serenity BDD HTML reports (Java 11+). If you'd rather stay Java-free, use the console reporter alone or Playwright's built-in HTML report.

Something not working?

Check the Troubleshooting guide for solutions to common issues with reports, screenshots, and configuration.

Next steps​

Using WebdriverIO instead?

Serenity/JS works just as well with WebdriverIO. The Task code is identical — only the config differs. See Serenity/JS with WebdriverIO.