@hetznercloud/protractor-test-helper

[![npm version](https://badge.fury.io/js/%40hetznercloud%2Fprotractor-test-helper.svg)](https://www.npmjs.com/package/@hetznercloud/protractor-test-helper) [![Build Status](https://travis-ci.com/hetznercloud/protractor-test-helper.svg?branch=master)](http

Usage no npm install needed!

<script type="module">
  import hetznercloudProtractorTestHelper from 'https://cdn.skypack.dev/@hetznercloud/protractor-test-helper';
</script>

README

Protractor Test Helper

npm version Build Status

This library provides functions which help to create robust and reliable end-to-end tests with protractor and reduces the pain of end-to-end tests to a minimum. All provided action helpers perform checks that the element is in the correct state before the actual task is performed.

Features

  • Robust actions like click, sendKeys or hover which wait for their elements before the action is performed
  • Lots of waitfor… functions to avoid sleep
  • Helper to open and close windows, tabs, popups, etc
  • Utilities like the flowLog function, which logs exactly in the moment when it is expected to log: when the previous web driver action was performed, and not when the it block is called.
  • Most of the actions have a retry logic inside, which retries the action 3 (or configurable number of) times before an error is thrown
  • Custom matcher like .toBePresent() or toBeDisplayed();
  • Provides better error messages with more details
  • All functions which interact with elements accept either ElementFinder, Locator or string as target parameter
  • Ready for tests written with async / await (every function returns a promise)
  • Definition files are included for TypeScript

Table of Contents

Example usage

const { click, waitForTextToBe, sendKeys, getText } = require('protractor-test-helper');

describe('readme example', () => {
    // Simple example - better would be a Page Object
    const firstNumber = element(by.model('first'));
    const secondNumber = element(by.model('second'));
    const goButton = element(by.id('gobutton'));
    const latestResult = element(by.binding('latest'));

    beforeEach(() => {
        browser.get('http://juliemr.github.io/protractor-demo/');
    });

    it('should add one and two', () => {
        sendKeys(firstNumber, '1');
        sendKeys(secondNumber, '2');
        click(goButton);

        waitForTextToBe(latestResult, '3');
        expect(getText(latestResult), '3');
    });
});

For more examples please have a look into the test folder.

Installation

npm install @hetznercloud/protractor-test-helper --save-dev

or

yarn add @hetznercloud/protractor-test-helper -D

To use the matcher you have to call the install function in your protractor.config:

exports.config = {
    onPrepare() {
        //...
        require('@hetznercloud/protractor-test-helper/').installMatcher();
    },
};

Contributing

Pull requests are warmly welcome. Minor fixes will be merged as soon as possible. Please ask before you make any significant changes (e.g. implementing new features, refactoring code, etc), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.

Tests

Tests can be started with:

yarn test

After adding new functionality please add new test cases as well. The test app is located under testapp/ and consists of a simple Angular application. You can simply start it with yarn start.

Code Style

Please respect the linting rules and run yarn pretty:write after applying changes to the code. Prettier is an "opinionated code formatter". More information about prettier.

Docs

The readme and docs are autogenerated. After adding or updating functions please run

yarn readme:update

The first part of the readme is stored under _docs/README.base.md. Please do not make changes directly in the README.md file.

License

MIT license

Matchers

expect(ElementFinder | Locator | string).toBeDisplayed();
expect(ElementFinder | Locator | string).toBePresent();

API

Actions

click

click(target: ElementFinder | Locator | string, timeout: number, tryCount: number): Promise‹void›

Waits for an element to be displayed and clickable, and click on it. If the click fails, tryCount retries are performed.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
timeout number DEFAULT_TIMEOUT Timeout in milliseconds to wait for the target
tryCount number DEFAULT_RETRIES Retry counter for the recursion

Returns: Promise‹void›


hover

hover(target: ElementFinder | Locator | string, timeout: number): Promise‹void›

Waits for an element to be displayed and positions the pointer inside that element.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
timeout number DEFAULT_TIMEOUT Timeout in milliseconds to wait for the target

Returns: Promise‹void›


selectOption

selectOption(option: ElementFinder | Locator | string, timeout: number): Promise‹void›

Select an <option>. If the selection fails, 3 retries are performed.

Parameters:

Name Type Default Description
option ElementFinder | Locator | string - Target
timeout number DEFAULT_TIMEOUT Timeout in milliseconds to wait for the target

Returns: Promise‹void›


selectOptionByIndex

selectOptionByIndex(select: ElementFinder | Locator | string, index: number, timeout: number): Promise‹void›

Select an <option> ancestor of a particular <select> element by its index. All options are collected by tagName === 'option', skipping <optgroup> or similar elements. After that the index is selected. If the selection fails, 3 retries are performed.

Parameters:

Name Type Default Description
select ElementFinder | Locator | string - Parent
index number - Index of the option which should be selected
timeout number DEFAULT_TIMEOUT Timeout in milliseconds to wait for the target

Returns: Promise‹void›


selectOptionByText

selectOptionByText(select: ElementFinder | Locator | string, text: string, timeout: number): Promise‹void›

Select an <option> ancestor of a particular <select> element by its content. The option is identified by Protractor's cssContainingText (partial match: selectOptionByText('bar') matches <option>foobar</option> too). If the selection fails, 3 retries are performed.

Parameters:

Name Type Default Description
select ElementFinder | Locator | string - Parent
text string - Text of the option which should be selected
timeout number DEFAULT_TIMEOUT Timeout in milliseconds to wait for the target

Returns: Promise‹void›


sendKeys

sendKeys(target: ElementFinder | Locator | string, value: string, timeout: number, tryCount: number): Promise‹void›

Wait for an <input> element to be displayed, then clear its content, and perform key strokes for the passed value. If sendKeys fails, tryCount retries are performed.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
value string - Input value which should be sent as key inputs
timeout number DEFAULT_TIMEOUT Timeout in milliseconds to wait for the target
tryCount number DEFAULT_RETRIES Retry counter for the recursion

Returns: Promise‹void›

Waits

waitForAttributeMatch

waitForAttributeMatch(target: ElementFinder | Locator | string, attr: string, value: RegExp, timeout: number): Promise‹boolean›

Wait for an element's attribute value to match a regular expression.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
attr string - Attribute name
value RegExp - RegExp which the attribute's value should match
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitForAttributeToBe

waitForAttributeToBe(target: ElementFinder | Locator | string, attr: string, value: string, timeout: number): Promise‹boolean›

Wait for an element's attribute to have the given value.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
attr string - Attribute name
value string - Value which the attribute should have
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitForElementCountToBe

waitForElementCountToBe(target: ElementArrayFinder | Locator | string, expected: number, timeout: number): Promise‹boolean›

Waits that a selector resolves to the expected number of elements. Useful e.g. to verify that the expected number of items have been added to a list.

Parameters:

Name Type Default Description
target ElementArrayFinder | Locator | string - Target selector or ElementArryFinder
expected number - Number of the expected elements
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitForElementCountToBeGreaterThan

waitForElementCountToBeGreaterThan(target: ElementArrayFinder | Locator | string, expected: number, timeout: number): Promise‹boolean›

Waits that a selector resolves to more than the expected count of elements. Useful e.g. to verify that at least some number of items have been added to a list.

Parameters:

Name Type Default Description
target ElementArrayFinder | Locator | string - Target selector or ElementArrayFinder
expected number - Expected number of elements
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitForElementCountToBeLessThan

waitForElementCountToBeLessThan(target: ElementArrayFinder | Locator | string, expected: number, timeout: number): Promise‹boolean›

Waits that a selector resolves to less than the expected count of elements. Useful e.g. to verify that at least some elements have been removed from a list.

Parameters:

Name Type Default Description
target ElementArrayFinder | Locator | string - Target selector or ElementArrayFinder
expected number - Should be less than the expected number of elements
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitForTextMatch

waitForTextMatch(target: ElementFinder | Locator | string, value: RegExp, timeout: number): Promise‹boolean›

Wait for an element's text content to match a regular expression.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - -
value RegExp - The RegExp which the content of the target should match
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitForTextToBe

waitForTextToBe(target: ElementFinder | Locator | string, value: string, timeout: number): Promise‹boolean›

Wait for an element's text content to equal the given value.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
value string - The string we are waiting for
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitForUrlMatch

waitForUrlMatch(value: RegExp, timeout: number): Promise‹boolean›

Wait for the browser's URL to match a regular expression.

Parameters:

Name Type Default Description
value RegExp - RegExp which the URL should match
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitForWindowCount

waitForWindowCount(count: number, timeout: number): Promise‹boolean›

Waits for a window count. Useful e.g. for confirming that a popup window was opened.

Parameters:

Name Type Default Description
count number - Expected number of windows
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitToBeDisplayed

waitToBeDisplayed(target: ElementFinder | Locator | string, timeout: number): Promise‹boolean›

Wait for an element to be displayed. Displayed means that it is part of the DOM and visible.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - -
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitToBeNotDisplayed

waitToBeNotDisplayed(target: ElementFinder | Locator | string, timeout: number): Promise‹boolean›

Wait for an element to be not displayed. An element which is not displayed could still be part of the DOM, but is hidden by a css rule.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitToBeNotPresent

waitToBeNotPresent(target: ElementFinder | Locator | string, timeout: number): Promise‹boolean›

Wait for an element not to be present. Not present means that this element does not exist in the DOM.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - -
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›


waitToBePresent

waitToBePresent(target: ElementFinder | Locator | string, timeout: number): Promise‹boolean›

Wait for an element to be present. Present means the element is part of the DOM, but still might be hidden by CSS rules.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
timeout number DEFAULT_TIMEOUT Timeout in milliseconds

Returns: Promise‹boolean›

Helper

getElementAttributeValue

getElementAttributeValue(target: ElementFinder | Locator | string, attr: string, timeout: number): Promise‹string›

Waits for the element to be present, and resolves to the attribute's value.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
attr string - Attribute name to look for
timeout number DEFAULT_TIMEOUT Timeout in milliseconds to wait for the target

Returns: Promise‹string›


getText

getText(target: ElementFinder | Locator | string, timeout: number, tryCount: number): Promise‹string›

Wait for an element to be displayed, and resolves to the text in that element. If getText fails, tryCount retries are performed.

Parameters:

Name Type Default Description
target ElementFinder | Locator | string - Target element
timeout number DEFAULT_TIMEOUT Timeout in milliseconds to wait for the target
tryCount number DEFAULT_RETRIES Retry counter for the recursion

Returns: Promise‹string›


getWindowHandlesCount

getWindowHandlesCount(): Promise‹number›

Resolves to the current window count. Windows includes windows, tabs, etc.

Returns: Promise‹number›

Window

closeWindow

closeWindow(index: number): Promise‹void›

Closes a browser window, popup, or tab identified by its zero-based index. If two windows are open and the second window is to be closed, the index should be 1.

Parameters:

Name Type Default Description
index number 0 The index of the Window

Returns: Promise‹void›


openUrlInNewTab

openUrlInNewTab(url: string): Promise‹boolean›

Opens the passed URL in a new tab.

Parameters:

Name Type Description
url string The URL to be opened in the window or tab

Returns: Promise‹boolean›


scrollBottom

scrollBottom(): Promise‹void›

Scrolls to the bottom of the window.

Returns: Promise‹void›


scrollTop

scrollTop(): Promise‹void›

Scrolls to the top of the window.

Returns: Promise‹void›

Utils

flowLog

flowLog(message: string): Promise‹void›

Logs a message in the flow of protractor. This means that the log message appears in the correct order as the actions and tests are performed, and not like regular log output at the test initialization.

Parameters:

Name Type Description
message string Text to be logged to the console in the control flow

Returns: Promise‹void›


getElementArrayFinder

getElementArrayFinder(target: ElementArrayFinder | Locator | string): ElementArrayFinder

Constructs an ElementArrayFinder from various target types.

Parameters:

Name Type Description
target ElementArrayFinder | Locator | string Target element

Returns: ElementArrayFinder


getElementFinder

getElementFinder(target: ElementFinder | Locator | string): ElementFinder

Constructs an ElementFinder from various target types.

Parameters:

Name Type Description
target ElementFinder | Locator | string Target element

Returns: ElementFinder


log

log(message: string, ignoreDebug: boolean): void

Logs a message to the console if debugging is enabled.

Parameters:

Name Type Default Description
message string - Text to be logged to the console
ignoreDebug boolean false Force log message to be logged, regardless of debug settings

Returns: void


refresh

refresh(reason: string): Promise‹void›

Performs a page reload and displays a message in the flow log why the reload was necessary.

see flowLog

Parameters:

Name Type Description
reason string Text to be logged to the flow log

Returns: Promise‹void›


sleep

sleep(time: number, message?: string): Promise‹void›

Performs a browser sleep. Normally it should be avoided because of its performance impact, and replaced by one of the waitTo… functions wherever possible. If sleep is still necessary, a reason can be displayed in the flow log.

Parameters:

Name Type Description
time number Time in milliseconds to sleep
message? string Text which explains why the sleep was necessary

Returns: Promise‹void›