Protractor Test Helper

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
• Installation
• Contributing
• License
• Matchers
• API

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 element | 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 element | 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 element | 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›