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

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›

Name		Name	Last commit message	Last commit date
Latest commit History 94 Commits
_docs		_docs
dist		dist
lib		lib
test		test
testapp		testapp
tools		tools
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
angular.json		angular.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
tslint.json		tslint.json
yarn.lock		yarn.lock

License

hetznercloud/protractor-test-helper

Folders and files

Latest commit

History

Repository files navigation

Protractor Test Helper

Table of Contents

Example usage

Installation

Contributing

Tests

Code Style

Docs

License

Matchers

API

Actions

click

hover

selectOption

selectOptionByIndex

selectOptionByText

sendKeys

Waits

waitForAttributeMatch

waitForAttributeToBe

waitForElementCountToBe

waitForElementCountToBeGreaterThan

waitForElementCountToBeLessThan

waitForTextMatch

waitForTextToBe

waitForUrlMatch

waitForWindowCount

waitToBeDisplayed

waitToBeNotDisplayed

waitToBeNotPresent

waitToBePresent

Helper

getElementAttributeValue

getText

getWindowHandlesCount

Window

closeWindow

openUrlInNewTab

scrollBottom

scrollTop

Utils

flowLog

getElementArrayFinder

getElementFinder

log

refresh

sleep

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 6

Languages

Packages