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.

protractor-logo-large

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 https://deb.nodesource.com/setup_4.x | 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 http://127.0.0.1:4444/wd/hub, if you’re Mac user) address in your browser, you should see a selenium server up and running:

selenium_server

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 127.0.0.1). 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
Started
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 backgroud 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.

Summary

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

If you want to continue learning Protractor, stay in touch – next parts of protractor tutorial are coming!

  • Pingback: Testing Bits – 10/23/16 – 10/29/16 | Testing Curator Blog()

  • Pingback: Protractor Tutorial: Jasmine test logging | TEST DETECTIVE()

  • Andrey V

    Hi Lukasz, thank you for useful article! Could you please share your opinion (pros/cons) in scope of Protractor vs. Selenium WebDriver for AngularJS apps?

    • Łukasz Rosłonek

      Hi @disqus_HO33WaYgTe:disqus

      Most obvious pros are of course ability to use angular-specific locators and taking advantage from webdriverJS asynchronous nature.

      As for the cons: I don’t treat it really as a cons – more like a challenges 😉 – but before you dive into protractor or webdriverJS in general, you should understand deeply how promises and control flow works.

      Those are just a quick notes, I’m planning to do a full post on this subject in near future, so keep updated!

      • Andrey V

        Hi @lukaszrosonek:disqus
        Thanks for the answer, and are there any difficulties with using Selenium for testing AngularJS apps?