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