Skip to main content

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 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 you attach to your test runner of choice. The task 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 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:

Attaching a Serenity/JS adapter to a test runner makes it emit Serenity/JS Domain Events compatible with Serenity/JS reporting services (a.k.a. StageCrewMembers) attached to a Stage, via configure.

Serenity/JS Test Runner Adapter integration diagram

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.

Serenity/JS Reporting Services integration diagram

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:

Apart from the integration modules, the framework also offers Serenity/JS Assertions - a dedicated and interface-agnostic assertions library based on the Screenplay Pattern.

Serenity/JS full integration diagram

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:

Getting started with Serenity/JS

With Serenity/JS, you don't need to start from scratch! Serenity/JS GitPods and Serenity/JS Project Templates come with appropriate Serenity/JS modules and lower-level integration and test tools already configured.

Learn more about faster ways of getting started with Serenity/JS.