Skip to main content

Installing Serenity/JS

In this article, you'll learn how to create a brand-new test automation project and install Serenity/JS from scratch.

I'll show you 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)
  • Choose and install appropriate Serenity/JS modules
Short on time? ⏱️

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.

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:

v18.20.2

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

openjdk 21.0.1 2023-10-17 LTS
OpenJDK Runtime Environment Temurin-21.0.1+12 (build 21.0.1+12-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.1+12 (build 21.0.1+12-LTS, 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
/Users/jan/.sdkman/candidates/java/21.0.1-tem

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.

Using WebdriverIO installation wizard​

If you're planning to start a new project using WebdriverIO, use the WebdriverIO installation wizard to generate the initial structure:

npm init wdio .

Next, follow the Serenity/JS "Getting Started" guide for WebdriverIO.

Using Playwright Test installation wizard​

If you're planning to use Playwright Test, use Playwright Test installation wizard:

npm init playwright@latest

Next, follow the Serenity/JS "Getting Started" guide for Playwright Test

Using plain Node.js​

If your chosen test runner doesn't offer an installation wizard, or when you want 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:

serenity-js-example/package.json
{
  "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 browsers​

To use Serenity/JS with Playwright and its default test runner - Playwright Test, use its dedicated installation wizard then add Serenity/JS as per the getting started guide:

npm init playwright@latest

To use Playwright with another test runner, like Cucumber.js, install the playwright module, as well as its browsers and operating system-level dependencies by running the below commands in your terminal:

serenity-js-example/
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:

serenity-js-example/
npm install --save-dev chromedriver

If you want to test with a specific version of Google Chrome, consider using Google Chrome for Testing.

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:

serenity-js-example/
npm install typescript @types/node ts-node

Next, create a tsconfig.json file in your project root directory:

serenity-js-example/tsconfig.json
{
  "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. This is to help you distinguish the original Serenity/JS modules developed and maintained by the Serenity/JS Team from other modules created by the Serenity/JS Community.

Each Serenity/JS module provides detailed installation instructions, and you can install them from your computer terminal by running command similar to the one below:

npm install --save-dev @serenity-js/core

On macOS and Linux you can save yourself some keystrokes and install several Serenity/JS modules simultaneously thanks to the terminal supporting Bash brace expansion:

npm install --save-dev @serenity-js/{assertions,console-reporter,core,rest,serenity-bdd}

On Windows, or when your shell doesn't support Bash brace expansion, you'll need to specify each Serenity/JS module individually:

npm install --save-dev \
    @serenity-js/assertions \
    @serenity-js/console-reporter \
    @serenity-js/core \
    @serenity-js/rest \
    @serenity-js/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 npmjs.com, you should be able to download Serenity/JS (and other publicly available Node modules) from your company internal artifact registry:

Configuring a test runner​

Follow the below instructions to configure your chosen test runner:

You might also want to consult the Serenity/JS Examples and Reference Implementations on GitHub.

Examples and reference implementations​

If you ever get stuck setting up a Serenity/JS project from scratch, make sure to review:

Also, remember to join the Serenity/JS Community chat where you can meet fellow Serenity/JS developers who might be able to help you out.