Serenity BDD Reporter
Serenity reports are a powerful feature enabled by Serenity BDD. They aim not only to report test results, but also to document how features are tested, and what your application does.
@serenity-js/serenity-bdd
module enables integration between Serenity/JS and the Serenity BDD reporting CLI.
You will learn:
- How to install Serenity BDD
- How to configure Serenity BDD reporter
- How to produce Serenity BDD reports
Examples and Project Templates
If you'd like to dive straight into the code, Serenity/JS GitHub repository provides:
- Serenity/JS project templates, which are the easiest way to start with the framework
- Examples and reference implementations, each set up to produce a Serenity BDD report
All the Serenity/JS project templates are configured to produce Serenity BDD reports and publish them to their GitHub Pages. Each Serenity/JS project template links to its respective Serenity BDD report from its readme file.
For example, here's where Serenity/JS + Cucumber + Playwright project template publishes its Serenity BDD reports.
Installation and usage
Serenity BDD reports are generated by Serenity BDD CLI,
a Java program downloaded and managed by the @serenity-js/serenity-bdd
module.
SerenityBDDReporter
is also available as part of the @serenity-js/serenity-bdd
module.
It listens to domain events emitted by actors, test runner adapters, and other stage crew members,
to produce Serenity BDD-compatible JSON reports, which can be then stored as files to disk by ArtifactArchiver
.
Resulting JSON files can be processed by Serenity BDD CLI to produce a HTML report and rich living documentation containing screenshots, details of HTTP traffic for any REST API interactions, details of any activities performed by Serenity/JS actors and more.
Installation
To install the @serenity-js/serenity-bdd
module, run the following command in your computer terminal:
npm install --save-dev @serenity-js/{core,serenity-bdd}
To learn more about the installation process, follow the API documentation.
Configuration
To use the Serenity BDD Reporter, you need to register it together with the Artifact Archiver so that the reports are stored to disk:
import { configure } from '@serenity-js/core'
configure({
crew: [
'@serenity-js/serenity-bdd',
[ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
]
})
To learn how to configure Serenity BDD Reporter with your test runner, follow the API documentation.
Reporting
To produce Serenity BDD reports, your test suite must:
- download the Serenity BDD CLI, by calling
serenity-bdd update
, which will cache the CLIjar
locally - produce intermediate Serenity BDD
.json
reports, by registeringSerenityBDDReporter
- invoke the Serenity BDD CLI when you want to produce the report, by calling
serenity-bdd run
The pattern used by all the Serenity/JS Project Templates relies on using:
- a
postinstall
NPM script to download the Serenity BDD CLI npm-failsafe
to run the reporting process even if the test suite itself has failed (which is precisely when you need test reports the most...).rimraf
as a convenience method to remove any test reports left over from the previous run
{
"scripts": {
"postinstall": "serenity-bdd update",
"clean": "rimraf target",
"test": "failsafe clean test:execute test:report",
"test:execute": "cucumber-js",
"test:report": "serenity-bdd run --features ./features ",
}
}
Note that in the above code sample, you should configure test:execute
to invoke your test runner of choice.
To learn more about the SerenityBDDReporter
, please consult:
- installation instructions in
@serenity-js/serenity-bdd
documentation, - configuration examples in
SerenityBDDReporter
.
You might also want to explore Serenity/JS example projects on GitHub.
Integration
SerenityBDDReporter
emits ArtifactGenerated
containing Serenity BDD-standard JSON reports,
which can be stored to disk by ArtifactArchiver
,
and then turned into Serenity BDD HTML reports by Serenity BDD Reporting CLI.