Blog

This chapter lets you understand various core APIs that are key to the functioning of the protractor.

Importance of Protractor APIs

Protractor provides us a wide range of APIs which are very important in order to perform the following actions for getting the current state of the website −

• Getting the DOM elements of the web page we are going to test.
• Interacting with the DOM elements.
• Assigning actions to them.
• Sharing information to them.

To perform the above tasks, it is very important to understand Protractor APIs.

Various Protractor APIs

As we know that Protractor is a wrapper around Selenium-WebDriver which is the WebDriver bindings for Node.js. Protractor has the following APIs −

Browser

It is a wrapper around an instance of WebDriver which is used to handle browser-level commands such as navigation, page-wide information, etc. For example, the browser.get method loads a page.

Element

It is used to search and interact with the DOM elements on the page we are testing. For this purpose, it requires one parameter for locating the element.

Locators (by)

It is a collection of element locator strategies. The elements, for example, can be found by CSS selector, by ID, or by any other attribute they are bound to with ng-model.

Next, we are going to discuss in detail these APIs and their functions.

Browser API

As discussed above, it is a wrapper around an instance of WebDriver for handling browser-level commands. It performs various functions as follows −

Functions and Their Descriptions

The functions of ProtractorBrowser API are as follows−

browser.angularAppRoot

This function of Browser API sets the CSS selector for an element on which we are going to find Angular. Usually, this function is in ‘body’, but in the case of our ng-app, it is on a sub-section of the page; it may be a sub-element also.

browser.waitForAngularEnabled

This function of Browser API can be set to true or false. As the name suggests, if this function is set for false then Protractor will not wait for Angular $http and $timeout tasks to complete before interacting with the browser. We can also read the current state without changing it by calling waitForAngularEnabled() without passing a value.

browser.getProcessedConfig

With the help of this browser APIs function, we can get the processed configuration object, including specification & capabilities, that is currently being run.

browser.forkNewDriverInstance

As the name suggests this function will fork another instance of browser to be used in interactive tests. It can be run with control flow enabled and disabled. An example is given below for both the cases −

Example 1

Running browser.forkNewDriverInstance() with control flow enabled −

var fork = browser.forkNewDriverInstance();

fork.get(‘page1’);

Example 2

Running browser.forkNewDriverInstance() with control flow disabled −

var fork = await browser.forkNewDriverInstance().ready;

await forked.get(‘page1’);

browser.restart

As the name suggests, it will restart the browser by closing the browser instance and creating a new one. It can also run with control flow enabled and disabled. An example is given below for both the cases −

Example 1 − Running browser.restart() with control flow enabled −

browser.get(‘page1’);

browser.restart();

browser.get(‘page2’);

Example 2 − Running browser.forkNewDriverInstance() with control flow disabled −

await browser.get(‘page1’);

await browser.restart();

await browser.get(‘page2’);

browser.restartSync

It is similar to the browser.restart() function. The only difference is that it returns the new browser instance directly rather than returning a promise resolving to the new browser instance. It can only run when the control flow is enabled.

Example − Running browser.restartSync() with control flow enabled −

browser.get(‘page1’);

browser.restartSync();

browser.get(‘page2’);

browser.useAllAngular2AppRoots

As the name suggests, it is compatible with Angular2 only. It will search through all the angular apps available on the page while finding elements or waiting for stability.

browser.waitForAngular

This browser API function instructs the WebDriver to wait until Angular has finished rendering and has no outstanding $http or $timeout calls before continuing.

browser.findElement

As the name suggests, this browser API function waits for Angular to finish rendering before searching for elements.

browser.isElementPresent

As the name suggests, this browser API function will test for the element to be present on the page or not.

browser.addMockModule

It will add a module to load before Angular every time the Protractor.get method is called.

Example

browser.addMockModule('modName', function() {

   angular.module('modName', []).value('foo', 'bar');

});

browser.clearMockModules

unlike browser.addMockModule, it will clear the list of registered mock modules.

browser.removeMockModule

As the name suggests, it will remove a register mock modules. Example: browser.removeMockModule(‘modName’);

browser.getRegisteredMockModules

Opposite to browser.clearMockModule, will get the list of registered mock modules.

browser.get

We can use browser.get() to navigate the browser to a particular web address and load the mock modules for that page before the Angular load.

Example

browser.get(url);

browser.get('http://localhost:3000'); 

// This will navigate to the localhost:3000 and will load mock module if needed

browser.refresh

As the name suggests, this will reload the current page and loads mock modules before Angular.

browser.navigate

As the name suggests, it is used to mix navigation methods back into the navigation object so that they are invoked as before. Example: driver.navigate().refresh().

browser.setLocation

It is used to browse to another page using in-page navigation.

Example

browser.get('url/ABC');

browser.setLocation('DEF');

expect(browser.getCurrentUrl())

   .toBe('url/DEF');

It will navigate from ABC to DEF page.

browser.debugger

As the name suggests, this must be used with protractor debug. This function basically adds a task to the control flow to pause the test and inject helper functions into the browser so that debugging can be done in the browser console.

browser.pause

It is used for debugging WebDriver tests. We can use browser.pause() in our test to enter the protractor debugger from that point in the control flow.

Example

element(by.id('foo')).click();

browser.pause();

// Execution will stop before the next click action.

element(by.id('bar')).click();

browser.controlFlowEnabled

It is used to determine whether the control flow is enabled or not.