Serenity/JS is a modular, full-stack acceptance testing framework based on Node.js.
The official Serenity/JS Node modules are distributed via NPM
@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 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.
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:
- Cucumber - Serenity/JS supports all latest major versions of Cucumber.js
- Playwright Test
Serenity/JS Reporting Services
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.
StageCrewMembers observe the actors on
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
ArtifactArchiverand 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
ArtifactArchiverand 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.
- Serenity/JS Web module provides the universal web testing façade - a set of integration 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:
- 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/web, plus a module providing wrappers for your integration library of choice, so
- you'd also want a test runner adapter and a reporting module
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