About serenity-js

A TypeScript-native acceptance testing framework that gives your Playwright Test, WebdriverIO, or Cucumber test suite the architecture it needs to scale.

s

Published by

serenity-js

Visit View Profile

README.md

View on GitHub

Serenity/JS

A TypeScript-native test automation framework that gives your Playwright Test, WebdriverIO, or Cucumber test suite the architecture it needs to scale.

Website · Getting Started · Handbook · API Docs · Community

What a Serenity/JS test looks like

import { describe, it } from '@serenity-js/playwright-test'
import { Ensure, equals } from '@serenity-js/assertions'
import { Navigate } from '@serenity-js/web'

describe('Swag Labs', () => {

    it('should let a standard user complete checkout', async ({ actor }) => {
        await actor.attemptsTo(
            Navigate.to('https://www.saucedemo.com/'),
            Authenticate.withCredentials('standard_user', 'secret_sauce'),
            Inventory.productCalled('Sauce Labs Backpack').addToCart(),
            Checkout.completeWith({
                firstName: 'Alice',
                lastName: 'Smith',
                postalCode: '90210',
            }),
            Ensure.that(
                Checkout.confirmationHeading(), 
                equals('Thank you for your order!')
            ),
        )
    })
})

Tests read like specifications. Each Task (Authenticate, Inventory, Checkout) is reusable across scenarios, test runners, and integration tools. See the full implementation →

Note: The username and password above are public demo values from saucedemo.com. In real projects, use environment variables or a secrets manager.

Why Serenity/JS?

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

→ See the same scenario at three levels of Serenity/JS adoption

Works with

Serenity/JS works on top of your existing tools — you don't replace anything, you add structure and reporting. Supported test runners and integration tools include:

Quick Start

Add Serenity/JS to an existing Playwright Test project:

1. Install Serenity/JS modules and reporting tools:

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 @serenity-js/assertions rimraf npm-failsafe

2. Update playwright.config.ts to register the Serenity/JS reporter:

  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' } ],
+           ]
+       }]
+   ],

3. Add scripts to package.json to generate Serenity BDD reports and living documentation:

 {
   "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'"
   }
 }

[...] is a npm-failsafe wildcard — it passes any CLI arguments to test:execute. For example, npm test -- --grep "checkout" runs only matching tests while still generating the report.

4. Change one import in your test files to use Serenity/JS fixtures:

// Before
import { test, expect } from '@playwright/test'

// After
import { describe, it } from '@serenity-js/playwright-test'

That's it. Your existing tests gain structured reporting immediately. Adopt the Screenplay Pattern gradually for new tests.

→ Full getting-started tutorial

Learn more

Why Serenity/JS? — architecture comparison at three levels of Serenity/JS adoption
15-minute tutorial — build your first Screenplay test in the browser
Project Templates — pre-configured starters for Playwright, WebdriverIO, Cucumber
API Documentation — reference for all @serenity-js/* modules
Reporting — console, HTML, Serenity BDD living documentation
Releases & Compatibility — latest versions, changelog, and Node/Playwright/WebdriverIO compatibility matrix

Community

GitHub Discussions — Q&A and feature proposals
Community Chat
LinkedIn
YouTube
Blog

If Serenity/JS is helping your team, please ⭐️ star this repo to help others discover it!

Support

GitHub Sponsors — fund ongoing development
Commercial support — training, consulting, and implementation help — contact Jan Molak

Contributing

Serenity/JS is an Apache-2.0 licensed open-source project. We welcome contributions of all kinds — code, documentation, bug reports, and community support.

License

Serenity/JS source code is licensed under Apache-2.0. The Handbook and documentation are licensed under CC BY-NC-SA 4.0.