npm package: @hetznercloud/protractor-test-helper
Description: [![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
Latest version: 1.1.1

# 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)](https://travis-ci.com/hetznercloud/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`](https://github.com/angular/protractor/blob/master/docs/async-await.md) (every function returns a promise)
* Definition files are included for `TypeScript`

## Table of Contents
* [Example usage](#example)
* [Installation](#installation)
* [Contributing](#contributing)
* [License](#license)
* [Matchers](#matchers)
* [API](#api)

<a id="example"></a>
## Example usage
```javascript
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.

<a id="installation"></a>
## Installation
```bash
npm install @hetznercloud/protractor-test-helper --save-dev
```

or

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

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

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

<a id="contributing"></a>
## 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:

```bash
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](https://prettier.io/).

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

```bash
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.

<a id="license"></a>
## License
MIT license

<a id="matchers"></a>

## Matchers
```js
expect(ElementFinder | Locator | string).toBeDisplayed();
expect(ElementFinder | Locator | string).toBePresent();
```

<a id="api"></a>
## 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; string | - | Target <option> 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 &#124; Locator &#124; string | - | Parent <select> 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 &#124; Locator &#124; string | - | Parent <select> 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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 &#124; Locator &#124; 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›*