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 https://deb.nodesource.com/setup_10.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:
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 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.
Summary
Protractor is easy yet very powerful framework. If you run functional tests agains Angular application, it has great benefits over traditional Selenium Webdriver.
