Setting Up Protractor

Prerequisites

Node.js

Protractor is a  program. To run Protractor, you will need to have Node.js installed. Check the version of node you have by running node --version. It should be greater than v0.10.0. 

Node.js comes with the Protractor  package, which you can use to install Protractor.

Installing Protractor

Use npm to install Protractor globally (omit the -g if you’d prefer not to install globally):

npm install -g protractor

Check that Protractor is working by running protractor --version.

The Protractor install includes the following:

• protractor command line tool

• webdriver-manager command line tool

• Protractor API (library)

Setting Up the Selenium Server

When working with Protractor, you need to specify how to connect to the browser drivers which will start up and control the browsers you are testing on. You will most likely use the Selenium Server. The server acts as proxy between your test script (written with the WebDriver API) and the browser driver (controlled by the WebDriver protocols).

The server forwards commands from your script to the driver and returns responses from the driver to your script. The server can handle multiple scripts in different languages. The server can startup and manage multiple browsers in different versions and implementations.

     [Test Scripts] < ------------ > [Selenium Server] < ------------ > [Browser Drivers]

The  includes several options for the Selenium Server, which are explained in the sections below.

Standalone Selenium Server

To run the Selenium Server on your local machine, use the standalone Selenium Server. 

JDK

To run a local Selenium Server, you will need to have the  installed. Check this by running java -version from the command line.

Installing and Starting the Server

To install and start the standalone Selenium Server manually, use the webdriver-manager command line tool, which comes with Protractor.

1. Run the update command: webdriver-manager update This will install the server and ChromeDriver.

2. Run the start command: webdriver-manager start This will start the server. You will see a lot of output logs, starting with INFO. The last line will be 'Info - Started org.openqa.jetty.jetty.Server'.

3. Leave the server running while you conduct your test sessions.

4. In your config file, set seleniumAddress to the address of the running server. This defaults to http://localhost:4444/wd/hub.

Starting the Server from a Test Script

To start the standalone Selenium Server from within your test script, set these options in your config file:

• seleniumServerJar - The location of the jar file for the standalone Selenium Server. Specify a file location.

• seleniumPort - The port to use to start the standalone Selenium Server. If not specified, defaults to 4444.

• seleniumArgs - Array of command line options to pass to the server. For a full list, start the server with the -help flag.

Connecting to a Running Server

To connect to a running instance of a standalone Selenium Server, set this option:

• seleniumAddress - Connect to a running instance of a standalone Selenium Server. The address will be a URL.

Please note that if you set seleniumAddress, the settings for seleniumServerJar, seleniumPort, seleniumArgs, browserstackUser, browserstackKey, sauceUser and sauceKey will be ignored.

Remote Selenium Server

To run your tests against a remote Selenium Server, you will need an account with a service that hosts the server (and the browser drivers). Protractor has built in support for  and .

Using BrowserStack as remote Selenium Server

In your config file, set these options:

• browserstackUser - The username for your BrowserStack account.

• browserstackKey - The key for your BrowserStack account.

Please note that if you set browserstackUser and browserstackKey, the settings for seleniumServerJar, seleniumPort, seleniumArgs, sauceUser and sauceKey will be ignored.

You can optionally set the  in a capability in order to give the jobs a name on the server. Otherwise they will just be allotted a random hash.

Using Sauce Labs as remote Selenium Server

In your config file, set these options:

• sauceUser - The username for your Sauce Labs account.

• sauceKey - The key for your Sauce Labs account.

Please note that if you set sauceUser and sauceKey, the settings for seleniumServerJar, seleniumPort, seleniumArgs, browserstackUser and browserstackKey will be ignored.

You can optionally set the  in a capability in order to give the jobs a name on the server. Otherwise they will just be called Unnamed Job.

Connecting Directly to Browser Drivers

Protractor can test directly against Chrome and Firefox without using a Selenium Server. To use this, in your config file set directConnect: true.

• directConnect: true - Your test script communicates directly Chrome Driver or Firefox Driver, bypassing any Selenium Server. If this is true, settings for seleniumAddress and seleniumServerJar will be ignored. If you attempt to use a browser other than Chrome or Firefox an error will be thrown.

The advantage of directly connecting to browser drivers is that your test scripts may start up and run faster.

Setting Up the Browser

Protractor works with , a browser automation framework. Selenium WebDriver supports several browser implementations or  which are discussed below.

Browser Support

Protractor supports the two latest major versions of Chrome, Firefox, Safari, and IE.

Please see  for a full list of supported browsers and known issues.

Configuring Browsers

In your Protractor config file (see ), all browser setup is done within the capabilities object. This object is passed directly to the WebDriver builder (). 

See  for full information on which properties are available.

Using Mobile Browsers

Please see the  documentation for information on mobile browsers.

Using Browsers Other Than Chrome

To use a browser other than Chrome, simply set a different browser name in the capabilities object.

capabilities: {  'browserName': 'firefox'}

You may need to install a separate binary to run another browser, such as IE or Android. For more information, see .

Adding Chrome-Specific Options

Chrome options are nested in the chromeOptions object. A full list of options is at the  site. For example, to show an FPS counter in the upper right, your configuration would look like this:

capabilities: {  'browserName': 'chrome',  'chromeOptions': {    'args': ['show-fps-counter=true']  }},

Testing Against Multiple Browsers

If you would like to test against multiple browsers, use the multiCapabilities configuration option.

multiCapabilities: [{  'browserName': 'firefox'}, {  'browserName': 'chrome'}]

Protractor will run tests in parallel against each set of capabilities. Please note that if multiCapabilities is defined, the runner will ignore the capabilities configuration.

Using Multiple Browsers in the Same Test

If you are testing apps where two browsers need to interact with each other (e.g. chat systems), you can do that with protractor by dynamically creating browsers on the go in your test. Protractor exposes a function in the browser object to help you achieve this: browser.forkNewDriverInstance(opt_useSameUrl, opt_copyMockModules). Calling this will return a new independent browser object. The first parameter in the function denotes whether you want the new browser to start with the same url as the browser you forked from. The second parameter denotes whether you want the new browser to copy the mock modules from the browser you forked from.

browser.get('http://www.angularjs.org');browser.addMockModule('moduleA', "angular.module('moduleA', []).value('version', '3');");// To create a new browser.var browser2 = browser.forkNewDriverInstance();// To create a new browser with url as 'http://www.angularjs.org':var browser3 = browser.forkNewDriverInstance(true);// To create a new browser with mock modules injected:var browser4 = browser.forkNewDriverInstance(false, true);// To create a new browser with url as 'http://www.angularjs.org' and mock modules injected:var browser4 = browser.forkNewDriverInstance(true, true);

Now you can interact with the browsers. However, note that the globals element, $, $$ and browser are all associated with the original browser. In order to interact with the new browsers, you must specifically tell protractor to do so like the following:

var element2 = browser2.element;var $2 = browser2.$;var $$2 = browser2.$$;element2(by.model(...)).click();$2('.css').click();$$2('.css').click();

Protractor will ensure that commands will automatically run in sync. For example, in the following code, element(by.model(...)).click() will run before browser2.$('.css').click():

browser.get('http://www.angularjs.org');browser2.get('http://localhost:1234');browser.sleep(5000);element(by.model(...)).click();browser2.$('.css').click();

Setting up PhantomJS

Note: We recommend against using PhantomJS for tests with Protractor. There are many reported issues with PhantomJS crashing and behaving differently from real browsers.

In order to test locally with , you'll need to either have it installed globally, or relative to your project. For global install see the . For local install run: npm install phantomjs.

Add phantomjs to the driver capabilities, and include a path to the binary if using local installation:

capabilities: {  'browserName': 'phantomjs',  /*    * Can be used to specify the phantomjs binary path.   * This can generally be ommitted if you installed phantomjs globally.   */  'phantomjs.binary.path': require('phantomjs').path,  /*   * Command line args to pass to ghostdriver, phantomjs's browser driver.   * See https://github.com/detro/ghostdriver#faq   */  'phantomjs.ghostdriver.cli.args': ['--loglevel=DEBUG']}

Choosing a Framework

Protractor supports two behavior driven development (BDD) test frameworks out of the box: Jasmine and Mocha. These frameworks are based on JavaScript and Node.js and provide the syntax, scaffolding, and reporting tools you will use to write and manage your tests.

Using Jasmine

Currently, Jasmine Version 2.x is supported and the default test framework when you install Protractor. For more information about Jasmine, see the . For more information regarding how to upgrade to Jasmine 2.x from 1.3, see the .

Using Mocha

Note: Limited support for Mocha is available as of December 2013. For more information, see the .

If you would like to use the Mocha test framework, you'll need to use the BDD interface and Chai assertions with .

Download the dependencies with npm. Mocha should be installed in the same place as Protractor - so if protractor was installed globally, install Mocha with -g.

npm install -g mochanpm install chainpm install chai-as-promised

You will need to require and set up Chai inside your test files:

var chai = require('chai');var chaiAsPromised = require('chai-as-promised');chai.use(chaiAsPromised);var expect = chai.expect;

You can then use Chai As Promised as such:

expect(myElement.getText()).to.eventually.equal('some text');

Finally, set the 'framework' property to 'mocha', either by adding framework: 'mocha' to the config file or by adding --framework=mocha to the command line.

Options for Mocha such as 'reporter' and 'slow' can be given in the  with mochaOpts:

mochaOpts: {  reporter: "spec",  slow: 3000}

For a full example, see Protractor’s own test: .

Using Cucumber

Note: Cucumber is no longer included by default as of version 3.0. You can integrate Cucumber with Protractor with the custom framework option. For more information, see the  or the .

If you would like to use the Cucumber test framework, download the dependencies with npm. Cucumber should be installed in the same place as Protractor - so if protractor was installed globally, install Cucumber with -g.

npm install -g cucumbernpm install --save-dev protractor-cucumber-framework

Set the 'framework' property to custom by adding framework: 'custom' and frameworkPath: 'protractor-cucumber-framework' to the 

Options for Cucumber such as 'format' can be given in the config file with cucumberOpts:

exports.config = {  // set to "custom" instead of cucumber.  framework: 'custom',  // path relative to the current config file  frameworkPath: 'protractor-cucumber-framework'  // relevant cucumber command line options  cucumberOpts: {    format: "summary"  }};

Using a Custom Framework

Check section  specifically