Skip to main content

Protractor Tutorial: example project setup

Web development is easily one of the fastest changing field of software engineering. When comes to web application’s functional testing, there is one king – Selenium Webdriver. It has been in use for about a decade and it’s still greatly popular. With demand for fast and reliable single page app’s development framework, Angular’s become first choice for majority of new web projects. Although Selenium Webdriver is still great tool for testing Angular applications, it falls short in some framework-specific aspects.

Developers and community behind Angular framework quickly realised that and came out with their own implementation of Selenium Webdriver – Protractor, an end-to-end testing framework, written on top of WebdriverJS. Protractor runs test agains your application in browser, simulating real user.

With this post I want to start a new tutorial series on my blog. In next few posts we will go from bootstrapping new project, through popular patterns and some advanced configurations, up to development style-guide. So, let’s start with configuring new protractor project from scratch!

Setting your environment 

First thing we’ll need is Node.js installed. Node.js is a runtime environment for JavaScript applications. With Node.js comes npm – one of the most popular open source libraries ecosystem, which we’ll use further for installing protractor. Installing Node.js is OS-specific. If you’re a Windows user, just download Windows installer. For Mac users, you can check Mac installer or open your terminal and use brew:

$ brew install node

For Debian and Ubuntu distributions:

$ curl -sL | sudo -E bash -
$ sudo apt-get install -y nodejs

To check your installation, open terminal and type:

$ node --version

Protractor installation

As we’ve mentioned, Node.js come with library manager – npm. To install protractor via npm, open your terminal and execute:

$ npm install -g protractor

This would install globally (-g switch) both protractor and it’s sub-package – webdriver-manager, which runs Selenium Server. You can check your installation with:

$ protractor --version

Next thing is to update our webdriver-manager packages:

$ webdriver-manager update

You can start your Selenium Server now:

$ webdriver-manager start

After opening http://localhost:4444/wd/hub (or, if you’re Mac user) address in your browser, you should see a selenium server up and running:

Project configuration 

Configuration of protractor project is super-simple. For a basic setup, all you’d need are two files: one with protractor configuration and second with your test. Let’s start with configuration. Create a config.js file first:

This is a minimal protractor’s configuration. SeleniumAddress field points for selenium-server address (for Mac users, you may have to change localhost for Specs field tells protractor where are your tests. Name of your config file is up to you, but it must have .js or .coffee extension.

Lets test our configuration! Save your config file, and run protractor:

$ protractor config.js

Remember to have selenium-server running in backgroud (or different terminal window). In case you’ve stopped it, you can fire it up with:

$ webdriver-manager start

Since we have no tests, output should be similar to:

~/protractor_example $ protractor config.js
[18:56:42] I/hosted - Using the selenium server at http://localhost:4444/wd/hub
[18:56:42] I/launcher - Running 1 instances of WebDriver
No specs found
Finished in 0.002 seconds
[18:56:43] I/launcher - 0 instance(s) of WebDriver still running
[18:56:43] I/launcher - chrome #01 passed

Creating first test 

Last thing we’ll need is a test itself. We’ll look closer into test implementation in next Protractor’s tutorials, but since we want just an example specification now, we’ll use one from official documentation:

Save the file as mytest.js (name should correspond to one you define in specs field in config.js). After that, we’re ready to run our test:

$ protractor config.js

Since protractor is very fast, you should see chrome browser flashing quickly and terminal output: 1 spec, 0 failures. That’s it! We have created basic protractor configuration and run our first script.

Dependency management 

To run our test, we need runtime environment, which is Node.js and one dependency – protractor. Usually we’ll run our tests on continuous integration servers, and we don’t want to ship our project’s with all dependencies. Node.js comes with dependency management tool, the one we mentioned before – npm. Idea behind npm should be well known for all of you who worked before with tools like maven or gradle. We create dependecies definition in file package.json file, and Node.js do all the work for us. Let’s create our package.json file:

Protractor is our only dependency. Now after cloning our test-project repository, we run:

$ npm install

…and all defined dependencies would be installed in /node_modules directory.

Running tests 

There’s common misconception about protractor: running selenium-server as a backgroud process. In project configuration paragraph we’ve mentioned that before running actual protractor tests, we need to have webdriver-manager up and running. If we run our tests on remote servers, running this process in background can be tricky.

There’s more simple solution though! If you want to start selenium-server, run your test and stop selenium-server afterwards, you can do it in one command. Open your config.js and delete line pointing on selenium-server address: seleniumAddress: ‘http://localhost:4444/wd/hub‘. Now you don’t need to start selenium-server before running tests. You simply run:

$ protractor config.js

…and protractor will start selenium-server for you, and kill it after running tests.


Protractor is easy yet very powerful framework. If you run functional tests agains Angular application, it has great benefits over traditional Selenium Webdriver.

Popular posts from this blog

REST-Assured framework overview

In modern software development, REST services becomes most popular choice for implementing distributed and scalable web application. They are light and easy to maintain, which results in faster and more effective implementation and system integration.
I recommend you also my other posts about REST-Assured and building microservice’s test automation frameworks: REST-Assured: going deeperBuilding microservices testing framework
With the increase popularity of RESTful services, there is a need for fast and lightweight tool for REST webservices testing automation. One of the most popular choice is Rest-Assured framework from Jayway. It introduces simplicity of testing web services from dynamic languages like groovy or ruby to java. In this post we will get our hands dirty and write automatic test in Rest-Assured framework.
In order to create complete implementation of automated tests in Rest-Assured framework, we need to write our code against some example API. We’ll use standalone Wiremock m…

Testing Asynchronous APIs: Awaitility tutorial

Despite the growing popularity of test automation, most of it is still likely to be done on the frontend side of application. While GUI is a single layer that puts all the pieces together, focusing your automation efforts on the backend side requires dealing with distributed calls, concurrency, handling their diversity and integration.
Backend test automation is especially popular in the microservices architecture, with testing REST API’s. I’ve noticed that dealing with asynchronous events is particularly considered as challenging. In this article I want to cover basic usage of Awaitility – simple java library for testing asynchronous events. All the code examples are written in groovy and our REST client is Rest-Assured.
Synchronous vs Asynchronous In simple words, synchronous communication is when the API calls are dependent and their order matters, while asynchronous communication is when the API calls are independent. Quoting Apigee definition:
Synchronous  If an API call is synchrono…

Notes after TestingCup 2018

On May 28-29th I attended TestingCup conference in Łódź. Having quite unique perspective: this was my second year in row as a Speaker at this conference I want to share some thoughts on the event. Dust has settled, lets go! 

Championship Originally TestingCup is a software testing championship. Wait, what? Yes, the formula is unique: teams and individuals from all around Poland are competing in finding the most bugs and defects in specially prepared application - Mr. Buggy. I don’t have specific data, but since this year’s conference was all english I guess competitors were not only from Poland. As a spectator, I must say that the whole competition looked very professional. There were team shirts and names, podium and trophies (gold cup and cash). 
Some cons? Testing championship is held at the first day of the conference. So this is already a conference, but if you’re not taking part in the championship… there’s not much to do, since all the talks are in the next day. Organizers are aw…