Protractor Helpers

This library extends Protractor API with a commonly used API. It helps write more understandable and clean tests with a well-defined separation between the test logic and the app under the test logic. It consists of four extension types: elements, helpers, locators, and matchers.

Get Started

Get Protractor Helpers via npm by running $ npm install --save-dev protractor-helpers from your console.
In your e2e tests, import the protractor-helpers module and start using it.

var helpers = require('protractor-helpers');

Usage

Elements

The Elements API extends ElementArrayFinder with:

getByText(comparedTest:string) => ElementFinder

example (choosing a date from a calendar):

$$('.calendar').getByText('27').click();

Helpers

not - Returns the negative value of a Promise.

helpers.not($('.some-element').isDisplayed());

translate - Returns the translated key with translation values.

expect($('.some-element').getText()).toEqual(helpers.translate('SOME_TRANSLATION_KEY'));

safeGet - Navigates to a URL, maximizing the window and resetting the mouse position.

helpers.safeGet('./SomeUrl');

maximizeWindow - Maximizes the window to a given size or a default size.

helpers.maximizeWindow(500, 500);

resetPosition - Resets the mouse position.

helpers.resetPosition();

displayHover - Displays an element that appears only on hover state.

helpers.displayHover($('.some-element'));

waitForElement - Waits for an element to be shown.

helpers.waitForElement($('.some-element'), timeout, optionalMessage);

waitForElementToDisappear - Waits for an element not to be shown.

helpers.waitForElementToDisappear($('.some-element'), timeout, optionalMessage);

selectOptionByText - Selects an element from a selection box.

helpers.selectOptionByText($('select'), 'options-to-select');

selectOptionByIndex - Selects an element from a selection box.

helpers.selectOptionByIndex($('select'), 0);

selectOption - Selects a given option.

helpers.selectOption($$('select option').first());

isFirefox - Indicates whether Firefox is the browser.

if (helpers.isFirefox()) {
  // Do FF stuff here . . .
}

createMessage - Creates a matchers message with {{locator}}, {{not}}, and {{actual}} as placeholders.

helpers.createMessage(this, 'Expected {{locator}}{{not}}to have image') + '.');

isIE - Indicates whether Internet Explorer is the browser.

if (helpers.isIE()) {
  // Do IE stuff here . . .
}

clearAndSetValue - Allows setting a new value to an input field (rather than appending text).

helpers.clearAndSetValue(inputField, 'text to populate');

getFilteredConsoleErrors - Returns console error messages resulting from the test run.
Ignores livereload error (since it is not loaded in CI mode), messages with warn and below severity, and a known Firefox bug (https://bugzilla.mozilla.org/show_bug.cgi?id=1127577).
Can be used to validate that there are no console errors.

expect(helpers.getFilteredConsoleErrors().length).toBe(0);

hasClass - Checks whether an element has a class.

helpers.hasClass(element, 'class-name');

Locators

Adds two locators: by.dataHook and by.dataHookAll. Searches for element(s) with the data-hook attribute. For example:

<ul>
  <li data-hook="first">First</li>
  <li data-hook="second">Second</li>
</ul>

element(by.dataHook('first')).click() - click on the first data hook

Matchers

The Matchers API extends the available matchers:

toBePresent - Checks whether an element is present (exists in the DOM).

expect($('.some-element')).toBePresent();

toBeDisplayed - Checks whether an element is displayed (visible in the DOM).

expect($('.some-element')).toBeDisplayed();

toHaveCountOf - Checks whether the length passes to the function against the value it's invoked with.

expect($('.some-elements').count()).toHaveCountOf(expectedCount);

toHaveText - Checks whether an element contains text.

expect($('.some-element')).toHaveText(expectedText);

toMatchRegex - Checks whether an element's text fits a regex.

expect($('.some-element')).toMatchRegex(expectedPattern);

toMatchMoney - Checks whether an element's text fits rtl money regex.

expect($('.some-element').getText()).toMatchMoney(expectedValue, currencySymbol);

toMatchMoneyWithFraction - Checks whether an element's text fits rtl money regex with fraction.

expect($('.some-element').getText()).toMatchMoneyWithFraction(expectedValue, currencySymbol);

toHaveValue - Checks whether an element's value attribute fits the expectedValue.

expect($('.some-element')).toHaveValue(expectedValue);

toHaveClass - Checks whether an element has a specific class name.

expect($('.some-element')).toHaveClass(className);

toBeDisabled - Checks whether an element is disabled.

expect($('.some-element')).toBeDisabled();

toBeChecked - Checks whether an element checkbox is checked.

expect($('.some-element')).toBeChecked();

toBeValid - Checks whether a form element is valid (using the ng-valid class name).

expect($('.some-element')).toBeValid();

toBeInvalid - Checks whether a form element is invalid (using the ng-invalid class name).

expect($('.some-element')).toBeInvalid();

toBeInvalidRequired - Checks whether a form element is invalid and required (using the ng-invalid-required class name).

expect($('.some-element')).toBeInvalidRequired();

toMatchTranslated - Checks whether an element contains a translation value.

expect($('.some-element')).toMatchTranslated(key, values);

License

The MIT License.

See LICENSE