Protractor 101

A quick (beginners) tutorial to using Protractor

Protractor? What’s that?

A protractor is a measuring instrument, typically made of transparent plastic or glass, for measuring angles. Most protractors measure angles in degrees(°). Radian-scale protractors measure angles in radians. Most protractors are divided into 180 equal parts. — Wikipedia

But this isn’t the protractor I’m going to tell you about.

Disclosure

I hope to give you a quick introduction to the software testing tool in the form of a quick tutorial. I do emphasise on quick. My goal here is to walk you through writing your first test(s) using Protractor; not dwell on what protractor is made of nor how it functions.

Protractor - E2E Testing Framework

Protractor is an end-to-end test framework that was developed to test Angular/AngularJS applications. That said, Protractor can still be used to test none Angular web sites and web applications as well. It’s built on top WebdriverJS and Selenium using Node.js. Protractor focusses on behaviour driven testing (BDT) and ships with Jasmine by default. This does not mean you are restricted to Jasmine alone; you could use it with other BDT frameworks (such as Mocha and Cucumber) as well. If you would like to learn how to do so, have a look at their documentation here. In this tutorial, however, I’ll be sticking with Jasmine (TBT when I emphasised on the word quick!!!).

As Protractor wraps Selenium WebDriver, it has every feature of Selenium WebDriver in its arsenal. What gives Protractor the edge though, is that it has a few “extras” as well (By.model, By.binding and waitForAngularEnabled to name a few).

Now that I’ve given the customary “introduction” to Protractor, let’s get the to highlight of this article… the tutorial itself!

Pre-Requisites

1. Node.js — If you’re using a Mac and have Homebrew set up, like me, I recommend installing it using the Homebrew formula (i.e. by running brew install node).
2. Java Development Kit (JDK).
3. Visual Studio Code or any other text/code editor of your choice.
4. Google Chrome

Setting Up Protractor

Step 1: Install Protractor

Assuming that you have installed Node.js (if you haven’t… install it already!), run the following command in terminal/command prompt:

npm install -g protractor

Once the installation is complete, run the following to make sure it’s working:

protractor --version

protractor — version (p.s. it should be two dashes)

Step 2: Install JDK

I won’t go into detail on this here since it’s a simple process of downloading the installer and running it. Please remember, you have to get the Java development kit (JDK); not the java runtime environment (JRE).

Step 3: Install Visual Studio Code (or your preferred editor)

In the case of Visual Studio Code, this is a pretty straight forward process as well and so I won’t be going into detail here. I’m guessing this would apply for most, if not all, other editors.

Writing & Running Your First Test

Step 1: Create the project folder structure

The bare essential is a folder with 2 files.

So just create a folder (e.g. protractor-demo) and create the two files shown in the image on the left; conf.js and spec.js.

I’ll go into details about each file while editing them.

Step 2: Start up the selenium server

A selenium server has to always be running in order for you to run your tests. There is no need to install this separately as it comes packaged when you Protractor (as shown above).

Before starting up the server you need to always update it first. To do so run the following command in terminal/command prompt:

webdriver-manager update

Once this has completed, run:

webdriver-manager start

P. S. — Do not close this window until the end of this session.

Step 3: Updating the conf.js file

This is the configuration file for the Protractor project. The following is the most basic configuration file.

As you can see, you only need two configuration to run a simple test:

1. seleniumAddress - This is the address to the instance of the selenium server which the test(s) will run on.
2. specs - This is where you define which “spec” files to execute. It can be one file or multiple files.

Keep in mind that these are the bare essentials only. There are so much more that could be configured such as which BDT framework to use, which browser the tests should run on and so on.

Step 4: Updating the spec.js file

Now this is the file where the test is scripted. Before we get into the scripting though, let’s have a look at what is going to be tested. I’ll be using the basic Two Way Data Binding example on AngularJS Hub. The linked page has code for the application, the example of it and a description on it. However, since we all need is the example, we will ask the test to run on the page which holds the example alone. To get to this, click on the Open in new window button (the icon of an arrow coming out of a rectangle) beside the Example title. You may also find the link in the code below.

Below is the content of the spec.js file:

The first thing you would (or should) notice is the describe keyword. This, as well as the it keyword in the following line, is from the Jasmine framework. Also, you may have noticed, that there is a certain “readability” in the first two lines. If you omit the keywords/syntax and only read the arguments passed in to the describe and it functions, you already have an idea of what is happening. Put simply, the following is what you get:

Protractor 101 should test two way binding

Quite friendly and easy to understand, isn’t it? This is one of the features of the behaviour driven testing! Moving on now…

In line #3, Protractor will launch the browser and navigate to URL passed into the browser.get() command. The browser keyword is part of Protractor which let you carry out browser-level commands. In this example, it uses the get command to navigate to a specific URL.

So what I’m going to do next is interact with the form in the URL via Protractor and perform verify (a.k.a assert) the outcome. If you navigate to the example, you should see the form as below:

The form in the Two Way Data Binding example of AngularJS Hub

This is what I’m going to do:

1. Change the last name from Doe to Peters in the text box.
2. Verify that Peters is displayed as the last name at the top of the form.

Now to achieve the task of changing the last name, we first need to identify the text box in order to interact with it. To do this, right click on the text box and click on Inspect (I’m using Google Chrome by the way; it’ll be something similar on other browsers as well). This would open up the inspector and highlight the element as shown below:

Inspector on Google Chrome

You might notice that this element does not have an ID or name to identify. If you were using a tool like Selenium, for example, then you would have to resort to the xpath or CSS class. This in turn means any changes to the design and/or layout might break the test. Now here’s where the true colours of Protractor are shown. As I’ve already mentioned at the start of this, Protractor has a few “extras”, one of which is the by.model command. You may have noticed that the highlighted input element has a ng-model property. This property is a feature of AngularJS which Protractor was built to test. If you look at line #5 in the spec.js code snippet above, you would notice that by.model command is used to locate the element which is then put into a variable.

var lastNameTextBox = element(by.model(‘lastName’));

Next, let’s clear the existing contents in the text box and type in new text. This is achieved with the following (line #6):

lastNameTextBox.clear().sendKeys(‘Peters’)

Here, the clear command plays a key role. Without this the text would be appended to the text box’s existing content rather than replace it.

Finally, let’s perform the assertion. The following line takes care of this:

expect(element(by.binding(‘lastName’)).getText()).toEqual(‘Peters’);

Let’s this break this down a bit, shall we? Similar to describe and it, expect is also from Jasmine. It allows you to set an expectation. In this exercise I’m going to be verifying the last name value displayed at the top of the form. Once the first thing we have to find the element and for that I’ve used the by.binding command. Also, since I want extract the text alone for the assertion, I use the getText command on the element (which is a span tag in this case).

Finally, a matcher is used on the expectation. In this example, the toEqual matcher is used to check whether the element’s getText value and the expected value (which, in this case, is Peters) match (pun intended!). toEqual isn’t the only matcher though; listed here are all the matchers that are available from Jasmine.

Step 5: Running the test

Finally, to run the test, run the following in terminal/command prompt. Remember that you should be in the folder you created for the Protractor project earlier.

protractor conf.js

Assuming that everything is set up and scripted correctly, your console output should be similar to the following:

protractor conf.js

If any test(s) should fail, the failure count is displayed at the end of the execution. Also, you should see Google Chrome fire up

Closing Words

So I hope this was of some help to you. There are plenty of Protractor tutorials out but I thought I’d do one with a bit more detail. This actually started out as a summary for a introductory workshop I conducted but then I decided to blow it up a bit more so that a complete newcomer could even follow it. Feel free to drop any comments if you have any suggestion. Constructive criticism is always welcome!