protractor

What is protractor?

Protractor is an end-to-end test framework for Angular and AngularJS applications. It runs tests against your application running in a real browser, interacting with it as a user would.

What are protractor's main functionalities?

End-to-End Testing

Protractor allows you to write end-to-end tests for your Angular applications. The code sample demonstrates navigating to an AngularJS website, selecting elements, and making assertions about their state.

const { browser, element, by } = require('protractor');

browser.get('http://www.angularjs.org');

const todoList = element.all(by.repeater('todo in todoList.todos'));
expect(todoList.count()).toEqual(2);
expect(todoList.get(1).getText()).toEqual('build an AngularJS app');

Automatic Waiting

Protractor automatically waits for Angular to finish rendering and for any outstanding $http calls to be completed before performing the next action. This reduces the need for explicit waits in your tests.

const { browser, element, by } = require('protractor');

browser.get('http://www.angularjs.org');

const addButton = element(by.css('[value="add"]'));
addButton.click();

const todoList = element.all(by.repeater('todo in todoList.todos'));
expect(todoList.count()).toEqual(3);

Integration with Jasmine

Protractor integrates seamlessly with the Jasmine testing framework, allowing you to write tests in a behavior-driven development (BDD) style. The code sample shows a Jasmine test suite that adds a new todo item and verifies its presence.

describe('angularjs homepage todo list', function() {
  it('should add a todo', function() {
    browser.get('http://www.angularjs.org');

    element(by.model('todoList.todoText')).sendKeys('write a protractor test');
    element(by.css('[value="add"]')).click();

    const todoList = element.all(by.repeater('todo in todoList.todos'));
    expect(todoList.count()).toEqual(3);
    expect(todoList.get(2).getText()).toEqual('write a protractor test');
  });
});

Other packages similar to protractor

cypress

Cypress is a next-generation front-end testing tool built for the modern web. It offers a more developer-friendly experience with features like time travel, real-time reloads, and automatic waiting. Unlike Protractor, Cypress does not require WebDriver and runs directly in the browser.

webdriverio

WebdriverIO is a popular testing framework that allows you to run tests based on the WebDriver protocol and Appium. It supports both synchronous and asynchronous commands and can be used for both web and mobile applications. WebdriverIO is more versatile compared to Protractor, which is specifically designed for Angular applications.

testcafe

TestCafe is a Node.js tool to automate end-to-end web testing. It works without WebDriver and is compatible with any modern web application. TestCafe provides a simple syntax and powerful features like parallel test execution and easy integration with CI/CD pipelines. Unlike Protractor, TestCafe is framework-agnostic and can be used with any web application.

README

Protractor

Protractor is an end to end test framework for AngularJS applications built on top of WebDriverJS.

Protractor can be run as a standalone binary runner, or included into your tests as a library. Use Protractor as a library if you would like to manage WebDriver and your test setup yourself.

For more information, read the docs, or head over to the FAQ.

To run the sample tests

Install protractor with.

npm install -g protractor

Start up a selenium server (See the appendix below for help with this). By default, the tests expect the selenium server to be running at http://localhost:4444/wd/hub.

The example folder contains a simple test suite which runs against angularjs.org. Run with:

protractor example/conf.js

Using the Protractor runner

The Protractor runner is a binary which accepts a config file. Install protractor with

npm install -g protractor
# Run the line below to see command line options
protractor

You will need a configuration file containing setup info and test files containing the actual test scripts. The config file specifies how the runner should start webdriver, where your test files are, and global setup options. The test files use Jasmine framework, but other adapters may be added in the future.

Create a configuration file - an example with detailed comments is shown in node_modules/protractor/referenceConf.js. Edit the configuration file to point to your test files.

// myConf.js
exports.config = {
  seleniumAddress: 'http://localhost:4444/wd/hub',
  jasmineNodeOpts: {
    specs: ['myTest.js', 'myTestFolder/*Test.js']
  }
}

The configuration file must specify a way to connection to webdriver. This can be

• seleniumAddress: The address of a running selenium standalone server.
• seleniumServerJar: The location of the selenium standalone .jar file on your machine. Protractor will use this to start up the selenium server.
• sauceUser and sauceKey: The username and key for a SauceLabs account. Protractor will use this to run tests on SauceLabs.

The runner exposes global variables browser, by and element. Check out getting started docs to learn how to write a test.

// myTest.js
describe('angularjs homepage', function() {
  it('should greet the named user', function() {
    browser.get('http://www.angularjs.org');

    element(by.model('yourName')).sendKeys('Julie');

    var greeting = element(by.binding('yourName'));

    expect(greeting.getText()).toEqual('Hello Julie!');
  });
});

Run with

protractor myConf.js

Cloning and running Protractor's own tests

Clone the github repository.

git clone https://github.com/angular/protractor.git
cd protractor
npm install

Start up a selenium server. By default, the tests expect the selenium server to be running at http://localhost:4444/wd/hub.

Protractor's test suite runs against the included testapp. Start that up with

cd testapp
./scripts/web-server.js

Then run the tests with

npm test

Appendix A: Setting up a standalone selenium server

WebdriverJS does not natively include the selenium server - you must start a standalone selenium server. All you need is the latest selenium-server-standalone.

To use with chrome browsers, download chromedriver. More information about chromedriver

A script is included to do the download for you - run (add the --nocd option if you do not want to install ChromeDriver)

./node_modules/protractor/bin/install_selenium_standalone

Start the selenium standalone with

./selenium/start

For alternate ways to download and start the selenium standalone, see the webdriver docs.

Changelog

0.13.0

Note: Major version 0 releases are for initial development, and backwards incompatible changes may be introduced at any time.

Features

• (ce5f494) feat(element): element.all now has 'first' and 'last' methods

• (ef61662) feat(runner): allow bypassing the selenium standalone server if running only chrome

  Using the config option chromeOnly now enables running ChromeDriver directly, without going through the Selenium Standalone. The chromedriver binary should be available in your PATH, or should be specified with the config option chromeDriver.

• (76c094a) feat(getLocationAbsUrl) - allows current url to be obtained on IE (and Chrome/Firefox)

• (6a1c918) feat(runner): add error message for bad jar path

• (98bce7e) feat(locators): add the ability to add custom element locators with by.addLocator

  Custom locators can now be added using by.addLocator(name, script), where script is a self-contained snippet to be executed on the browser which returns an array of elements. Closes #236.

• (c7bcc20) chore(angular): update to angular 1.2

Bug Fixes

• (a24eeee) fix(runner): do not error out if only one spec pattern does not match any files

  Previously, the runner would throw an error if any one of the spec patterns did not match any files. Now it logs a warning in that case, and errors out only if there are no found files in any spec patterns. Closes #260

• (f3b3fdb) fix(element): fix an error where all.then() wasn't calling callbacks.

  Closes #267

• (137d804) fix(jasminewd): patched matcher should understand 'not'

  Closes #139.