@serenity-js/serenity-bdd
Serenity/JS is an innovative open-source framework designed to make acceptance and regression testing of complex software systems faster, more collaborative and easier to scale.
⭐️ Get started with Serenity/JS!
- Serenity/JS web testing tutorial
- Serenity/JS Handbook and Getting Started guides
- API documentation
- Serenity/JS Project Templates on GitHub
👋 Join the Serenity/JS Community!
- Meet other Serenity/JS developers and maintainers on the Serenity/JS Community chat channel,
- Find answers to your Serenity/JS questions on the Serenity/JS Forum,
- Learn how to contribute to Serenity/JS,
- Support the project and gain access to Serenity/JS Playbooks by becoming a Serenity/JS GitHub Sponsor!
Serenity BDD
@serenity-js/serenity-bdd
module integrates Serenity/JS and the Serenity BDD reporting CLI.
This integration enables your Serenity/JS tests to produce interim JSON reports, which the Serenity BDD reporting CLI can then turn into world-class, illustrated test reports and living documentation. Learn more about Serenity/JS reporting.
Installation
To install this module, run the following command in your computer terminal:
npm install --save-dev @serenity-js/core @serenity-js/serenity-bdd
To learn more about Serenity/JS and how to use it on your project, follow the Serenity/JS Getting Started guide.
SerenityBDDReporter
To allow Serenity/JS to produce Serenity BDD-standard JSON reports, assign the SerenityBDDReporter
to the Stage
and configure the ArtifactArchiver
to store the reports at the location where Serenity BDD expects to find them.
This can be done:
- via
playwright.config.ts
, if you're using Serenity/JS with Playwright Test - via
wdio.conf.ts
, if you're using Serenity/JS with WebdriverIO - via
protractor.conf.js
, if you're using Serenity/JS with Protractor - or programmatically.
Usage with Playwright Test
Learn more about using Serenity/JS with Playwright Test.
// playwright.config.ts
import type { PlaywrightTestConfig } from '@serenity-js/playwright-test'
const config: PlaywrightTestConfig = {
reporter: [
[ '@serenity-js/playwright-test', {
crew: [
'@serenity-js/serenity-bdd',
[ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
]
}]
],
// Other configuration omitted for brevity
// For details, see https://playwright.dev/docs/test-configuration
}
export default config
Usage with WebdriverIO
Learn more about using Serenity/JS with WebdriverIO.
// wdio.conf.ts
import { WebdriverIOConfig } from '@serenity-js/webdriverio'
export const config: WebdriverIOConfig = {
framework: '@serenity-js/webdriverio',
serenity: {
crew: [
'@serenity-js/serenity-bdd',
[ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
]
},
// Other configuration omitted for brevity
// For details, see https://webdriver.io/docs/options
}
Usage with Protractor
Learn more about using Serenity/JS with Protractor.
// protractor.conf.js
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
serenity: {
crew: [
'@serenity-js/serenity-bdd',
[ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
]
},
// ...
}
Programmatic configuration
Learn more about configuring Serenity/JS programmatically.
import { ArtifactArchiver, configure } from '@serenity-js/core'
import { SerenityBDDReporter } from '@serenity-js/serenity-bdd'
configure({
crew: [
ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
new SerenityBDDReporter()
],
})
Serenity BDD Living Documentation
To turn the Serenity BDD-standard JSON reports produced by the SerenityBDDReporter
into Serenity BDD test reports,
you need the Serenity BDD reporting CLI.
The Serenity BDD reporting CLI is a Java program, distributed as an executable .jar
file and available on Bintray.
This module ships with a serenity-bdd
CLI wrapper that makes downloading and running the Serenity BDD reporting CLI easy.
To learn more about the usage of the serenity-bdd
wrapper, run:
npx serenity-bdd --help
Configuring Serenity BDD reporting CLI
To configure the Serenity BDD reporting CLI, place a file called serenity.properties
in your project root directory.
For example:
# serenity.properties
serenity.project.name=My awesome project
Please note that the reporting CLI considers only those properties that are related to producing test reports.
Learn more about configuring serenity.properties
.
Downloading the Serenity BDD reporting CLI
To download the Serenity BDD reporting CLI or to update it, use the update command:
npx serenity-bdd update
You can also tell it to download the Serenity BDD reporting CLI jar from your company's artifact repository if you can't use the official Bintray one:
npx serenity-bdd update --repository https://artifactory.example.org/
To learn more about the update
command, run:
npx serenity-bdd --help update
Please note that the update
command will try to download the .jar
only if you don't have it cached already, or when the one you have is not up to date. Otherwise, no outbound network calls are made.
Downloading through a proxy
The update
command will pick up your proxy configuration automatically from your NPM config, .npmrc
file, or environment variables.
Please note that you only need to use one of those configuration mechanisms.
Use NPM config (Linux, macOS, Windows)
To use NPM-level configuration, run the following commands in your terminal:
npm config set proxy http://[user:pwd]@domain.tld:port
npm config set https-proxy http://[user:pwd]@domain.tld:port
If your proxy requires a certificate file, you can provide a path to it as follows:
npm config set cafile /path/to/root-ca.pem
The above can also be accomplished by placing an .npmrc
file with following contents in your home directory or your project root:
# ~/.npmrc
proxy = http://[user:pwd]@domain.tld:port
https-proxy = http://[user:pwd]@domain.tld:port
cafile = /path/to/root-ca.pem # optional
noproxy = localhost,mycompany.com # optional
Environment variables on Linux or macOS
To set your proxy on Linux or macOS, run the following commands in your terminal:
export HTTP_PROXY=http://[user:pwd]@domain.tld:port
export HTTPS_PROXY=http://[user:pwd]@domain.tld:port
If needed, you can also set a NO_PROXY
variable to a comma-separated list of domains that don't require a proxy, for example:
export NO_PROXY=localhost,mycompany.com
Please note that you can add the above commands to your shell's ~/.profile
, so that they're executed whenever you open a new terminal.
Environment variables on Windows
To configure a proxy on Windows, run the following commands in Command Prompt:
set HTTP_PROXY=http://[user:pwd]@domain.tld:port
set HTTPS_PROXY=http://[user:pwd]@domain.tld:port
If you're using Powershell, run the following commands instead:
$env:HTTP_PROXY = http://[user:pwd]@domain.tld:port
$env:HTTPS_PROXY = http://[user:pwd]@domain.tld:port
Use a specific User-Agent
If your artifact registry requires you to use a specific user agent, you can configure it using NPM config:
npm config set user-agent "Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0"
Ignore SSL checks
You can instruct the update
command to ignore any SSL certificate errors by providing an --ignoreSSL
flag when running the command:
npx serenity-bdd update --ignoreSSL
You can also disable certificate checks at the NPM config level by running:
npm config set strict-ssl false
Alternative, you can accomplish the same with an .npmrc
file:
# ~/.npmrc
npm_config_strict-ssl = false
Producing the Serenity BDD test report
To produce the Serenity BDD test report and living documentation using default settings, run:
npx serenity-bdd run
To learn more about the run
command and how to change the default settings, run:
npx serenity-bdd --help run
Using NPM scripts
Serenity BDD reports are generated by Serenity BDD CLI,
a Java program downloaded and managed by the @serenity-js/serenity-bdd
module.
In general, to produce Serenity BDD reports, your test suite must:
- download the Serenity BDD CLI, by calling
serenity-bdd update
- 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:
- an NPM
postinstall
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.
📣 Stay up to date
New features, tutorials, and demos are coming soon! Follow Serenity/JS on LinkedIn, subscribe to Serenity/JS channel on YouTube and join the Serenity/JS Community Chat to stay up to date! Please also make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!
💛 Support Serenity/JS
If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!