protractor-helper

Protractor helper's library

This library contains helper functions that can be used together with Protractor for creating robust end-to-end tests.

Many of the helper functions on this library uses protractor.ExpectedConditions to ensure that the elements we want to interact with are in the correct state before interacting with them or running expectations on them. This helps on avoiding trying to interact with elements when they are still not ready for it, which helps on avoiding test flakiness.

Available helpers

Below is the list of all available helpers in this library with your respective example:

setTimeout

This method allows to change the timeout duration of all protractor-helper methods called below setTimeout.

The timeoutInMilliseconds default is 5000 milliseconds

If called without passing an argument the timeout will be set to the default one.

An example of using this method is the need to ensure the screen loads within up to XX seconds, due to the request of the product management. This commonly occurs in ecommerce systems on special dates, such as Black Friday.

getBodyElementFromCurrentBrowserOrBrowserInstance

This method returns the body element of the current browser if nothing is passed as argument or the body element of a specific browser instance in case the browser instance is passed as an argument. This second option is useful when working with two browsers interacting with each other, for example.
Example

openNewBrowserInTheSamePage

This method opens a new browser instance in the same page of the main browser.

waitForElementNotToBePresent

This method is the opposite of the previous one, so, it waits for an element not to be present in the DOM.
Example

waitForElementVisibility

This method waits for an element to be visible in the page. Being displayed means not only that the element is present in the DOM, but also that is has a height and width that is greater than 0.
Example

waitForElementNotToBeVisible

This method is the opposite of the previous one, so, it waits for an element not to be visible in the page. By saying not being displayed means that the element may be in the DOM, but not visible.
Example

clickWhenClickable

This method is used to click in an element as soon as it is in a clickable state. This means that the element is visible and enabled for clicking.
Example

Note: this function will be deprecated in favor of the function click.

click

This method is used to click in an element as soon as it is in a clickable state. This means that the element is visible and enabled for clicking.
Example

fillFieldWithTextWhenVisible

This method fills an input field with a text as soon as such field is visible.
Example

Note: this function will be deprecated in favor of the function fillFieldWithText.

fillFieldWithText

This method fills an input field with a text as soon as such field is visible.
Example

fillInputFieldWithFileWhenPresent

This method fills a file input field with a specified file as soon as the file input field is present in the DOM.
Example

Note: this function will be deprecated in favor of the function uploadFileIntoInputField.

uploadFileIntoInputField

This method uploads a file in a file input field as soon as the file input field is present in the DOM.
Example

clearFieldWhenVisible

This method clears a text input field as soon as such field is visible.
Example

Note: this function will be deprecated in favor of the function clear.

clear

This method clears a text input field as soon as such field is visible.
Example

clearFieldWhenVisibleAndFillItWithText

This method clears a text input field as soon as such field is visible, and then it fills it with a text.
Example

Note: this function will be deprecated in favor of the function clearFieldAndFillItWithText.

clearFieldAndFillItWithText

This method clears a text input field as soon as such field is visible, and then it fills it with a text.
Example

tapWhenTappable

This method performs a tap action on a clickable/tappable HTML element as soon as it is in a clickable/tappable state. This method is used when performing web mobile testing in mobile emulators, for example.
Example

Note: this function will be deprecated in favor of the function tap.

tap

This method performs a tap action on a clickable/tappable HTML element as soon as it is in a clickable/tappable state. This method is used when performing web mobile testing in mobile emulators, for example.
Example

waitForTextToBePresentInElement

This method waits for a specific text to be present in a specific HTML element.
Example

waitForTextNotToBePresentInElement

This method is the opposite of the previous one, so, it waits for a specific text not to be present in a specific HTML element.
Example

waitForUrlToBeEqualToExpectedUrl

This method waits for the URL to be equal to an expected URL. Such method is useful when you want to continue performing actions on elements only when in the correct URL.
Example

waitForUrlNotToBeEqualToExpectedUrl

This method waits for the URL not to be equal to an expected URL. Such method is useful when you want to continue performing actions on elements only when not in a specific URL.
Example

waitForUrlToContainString

This method waits for the URL to contain an expected string. Such method is useful when you want to perform verifications based on the current URL.
Example

waitForUrlNotToContainString

This method waits for the URL not to contain an expected string. Such method is useful when you want to perform verifications based on the current URL.
Example

fillFieldWithTextWhenVisibleAndPressEnter

This method fills an input field with a text as soon as such field is visible and then it simulates pressing the ENTER key from the keyboard. This method is useful in cases such as when doing a search and pressing the ENTER key, instead of having to fill the input field and clicking the search button, for example.
Example

Note: this function will be deprecated in favor of the function fillFieldWithTextAndPressEnter.

fillFieldWithTextAndPressEnter

This method fills an input field with a text as soon as such field is visible and then it simulates pressing the ENTER key from the keyboard. This method is useful in cases such as when doing a search and pressing the ENTER key, instead of having to fill the input field and clicking the search button, for example.
Example

scrollToElementWhenVisible

This method is used to scroll up to an element on the page as soon as the element is visible in the DOM.
Example

Note: this function will be deprecated in favor of the function scrollToElement.

scrollToElement

This method is used to scroll up to an element on the page as soon as the element is visible in the DOM.
Example

Using methods that start with 'wait' as test expectations (or test assertions)

Some of the available methods in this library can be used as test expectations, meaning that when using them you don't necessarily need to add an explicit expectation, such as something like this: expect(avatar.isDisplayed()).toBe(true);.

By using the protractor-helper library this could be implicit, like this: protractorHelper.waitForElementVisibility(avatar);. Here, implicit means that if the function waitForElementVisibility(avatar) has passed, it means that the element is visible, in other words, the element is displayed.

Below you can find the list of methods that can be used as expectations:

waitForElementPresence(element)

waitForElementNotToBePresent(element)

waitForElementVisibility(element)

waitForElementNotToBeVisible(element)

waitForTextToBePresentInElement(element, text)

waitForTextNotToBePresentInElement(element, text)

waitForUrlToBeEqualToExpectedUrl(expectedUrl)

waitForUrlNotToBeEqualToExpectedUrl(expectedUrl)

waitForUrlToContainString(string)

waitForUrlNotToContainString(string)

Note: if you use such methods as expectations they will not count as expectations, in a test report, for example, but if they fail a clear message will be shown to ease understanding why the test has failed. In the end, test reports are usually useful in cases where tests have failed and we need to understand why. If all tests are green there is nothing to worry about, at least not if they were well implemented.

Example of a test failure when using such methods as expectations

Let's look how a failure would looks like when using some of this methods as expectations.

Failure when using waitForElementPresence as expectation:

Failed: element with locator 'By(css selector, *[id="foo"])' is not present.

Failure when using waitForElementVisibility as expectation:

Failed: element with locator 'By(css selector, *[id="foo"])' is not visible.

As you can see, the messages are clear and tell you exactly why the test has failed, such as in the previous example, where a specific text ('foo') is not present in a heading element (an element with css selector 'h1').