Skip to main content


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
Getting started with Serenity/JS

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 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,, 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:


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": [

"include": [

"exclude": [

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 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}
Stay up to date

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, you should be able to download Serenity/JS (and other publicly available Node modules) from your company internal artifact registry: