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

Test Automation: Good, Bad and Ugly

The modern approach to software quality and software development life cycle requires that business guys, developers and testers understand that the long manual test phase, although often still necessary, must be reduced to a minimum and replaced by test automation. Working in continuous delivery and continuous integration environment requires us to create automated tests that run on demand, checking our application integration and it’s core functionality correctness. However, there are still many problems with designing and writing automated tests, resulting in their costly maintenance or abandonment in favour of a return to manual processes.
In this article I will focus on describing common good practices of test automation. This post is more than an overview than complete reference guide. Broader aspects, such as the Page Object pattern or Page Factory will be described in detail in a separate article on this blog. Although most practices apply for every types of automated tests, thi…

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…

REST-Assured: going deeper

In my previous post I described the basic REST-Assured usage – the lightweight framework for testing RESTful services. Despite the fact that described range of functionalities would be enough in most cases,REST-Assured has a lot more to offer. In this post I would like to bring some more advanced examples of the framework usage.

I recommend you also my other posts about REST-Assured and building microservice’s test automation frameworks:

REST-Assured – framework overviewBuilding microservices testing framework
Object Mapping Sending request’s body as string is easy and straightforward, but it can be inconvenient in the case of more complex operations on request / response properties. Proven solution for this is a good-known serialization of request/response body to objects. REST-Assured supports object mapping to (and from) JSON and XML. For JSON you need either to have Jackson or Gson in your classpath and for XML you need JAXB. Here is an example of request object serialization using J…