Getting Started

Introduction

In this series, we will setup an automation framework from scratch to test against the UI frontend of a web application built using AngularJS.

The completed repository can be found at https://gitlab.com/testifyqa/javascript-web-serenityjs.

It is recommended that you be at least some what comfortable with Protractor and understand my blog series on how to create a Cucumber, TypeScript and Protractor framework.

We will use the following in our framework:

  • Serenity/JS
    • Serenity/JS is a node.js library designed to make acceptance and regression testing of modern web applications faster, more collaborative and easier to scale. It extends upon Protractor and can test both Angular and Non-Angular sites.  It also builds on the Screenplay Pattern to help your code follow SOLID principles as well as address some of the pain points of using Page Objects Pattern
  • Protractor
    • Protractor is an automation testing tool for web applications testing; combining powerful technologies such as Jasmine, Selenium WebDriver, Node.js etc. The Protractor testing tool is an end to end behaviour-driven testing framework designed to test AngularJS applications, but as it is built on top of Selenium can also be used to test Non-Angular sites
  • Cucumber
    • Cucumber is a software tool used by computer programmers for testing other software. It runs automated acceptance tests written in a behaviour-driven development style. Central to the Cucumber BDD approach is its plain language parser called Gherkin.
  • Chai
    • Chai is a BDD / TDD assertion library for node and the browser that can be delightfully paired with any javascript testing framework.
  • TypeScript
    • TypeScript is an open-source programming language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript, and adds optional static typing to the language. TypeScript is designed for development of large applications and trans-compiles to JavaScript.

Setting Up Your Source Code Editor

The great thing about Javascript is that pretty much any browser instantly recognises the code. Javascript can be written using any simple text editor (e.g. TextEdit or Notepad), but for the sake of this course, let’s install a good editor like Visual Studio Code 🙂

  1. Download the appropriate Visual Studio Code for your Operating System from https://code.visualstudio.com/download
  2. Follow any instructions and complete the installation of Visual Studio Code.

Launch Visual Studio Code from Command Line / Terminal

Going forwards, it would be nice if we could launch Visual Studio Code from the terminal (if on macOS, on Windows it should be done automatically), so let’s do that now.

  1. Open up Visual Studio Code
  2. Open the Command Palette in Visual Studio Code
    • press Ctrl/CMD + Shift + P
    • Type
      shell command

      to find the ‘Shell Command: Install ‘code’ command in PATH command, and select that

    • Restart the Command Line / Terminal for the new $PATH value to take effect.
      • You’ll be able to type
        code .

        in any folder in the Terminal (or Command Prompt) to start editing files in that folder 🙂

Node.js & NPM (Node Package Manager)

Node.js is an open-source, cross-platform JavaScript run-time environment that executes JavaScript code outside of a browser.

NPM is a package manager for the JavaScript programming language. It is the default package manager for the JavaScript runtime environment Node.js. It consists of a command line client, also called npm, and an online database of public and paid-for private packages, called the npm registry.

Setting up Node.js and NPM

MacOS:

Install HomeBrew (Package Manager)

Homebrew is a free and open-source software package management system that simplifies the installation of software on Apple’s macOS operating system.

  1. Go to https://brew.sh/
  2. Copy the command and paste it into Terminal (if you run into any issues, consult https://docs.brew.sh/Common-Issues)…
    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Install Node.js
  1. Open up Terminal and use Homebrew to install Node.js (NPM will be installed with Node)…
    brew install node
  2. You can check that Node.js and NPM were installed successfully by checking their appropriate version numbers in Terminal…
    node -v
    npm -v

Windows

Setting up Chocolatey

Chocolatey is a package manager for Windows. It is a single, unified interface designed to easily work with all aspects of managing Windows software (installers, zip archives, runtime binaries, internal and 3rd party software) using a packaging framework that understands both versioning and dependency requirements. Chocolatey packages encapsulate everything required to manage a particular piece of software into one deployment artefact by wrapping installers, executables, zips, and scripts into a compiled package file. Chocolatey packages can be used independently, but also integrate with configuration managers like SCCM, Puppet, and Chef.

  1. Search for CMD Prompt
  2. Right-click on Command Prompt and select ‘Run as administrator’
  3. Run the following command…
    @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
  4. Let’s now check that Chocolatey was installed successfully by checking the version number (exit and restart command prompt first if necessary)…
    chocolatey -v
Install Node.js
  1. Open up an elevated Command Prompt (run as Administrator again) and use Chocolatey to install Node.js (NPM will be installed with Node)…
    choco install nodejs
    1. Agree to install [A]ll scripts if prompted
  2. Let’s then check that Node.js and NPM have been installed successfully by checking their version numbers. Enter each of the following in the elevated Command Prompt…
    node -v
    npm -v

Setting up the Node Packages

Now that we have Node.js and NPM (Node Package Manager) installed, we can install node packages for our framework to use.  We can either install it globally using the -g flag, or we can install it locally to the folder we are in. Installing locally will add it to a package.json file, easily allowing any other Developers on the team to get setup with their local environment. Let’s setup our test framework directory now

  1. Open up Terminal (or Command Prompt)
  2. Make a new directory and call it something suitable like ‘serenity-js-framework’…
    mkdir serenity-js-framework
  3. Change directory (cd) into the folder you just made…
    cd serenity-js-framework

Let’s now initialise the directory with NPM, skipping any questions it may ask and going with the defaults (via the -y flag), so that it creates a package.json file. If any other developers checkout this test framework, they can simply run

npm install

and it will install all packages listed in the package.json file.

  1. Make sure you are still in the project root and enter the following command to initialise a default package.json (the -y flag just uses default answers for all the questions asked when creating the file)…
    npm init -y
    • You should see output like below in the Terminal (or Command prompt) window…
      Wrote to /Users/username/serenity-js-framework/package.json:
      
      {
        "name": "serenity-js-framework",
        "version": "1.0.0",
        "description": "",
        "main": "index.js",
        "scripts": {
          "test": "echo \"Error: no test specified\" && exit 1"
        },
        "keywords": [],
        "author": "",
        "license": "ISC"
      }

We are now ready to start adding the Node packages locally in to our test framework directory 🙂

node type definitions

Let’s install the type definitions for using node with TypeScript 🙂

  1. Enter the following in Terminal (or Command prompt), whilst in the root directory of your project, to install the Node type definitions locally to our project…
    npm install @types/node --save

protractor

  1. Let’s install Protractor locally so other Developers can install it from the package.json…
    npm install protractor

typescript

  1. Enter the following in Terminal (or Command prompt), whilst in the root directory of your project, to install TypeScript locally to our project
    npm install typescript

ts-node

TS-Node is an executable, which allows TypeScript to be run seamlessly in a Node.js environment.

  1. Enter the following in Terminal (or Command prompt), whilst in the root directory of your project, to install ts-node locally to our project…
    npm install ts-node

cucumber

  1. Enter the following in Terminal (or Command prompt), whilst in the root directory of your project, to install cucumber locally to our project…
    npm install cucumber

cucumber type definitions

  1. Enter the following in Terminal (or Command prompt), whilst in the root directory of your project, to install cucumber type definitions locally to our project…
    npm install @types/cucumber --save

eslint

ESLint is a linter that statically analyses your Javascript code and identifies any problematic patterns found

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install eslint locally to our project as a devDependency…
    npm install eslint --save-dev

@typescript-eslint/parser

This is an ESLint custom parser which leverages TypeScript ESTree to allow for ESLint to lint TypeScript source code.

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install @typescript-eslint/parser locally to our project as a devDependency…
    npm install @typescript-eslint/parser --save-dev

@typescript-eslint/eslint-plugin

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install @typescript-eslint/eslint-plugin locally to our project as a devDependency…
    npm install @typescript-eslint/eslint-plugin --save-dev

@serenity-js/core

This is the necessary core library for Serenity/JS

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install the new version 2 of the @serenity-js/core module locally to our project…
    npm install @serenity-js/core

@serenity-js/assertions

This is a screenplay-style assertion library for Serenity/JS that includes Chai (hence why we don’t need to install any Chai packages separately)

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install the new version 2 of the @serenity-js/assertions module locally to our project…
    npm install @serenity-js/assertions

@serenity-js/cucumber

This enables Serenity/JS to run Cucumber JS 1.3.x test scenarios. By installing the next upcoming version, it should support the far more recent versions of Cucumber without finding any vulnerabilities 🙂

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install the new version 2 of the @serenity-js/cucumber module locally to our project…
    npm install @serenity-js/cucumber

@serenity-js/console-reporter

This is the console reporter for Serenity/JS

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install the new version 2 of the @serenity-js/console-reporter module locally to our project…
    npm install @serenity-js/console-reporter

@serenity-js/protractor

This library allows you to use Serenity/JS to test web applications via Protractor

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install the new version 2 of the @serenity-js/protractor module locally to our project…
    npm install @serenity-js/protractor

@serenity-js/serenity-bdd

This is a Serenity BDD reporter for Serenity/JS

  1. Enter the following in Terminal (or Command prompt) whilst in the root directory of your project, to install the new version 2 of the @serenity-js/serenity-bdd module locally to our project…
    npm install @serenity-js/serenity-bdd

Configuring ‘eslint’

  1. Now that we have installed the ‘tslint’ package, open up your project in Visual Studio Code and add a new file in the root of the project called ‘.eslintrc.js’
  2. Open up the ‘.eslintrc.js’ file and add the following to get started with a simple configuration…
    module.exports = {
        root: true,
        parser: '@typescript-eslint/parser', // tell ESLint to use the parser package we installed so it understands TypeScript syntax
        plugins: [
          '@typescript-eslint', // load the plugin package we installed so we can use the rules within our codebase
        ],
        extends: [ // ESLint config extends the following given configurations...
          'eslint:recommended',
          'plugin:@typescript-eslint/eslint-recommended',
          'plugin:@typescript-eslint/recommended',
        ],
        rules: {
          "@typescript-eslint/explicit-function-return-type": "off",
        }
    };

Ignoring unnecessary files

  1. Next, create a ‘.eslintignore’ file in the root of your project and add the following in to the file so that ESLint knows which files and folder to never lint and to ignore…
    # don't ever lint node_modules
    node_modules
    # don't ever lint the .vscode directory
    .vscode
    # don't ever lint the protractor.conf.js file
    protractor.conf.js

Running the lint

The lint can now be run on any .ts files we want in our project.

For example, if we wanted to use ESLint to lint all .ts files in our current directory, we would use the following command…

npx eslint . --ext .ts

Installing VS Code Extensions

Let’s now open up Visual Studio Code and install some extensions which will be useful for our project 🙂

  1. Open up Visual Studio Code
  2. Select the Extensions icon on the left (the one that looks like four squares, with one square being broken off)
  3. Search for ‘Cucumber (Gherkin) Full Support’ and click the green install button
  4. Search for ‘Gherkin step autocomplete’ and click the green install button
  5. Search for ‘Protractor Test Runner’ and click the green install button

Installing Java Runtime Environment

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), which you can download from the oracle.com website.

Download the correct version for your Operating System and architecture and follow the instructions to install it

In the next section we will start creating our framework structure and sorting out any configurations (e.g. Protractor, Serenity/JS etc.) 🙂

Liked it? Take a second to support Thomas on Patreon!

Next Article

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.