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 architecture and reporting that help your team understand what the system does and ship with confidence.

→ New to Serenity/JS? Start with Why Serenity/JS to see the full picture.

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/JS HTML Report for all stakeholders — developers, testers, and business audiences — with trend tracking, flaky test detection, and execution evidence
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 22.22.2 and 24.15.0.

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/html-reporter

→ 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/html-reporter', {
+                   specDirectory: './tests'
+               } ],
+           ]
+       }]
+   ],

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

package.json
 {
   "scripts": {
+    "test": "npx playwright test"
   }
 }

→ Learn more: Configuration options | HTML Reporter setup

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 automatically at the end of the test run. Open reports/serenity-js/index.html in your browser to view it.

Running a single test

Pass any arguments directly to Playwright Test. For example, to run a single spec file:

npx playwright test tests/website.spec.ts

Or to run tests matching a specific name:

npx playwright test --grep="descriptive title"

→ Learn more: Reporting overview | HTML Reporter

Example Serenity/JS HTML report (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 HTML 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.

Go further​

Now that you've seen the basics, here are complete projects you can use as reference or as a starting point for your own.

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 HTML report lands in reports/serenity-js/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": {
    "test": "npx playwright test"
  },
  "devDependencies": {
    "@serenity-js/assertions": "^3.45.9",
    "@serenity-js/console-reporter": "^3.45.9",
    "@serenity-js/core": "^3.45.9",
    "@serenity-js/html-reporter": "^3.45.9",
    "@serenity-js/playwright": "^3.45.9",
    "@serenity-js/playwright-test": "^3.45.9",
    "@serenity-js/web": "^3.45.9",
    "@playwright/test": "~1.62.1",
    "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?​

Not if you use the Serenity/JS HTML Reporter — it produces rich reports with trend tracking, flaky test detection, and execution history using pure Node.js. Java is only needed if you choose to use the Serenity BDD Reporter.

Something not working?

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

Next steps​

Community tutorials​

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.