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
• 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
• 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

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

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:

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:

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:

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:

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:

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:

Returns: Promise<void>

Waits

waitForAttributeMatch

▸ waitForAttributeMatch(target: * ElementFinder | Locator | string*, attr: string, value: RegExp, timeout?: number): Promise<Promise<boolean>>

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

Parameters:

Returns: Promise<Promise<boolean>>

waitForAttributeToBe

▸ waitForAttributeToBe(target: * ElementFinder | Locator | string*, attr: string, value: string, timeout?: number): Promise<Promise<boolean>>

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

Parameters:

Returns: Promise<Promise<boolean>>

waitForElementCountToBe

▸ waitForElementCountToBe(target: * ElementArrayFinder | Locator | string*, expected: number, timeout?: number): Promise<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:

Returns: Promise<Promise<boolean>>

waitForElementCountToBeGreaterThan

▸ waitForElementCountToBeGreaterThan(target: * ElementArrayFinder | Locator | string*, expected: number, timeout?: number): Promise<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:

Returns: Promise<Promise<boolean>>

waitForElementCountToBeLessThan

▸ waitForElementCountToBeLessThan(target: * ElementArrayFinder | Locator | string*, expected: number, timeout?: number): Promise<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:

Returns: Promise<Promise<boolean>>

waitForTextMatch

▸ waitForTextMatch(target: * ElementFinder | Locator | string*, value: RegExp, timeout?: number): Promise<Promise<boolean>>

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

Parameters:

Returns: Promise<Promise<boolean>>

waitForTextToBe

▸ waitForTextToBe(target: * ElementFinder | Locator | string*, value: string, timeout?: number): Promise<Promise<boolean>>

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

Parameters:

Returns: Promise<Promise<boolean>>

waitForUrlMatch

▸ waitForUrlMatch(value: RegExp, timeout?: number): Promise<Promise<boolean>>

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

Parameters:

Returns: Promise<Promise<boolean>>

waitForWindowCount

▸ waitForWindowCount(count: number, timeout?: number): Promise<Promise<boolean>>

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

Parameters:

Returns: Promise<Promise<boolean>>

waitToBeDisplayed

▸ waitToBeDisplayed(target: * ElementFinder | Locator | string*, timeout?: number): Promise<Promise<boolean>>

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

Parameters:

Returns: Promise<Promise<boolean>>

waitToBeNotDisplayed

▸ waitToBeNotDisplayed(target: * ElementFinder | Locator | string*, timeout?: number): Promise<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:

Returns: Promise<Promise<boolean>>

waitToBeNotPresent

▸ waitToBeNotPresent(target: * ElementFinder | Locator | string*, timeout?: number): Promise<Promise<boolean>>

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

Parameters:

Returns: Promise<Promise<boolean>>

waitToBePresent

▸ waitToBePresent(target: * ElementFinder | Locator | string*, timeout?: number): Promise<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:

Returns: Promise<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:

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:

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:

Returns: Promise<void>

openUrlInNewTab

▸ openUrlInNewTab(url: string): Promise<Promise<boolean>>

Opens the passed URL in a new tab.

Parameters:

Returns: Promise<Promise<boolean>>

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:

Returns: Promise<void>

getElementArrayFinder

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

Constructs an ElementArrayFinder from various target types.

Parameters:

Returns: ElementArrayFinder

getElementFinder

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

Constructs an ElementFinder from various target types.

Parameters:

Returns: ElementFinder

log

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

Logs a message to the console if debugging is enabled.

Parameters:

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:

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:

Returns: Promise<void>