node package manager
Don’t reinvent the wheel. Reuse code within your team. Create a free org »

protractor-helpers

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);
  • waitForElementToDisappear - Waits for an element not to be shown.
helpers.waitForElementToDisappear($('.some-element'), timeout);
  • 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