Open-Source Testing · serenity-js

serenity-js

Serenity/JS is a TypeScript-based acceptance testing framework that layers on top of Playwright, WebdriverIO, or Cucumber to provide reusable test patterns, structured reporting, and multi-actor test support. It lets teams write tests that read like specifications and scale without duplicating selectors or logic.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/serenity-js/serenity-js

612

GitHub stars

154

Forks

TypeScript

Primary language

Apache-2.0

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	serenity-js/serenity-js
Owner	serenity-js
Primary language	TypeScript
License	Apache-2.0 — OSI-approved
Stars	612
Forks	154
Open issues	87
Latest release	v3.44.1 (2026-07-06)
Last updated	2026-07-08
Source	https://github.com/serenity-js/serenity-js

What serenity-js is

Serenity/JS implements the Screenplay Pattern to decompose acceptance tests into composable Tasks that decouple intent from implementation. It integrates as a reporter/plugin with existing test runners (Playwright Test, WebdriverIO, Cucumber, Mocha, Jasmine), supports blended API/UI testing, and generates structured JSON artifacts for downstream reporting (Serenity BDD HTML, console).

Quickstart

Get the serenity-js source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/serenity-js/serenity-js.git2cd serenity-js3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Large, growing acceptance test suites with duplicated logic

Teams with hundreds of Playwright or WebdriverIO tests can adopt the Screenplay Pattern incrementally to eliminate selector duplication, reuse Tasks across scenarios, and maintain readability as suites grow.

Multi-actor workflows and collaboration scenarios

Built-in multi-actor support simplifies tests where multiple users interact concurrently (e.g., order placement + admin verification). Avoids manual actor/context juggling in plain Playwright/WebdriverIO.

Living documentation and stakeholder-facing test reports

Serenity BDD reports generate human-readable HTML living documentation linking tests to business requirements, suitable for sharing with POs and non-technical stakeholders.

Implementation considerations

Requires updating test runner config files (e.g., playwright.config.ts) and switching imports from @playwright/test to @serenity-js/playwright-test; gradual adoption is supported but full benefit requires refactoring existing tests into Tasks.
Screenplay Pattern learning curve varies by team experience with design patterns and DDD; plan for onboarding and coding standards documentation to ensure consistent Task design across teams.
Module ecosystem (@serenity-js/core, @serenity-js/web, @serenity-js/rest, etc.) must be installed and version-aligned; verify compatibility matrix on serenity-js.org/releases for your Node, Playwright, and WebdriverIO versions.
Structured reporting pipeline (test execution → JSON artifacts → Serenity BDD HTML generation via CLI) requires npm scripts and build configuration; plan artifact storage and pipeline integration.
Multi-actor test scenarios require explicit actor fixture setup and Task composition; unsuitable for simple single-user tests without careful scope management to avoid over-engineering.

When to avoid it — and what to weigh

Minimal, lightweight test suites (< 20 tests) — Serenity/JS adds architectural overhead (module structure, Task composition). For tiny projects, plain Playwright Test or WebdriverIO may be faster to set up and maintain.
Need to avoid TypeScript or JavaScript — Serenity/JS is TypeScript-native with JavaScript support. Teams committed to Python, Java, or other languages should use Selenium/Cucumber implementations in those ecosystems.
Strict dependency minimalism or air-gapped deployment — Serenity/JS depends on a large package tree (@serenity-js/core, reporters, integrations). Verify npm package availability and bundle size constraints in your environment.
Real-time test execution dashboards or CI/CD deep integration — Serenity/JS focuses on post-execution reporting artifacts (JSON, HTML). If your CI demands live test streaming or tight execution hooks, evaluate custom reporter integration effort upfront.

License & commercial use

Apache License 2.0 (Apache-2.0). Permissive OSI-approved license allowing commercial use, modification, and distribution with standard Apache obligations (license notice, CHANGES file). No restrictions on proprietary products.

Apache-2.0 explicitly permits commercial use and proprietary derivatives. No license review required for commercial integration. Verify you retain and distribute the Apache license notice in your product. No dual-licensing or paid tiers mentioned in provided data.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Strong
Assessment confidence	High

Security considerations

No security posture details provided in source data. As a TypeScript test framework, standard considerations apply: validate credentials are not hardcoded (use env vars, secrets managers—README explicitly warns against this); audit npm dependencies for vulnerabilities (large package tree); run tests in isolated CI environments to prevent secrets leakage in reports or artifacts. Serenity BDD reports may contain PII (screenshots, form values)—secure artifact storage accordingly.

Alternatives to consider

Plain Playwright Test or WebdriverIO (no framework layer)

Lower overhead for small suites; direct test runner config without Screenplay abstraction. Suitable if test reusability and stakeholder reporting are not priorities.

Cypress with custom Page Object or Cucumber patterns

Lighter-weight alternative for UI-only testing with strong debugging experience, though lacks multi-actor support and structured reporting comparable to Serenity BDD.

Robot Framework (Python-based)

Alternative for teams preferring Python, offering keyword-driven syntax and built-in reporting; not TypeScript-native and requires separate ecosystem (Selenium, AppiumLibrary).

Software development agency

Build on serenity-js with DEV.co software developers

Serenity/JS layers onto your existing Playwright or WebdriverIO tests to reduce duplication and enable stakeholder-facing living documentation. Start with the quick-start guide on serenity-js.org—no rewrite required.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

testplane dom-testing-library CodeceptJS

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing AI Application Development Web App Development API Development Talk to DEV.co

serenity-js FAQ

Do I have to rewrite all my existing Playwright tests to use Serenity/JS?

No. Serenity/JS works on top of existing tests. You can adopt it incrementally—run existing tests under the Serenity reporter and gradually refactor into Tasks as you update code. The README Quick Start shows immediate structured reporting without Screenplay changes.

Can I use Serenity/JS with my current test runner (Playwright, WebdriverIO, etc.)?

Yes. Serenity/JS integrates as a reporter and fixture layer. Supported runners: Playwright Test, WebdriverIO, Cucumber, Mocha, Jasmine. You keep your existing runner; Serenity/JS adds structure and reporting on top.

What is the Screenplay Pattern and do I need to learn it?

Screenplay Pattern is a design approach that separates test intent (what) from implementation (how) via reusable Tasks. It reduces duplication and improves maintainability. Learning curve exists but is gradual; Serenity/JS supports adoption at three levels (no pattern, basic Tasks, full pattern).

How does Serenity BDD reporting work? Do I need separate infrastructure?

Serenity/JS generates JSON artifacts during test execution. The serenity-bdd CLI tool post-processes them into HTML living documentation. No separate infrastructure needed—run the CLI in your CI pipeline after tests complete. Reports are static HTML files you can host or archive.

Software developers & web developers for hire

Need help beyond evaluating serenity-js? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source testing integrations — and maintain them long-term.

Ready to scale your test suite?

Talk to DEV.co Schedule a Consultation