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:
- Screenplay Pattern-based integration library for the given interface of your system under test
- Test Runner Adapter that translates your test runner events into Serenity/JS domain events used for reporting
- Reporting Services that translate Serenity/JS domain events into test reports
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.
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 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.
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:
- Console Reporter - writes text-based test reports to your computer terminal,
- Serenity BDD Reporter - emits Serenity BDD-compatible JSON reports, to be archived via
ArtifactArchiver
and consumed by the Serenity BDD CLI to produce HTML reports and living documentation, - Photographer - automatically captures screenshots of the web browser window used by the active actor, to be archived via
ArtifactArchiver
and attached to Serenity BDD reports - Artifact Archiver - stores report artifacts on disk,
- Stream Reporter - logs any events it receives to help you with debugging.
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:
- Serenity/JS Web module provides test library-agnostic Screenplay Pattern APIs dedicated to web UI testing
- Serenity/JS Playwright module provides wrappers around Microsoft Playwright, to be used with the Serenity/JS Web module
- Serenity/JS Protractor module provides wrappers around Angular Protractor, to be used with the Serenity/JS Web module
- Serenity/JS WebdriverIO module provides wrappers around WebdriverIO, to be used with the Serenity/JS Web module
- Serenity/JS REST module provides Screenplay Pattern APIs dedicated to HTTP and REST API testing, as well as wrappers around Axios HTTP client
- Serenity/JS Local Server provides Screenplay Pattern APIs dedicated to interacting with local HTTP servers, as well as wrappers supporting servers built with Express, Hapi, Koa, Restify, and raw Node.js.
Apart from the integration modules, the framework also offers Serenity/JS Assertions - a dedicated and interface-agnostic assertions library based on the Screenplay Pattern.
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:
@serenity-js/core
@serenity-js/assertions
@serenity-js/rest
- plus a test runner adapter and a reporting module
If you wanted to create a test suite that exercised a web interface, you'd need:
@serenity-js/core
@serenity-js/assertions
@serenity-js/web
, plus a module providing wrappers for your integration library of choice, so@serenity-js/playwright
,@serenity-js/protractor
, or@serenity-js/webdriverio
- as well as a test runner adapter and a reporting module
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.