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)…
Install Node.js
  1. Open up Terminal and use Homebrew to install Node.js (NPM will be installed with 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…
  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)…

    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’…
  3. Change directory (cd) into the folder you just made…

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…

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…

protractor

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

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

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…

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…

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…

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…

@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…

@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…

@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…

@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…

@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…

@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…

@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…

@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…

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…

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…

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…

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.