Installation
In this article, you'll learn how to:
- create a Node.js project capable of running Serenity/JS test scenarios
- install runtime dependencies required to create automated tests based on Serenity/JS
- configure TypeScript (if you'd like to)
- install Serenity/JS modules
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.
Installing Node.js
Serenity/JS is a Node.js program. To help you ensure maximum stability of your test scenarios, Serenity/JS relies on a recent Long-Term Support (LTS) version of the Node.js platform.
You can get both Node.js and the Node Package Manager (npm) either from the nodejs.org website, which provides convenient installers for all the major operating systems, or using the Node Version Manager (nvm). The second option is more appropriate if you need to work with several versions of the Node.js platform simultaneously.
To check if your machine is set up correctly, execute the following command in your terminal:
node --version
The version number returned by the above command should be a recent version of Node 16.13, 18.12, or 20. For example, Node v18.16.0.
Installing Java Runtime Environment (JRE)
Serenity/JS delegates the work of generating the illustrated HTML reports to Serenity BDD, which is a Java library and therefore requires a Java Runtime Environment (JRE) version 8 or newer.
You can download the JRE from oracle.com, adoptopenjdk.net, or by using the excellent Software Development Kit Manager (SDKMan)
To verify that you have the JRE installed, execute the below command in your terminal:
java -version
The output should look similar to the following:
java version "1.8.0_181"
Java(TM) SE Runtime Environment (build 1.8.0_181-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.181-b13, mixed mode)
If you're working with several versions of the Java platform simultaneously, please make sure that you point
your JAVA_HOME environment variable at the correct version.
On macOS this could be:
echo $JAVA_HOME
/Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home
Please consult the Oracle documentation for more details.
Creating a Node.js project
Serenity/JS is typically installed as a dev dependency of a Node.js project. This way it doesn't accidentally get bundled together with your production dependencies.
If you're introducing Serenity/JS to an existing project you can skip this section as its purpose is to help you
create package.json - a Node.js project descriptor file, which would already be part of your project.
To create a Node.js project from scratch, create a new directory, such as serenity-js-example.
Next, initialise a new Node.js project accepting the default configuration suggested by the npm with these terminal commands:
mkdir serenity-js-example
cd serenity-js-example
npm init
Your actions should result in a basic package.json
file appearing under serenity-js-example, with contents similar to the following:
{
"name": "example",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC"
}
Installing a web browser
If you're planning to make your acceptance tests interact with a web interface, you'll need a web browser. The way you install web browsers and their associated drivers depends on whether you want to use Playwright or a Selenium Webdriver-based integration library, such as WebdriverIO or Protractor.
Using Playwright
For test suites using Playwright, install playwright module, as well as its browsers and operating system-level dependencies
by running the below commands in your terminal:
npm install --save-dev playwright
npx playwright install --with-deps
Learn more about the installing Playwright.
Using Selenium Webdriver
For test suites using the Selenium Webdriver protocol via WebdriverIO or Protractor, you'll need to install the appropriate web browsers and their associated drivers on any machine running the tests.
If you already have Google Chrome installed locally, you can add its driver to your Node project by running the following command in your terminal:
npm install --save-dev chromedriver
Consult the Selenium project documentation to learn how to install other drivers.
Using TypeScript
Serenity/JS is written in TypeScript and offers first-class support for TypeScript projects.
To use TypeScript in your project, install the following dependencies:
npm install typescript @types/node ts-node
Next, create a tsconfig.json file in your project root directory:
{
"compilerOptions": {
"target": "es2019",
"lib": ["es2019", "dom"],
"module": "commonjs",
"moduleResolution": "node",
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"sourceMap": true,
"declaration": true,
"types": [
"node"
]
},
"include": [
"features/**/*.ts",
"test/**/*.ts"
],
"exclude": [
"node_modules"
]
}
Make sure to configure the include property to cover all your
testing-related TypeScript sources.
Installing Serenity/JS modules
All the official Serenity/JS modules are distributed
via the Node Package Manager registry at npmjs.com
and published under the @serenity-js/ namespace.
Each Serenity/JS module provides detailed installation instructions, and you can install them from your computer terminal by running:
npm install --save-dev @serenity-js/core
You can also install several Serenity/JS modules simultaneously:
npm install --save-dev @serenity-js/{assertions,console-reporter,core,rest,serenity-bdd}
Please make sure to always update your Serenity/JS dependencies together and use the same version number for all the @serenity-js/* modules you depend on.
Learn more about versioning.
If your machine is part of a corporate network and doesn't have direct access to npmjs.com, you should be able to download Serenity/JS (and other publicly available Node modules) from your company internal artifact registry: