Skip to main content

Serenity/JS Architecture

Serenity/JS is a modular, full-stack acceptance testing framework based on Node.js. The official Serenity/JS Node modules are distributed via NPM under the @serenity-js/* namespace, and you can use as many or as few of them as you need to improve the reporting capabilities of your test suite, integrate with the various interfaces of your system under test, and introduce advanced code reuse patterns in your organisation.

At the high level, Serenity/JS framework is a collection of modules where each module provides at least one of the following:

To build a Serenity/JS-based test automation framework, you pick those Serenity/JS modules that provide the capabilities supporting the type of testing and reporting you want to do. If you wish, you can also extend Serenity/JS and create your own modules that wrap another low-level integration library, or interact with an interface that the framework itself doesn't support yet!

Serenity/JS Test Runner Adapters​

Serenity/JS Test Runner Adapters are tiny reporting libraries that attach to your test runner of choice. The responsibility of an adapter is to listen to the actions performed by the test runner and translate them to Serenity/JS Domain Events, which are then used for test reporting purposes.

First steps with Serenity/JS

Setting up a Serenity/JS test runner adapter and reporting services is the first thing most developers do when introducing Serenity/JS to an existing code base.

Out of the box, Serenity/JS offers test runner adapters for the following test runners:

Serenity/JS Reporting Services​

Just like the core design patterns in your Serenity/JS scenarios revolve around the system metaphor of a stage performance, Serenity/JS reporting services follow the metaphor of a stage crew.

What if I don't follow the Screenplay Pattern yet?

Serenity/JS Reporting Services rely on domain events emitted by actors and Test Runner Adapters. If your test scenarios don't follow the Screenplay Pattern and have no actors yet, don't worry! Serenity/JS reports will present information gathered by the adapter and will start to include information provided by actors whenever you're ready to introduce them.

The StageCrewMembers observe the actors on Stage, watch the Activities they perform, and listen to the domain events emitted by their environment. They use the information they gather to generate artifacts, such as test reports, produce more events to prompt other crew members to action, or perform side effects like printing to the terminal, writing files to disk, or performing network or database calls.

Several of the Serenity/JS modules provide StageCrewMembers you can use for test reporting purposes:

Creating custom reporting services

Studying existing Serenity/JS reporting services will help you create your own StageCrewMembers that produce custom reports or send the results to external reporting or storage systems.

Serenity/JS Screenplay Pattern APIs​

Most Serenity/JS modules offer low-level Screenplay Pattern APIs: Abilities, Questions and Activities, dedicated to helping you integrate your test scenarios with the interfaces of your system under test and create elegant, business-focused test DSLs.

Out of the box, Serenity/JS enables integration with web-, mobile-, and HTTP API-based interfaces and provides wrappers around battle-tested integration libraries to take care of the low-level interactions with your system.

In particular:

What Serenity/JS modules do I need?​

What Serenity/JS modules you need depends on the type of tests you want to write and the lower-level integration libraries you want to use.

For example, if you wanted to create a test suite that exercised a REST API and didn't need to touch the UI, you'd use:

If you wanted to create a test suite that exercised a web interface, you'd need:

Short on time? ⏱️

Serenity/JS Project Templates and Serenity/JS GitPods come with all the appropriate Serenity/JS modules and lower-level integration and test tools already configured, so you can start automating your tests straight away!

Learn more about faster ways to get started using Serenity/JS Project Templates.

Integration architecture summary​

At the high level:

  • Serenity/JS Test Runner Adapter attaches to your test runner and enables test reporting
  • Serenity/JS Screenplay Pattern libraries provide an abstraction that enables your test scenarios to interact with the system under test, while being agnostic of the underlying integration tool
  • Serenity/JS Reporting Services combine the information provided by your test runner and any custom test automation code to produce test execution reports and living documentation in various formats
Serenity/JS integration architecture diagram