🎉 Launch of protractor-helper v4 🎉
Get to know a bit of the history behind protractor-helper and its new version
If you automate or intend to automate tests of web applications with the Protractor framework, protractor-helper will help you on making them reliable. It does that by using the ExpectedConditions class, from Protractor, to ensure that the test scripts will only interact with elements, or run assertions on them, when such elements are in the correct state, like visible, clickable, present, etc.
Automated tests of GUI (graphical user interface) are commonly seen as flaky. They fail when they should not, and so they lose credibility.
A test that fails when there’s nothing wrong with the application under test is what we call a false negative, and these should always be avoided.
Tests that are not-well-thought-through might result in false negatives. For instance, a test that doesn’t wait for a button to be on the screen before clicking on it or a test that doesn’t wait for the transition between one URL to another.
The protractor-helper library was created in the year of 2017, due to an internal need in the company where I worked at the time, to solve this specific problem, but without the complexity of the ExpectedConditions class, and since then it keeps evolving.
What are the most common functionalities of protractor-helper?
Some of the most used functions of protractor-helper are:
helper.click(element)The above function receives an element as an argument and only clicks on it when such an element is visible on the screen and available for clicking.
helper.fillFieldWithText(element, text)The above function receives two arguments, the first is an HTML element, such as a text input field, or a text area, and the second is a string, which will be typed into the field, only when such field is visible.
helper.waitForElementVisibility(element)The above function, as the name suggests, waits for an element to be visible on the page. The element is passed as an argument.
Now, let’s walk through some of its latest versions.
Version 3.7.0
In the beginning, some of the protractor-helper functions, such as click and fillFieldWithText, were called clickWhenClickable and fillFieldWithTextWhenVisible. On version 3.7.0, their successors functions were created to replace them.
These new functions allowed writing shorter lines of code, which helps in code readability.
Version 3.7.8
On version 3.7.8, we announced the functions that would be deprecated because they had a replacement, but also, we decided to remove other two functions that were not in line with the primary purpose of the library, which is helping on writing robust and reliable tests.
The two other functions are the following: getBodyElementFromCurrentBrowserOrBrowserInstance and openNewBrowserInTheSamePage.
Last but not least, we also decided to deprecate the error message argument, that could be optionally passed to alter the default message in case of a failure. This decision was made due to the default messages being already very clear, suggesting exactly why a specific test step has failed. See some examples.
Finally, we arrived at version 4, where the announced functions and arguments that would be deprecated were, in fact, removed. This is why the major version change.
Here’s what you should do if you already use a version previously from v4?
Below are listed the removed functions that have a replacement, therefore, if you use any of the functions described in the left of the below list, replace them by the relative function in the right.
clickWhenClickable - clickfillFieldWithTextWhenVisible - fillFieldWithTextfillInputFieldWithFileWhenPresent - uploadFileIntoInputFieldclearFieldWhenVisible - clearclearFieldWhenVisibleAndFillItWithText - clearAndFillItWithTexttapWhenTappable - tapfillFieldWithTextWhenVisibleAndPressEnter - fillFieldWithTextAndPressEnterscrollToElementWhenVisible - scrollToElement
However, if you use the functions getBodyElementFromCurrentBrowserOrBrowserInstance and/or openNewBrowserInTheSamePage, you will have to replace them by their native Protractor implementation. See the below examples.
Instead of wring:
helper.getBodyElementFromCurrentBrowserOrBrowserInstance()Use:
browser.element(by.css('body')And instead of writing:
helper.openNewBrowserInTheSamePage()Use:
browser.forkNewDriverInstance(true)Finally, if you changed the default message of some function, see the below example to understand what needs to be changed on your code.
Let’s say that the implementation of your waitForElementVisibility function is the following:
helper.waitForElementVisibility(someElement, 5000, 'Element is still visible')Your new implementation should be the following:
helper.waitForElementVisibility(someElement)Acknowledgment
I want to take a moment in this post to thank Paulo Gonçalves, for helping me in maintaining this library, that helps other professionals in the software industry to write robust and reliable automated tests. Thank you very much, Paulo!
And that’s it for today, but if you have any doubt, please leave a comment, and I’ll reply as soon as possible.
👋 See you next time and good testing! ✅
This post was firstly published in Portuguese, and its original version can be seen here.
