Serenity/JS Handbook

Serenity/JS is an open-source test automation framework that transforms acceptance testing into a collaborative, intuitive, and enjoyable experience for everyone on your team! By leveraging the Screenplay Pattern, Serenity/JS unifies developers, testers, and business stakeholders and helps your team create high-quality, reliable test scenarios that align with real-world workflows and deliver meaningful insights.

This Serenity/JS Handbook offers plenty of practical examples, exercises, and reference implementations to help you get started with Serenity/JS and succeed with modern test automation.

Why choose Serenity/JS

Serenity/JS revolutionises how teams approach test automation:

• For Developers: Modular APIs and vendor-agnostic design allow you to write clean, reusable code that integrates seamlessly with your existing Node.js toolchain.
• For Testers: Simulate authentic multi-actor workflows spanning web UIs, REST APIs, mobile apps, and more.
• For Business Stakeholders: Benefit from clear, actionable reports and living documentation that connect technical outcomes to meaningful business insights.

Improved collaboration

• Speak the same language: The Serenity/JS Screenplay Pattern fosters alignment between developers, testers, and business stakeholders by helping you develop a test language that captures your domain vocabulary and workflows. No matter your role, you'll find it easy to stay aligned and contribute meaningfully to the testing process.

• Focus on actors: Serenity/JS test scenarios are written from the perspective of actors interacting with your system, ensuring clarity and relevance to real-world workflows.

Reusable and modular design

• Write once, reuse anywhere: Serenity/JS APIs encourage your team to craft modular, reusable code modelled after the various activities performed by your actors. Combine activities into reusable tasks and easily represent even the most complex multi-actor and multi-interface scenarios.

• Scale effortlessly: Serenity/JS's actor-centric design minimises redundancy and helps you keep your tests maintainable. It also enables you to build reusable automation libraries that can be shared across projects and teams to create a cohesive testing ecosystem across your organisation and scale your automation as your systems evolve.

• Encourage portability: The Serenity/JS Web module provides a portable abstraction layer over popular automation tools like Selenium, Playwright, and WebdriverIO. This abstraction makes your test code vendor-agnostic, enabling you to switch or mix underlying tools without rewriting your tests. For example:

  • You could reuse the test code between your UI component tests using the Playwright Component Test runner and your end-to-end (E2E) test scenarios running with WebdriverIO against a remote Selenium WebDriver grid.
  • Similarly, you could quickly adapt tests developed with one integration tool to use another. This portability not only future-proofs your test automation but also allows you to leverage the strengths of different tools depending on the context - whether it's local development, CI pipelines, or cross-browser testing.

Realistic multi-actor scenarios

• Test across interfaces: Test across web UIs, REST APIs, mobile apps, and more - all within a single framework and using the same consistent design patterns.

• Achieve true end-to-end coverage: Simulate realistic multi-actor user journeys across all touchpoints, ensuring comprehensive feature coverage.

Continuous automation

• CI/CD-ready: Serenity/JS supports Continuous Integration, Continuous Testing, and Continuous Delivery paradigms, ensuring your automated tests are as easy to run on your machine as they are as part of your test automation pipelines.

• Efficient execution: Execute tests in parallel or sharded, locally or remotely, and integrate with your favourite CI/CD tools to support your team and ensure your system is always release-ready.

Insightful reporting

• Generate world-class test reports and living documentation that connect test outcomes to business requirements.

• Provide stakeholders with clear, actionable insights into your system's performance, stability, and release readiness.

Get started fast 🚀

Kickstart your journey with Serenity/JS today and experience the power of collaborative, scalable test automation. Here's how:

1. Explore the official tutorials: Dive into step-by-step tutorials to learn the fundamentals of Serenity/JS and see practical examples in action without having to install anything on your machine!
2. Start with a Serenity/JS Project Template: Save time and accelerate your progress with pre-built templates tailored to common automation scenarios.
3. Follow the installation guide: Learn to install Serenity/JS and related test automation tools.
4. Understand the architecture: Discover how the modular architecture of Serenity/JS supports your software quality goals.
5. ⭐ Star Serenity/JS on GitHub and tell your colleagues about the framework!

Get started fast

Get a feel for Serenity/JS with our 15-minute web testing tutorial 🚀

Modernise existing projects

Serenity/JS is designed to help you safely and progressively modernise existing codebases:

• Serenity/JS with Playwright Test: Learn how to integrate Serenity/JS reporting services and Screenplay Pattern APIs with your Playwright Test project.
• Serenity/JS with WebdriverIO: Learn how Serenity/JS can help you improve your WebdriverIO 8 and WebdriverIO 9 projects.
• Migrating from Protractor: Migrate from Protractor to WebdriverIO or Playwright Test using the Serenity/JS web module.
• Upgrading from Serenity/JS 2: Upgrade from Serenity/JS 2 to Serenity/JS 3 with our comprehensive guide.

Join the Serenity/JS Community!

Serenity/JS is more than just a framework - it's an active community of testers, developers, and quality advocates who share your passion for excellence. Want to get involved? Here’s how:

• Serenity/JS GitHub: Dive into the source code, contribute to the project, and collaborate with other developers.
• Community Chat: Connect with professionals who share your interests, exchange ideas, and learn from each other.
• Q&A Forum: Ask questions, find answers, and help others navigate Serenity/JS.
• Stay up to date: Follow @serenity-js on LinkedIn and YouTube for the latest tutorials and updates.

Meet the author

Jan Molak is a software development consultant and trainer with over 19 years of experience helping teams turn ideas into high-quality software. From award-winning video games to high-traffic web apps, complex event processing, and financial systems, Jan has worked across multiple industries to boost efficiency, reduce risks, and accelerate delivery - leading to better business results and happier customers.

As the creator of Serenity/JS, co-author of BDD in Action, Second Edition, and a key contributor to the Screenplay Pattern, Jan specialises in Behaviour-Driven Development (BDD), test automation and continuous delivery. His mission? Helping teams collaborate better, catch issues earlier, and build software that truly meets business needs.

🚀 Want to deliver better software, sooner? Connect with Jan on LinkedIn!