Some years ago, at a conference, I announced that I released a Selenium based library that contained useful wait-based methods for test automation. After a while I archived that project as I did not find time to work on it too much. Well, now, years later, having gathered new ideas, having a refined vision of what that library should be, and with some fresh energy, I am releasing the, let’s say, V2 version of it. In fact it is a brand new library, bigger and better, and it’s name is: waiter2.

I wanted to specify the ‘2’ in the name to highlight that this is based on the original idea (‘thewaiter’) but it is an improved concept. I kept the ‘waiter’ name as the library contains mostly methods that use Selenium’s WebDriverWait mechanism to ensure reliability in tests. It is a Maven based Java project with a Selenium dependency.

The What

I will be making several small releases that will contain the new methods I am interested in, instead of a single large release. I will track progress of that here, on the blog. Each set of new methods released will have an associated blog post where I will describe what is new, and how to use the newly released methods. I will also specify the library version in which a feature will be available. Additionally, the code will be well documented through Javadoc.

So what functionality will I cover with the new methods? Well, you will have the possibility to click on items, work with checkboxes or dropdowns, read element texts or attribute values, work with iframes or multiple windows. Basically whatever I will consider useful, I will add to the library.

Importing into your project

The library will be available for download from the Maven Repository website, at: https://mvnrepository.com/artifact/com.imalittletester/waiter2. It is recommended to always use the latest available version, since it always contains the most features. Add the dependency as it is shown in mvnrepository to your project’s pom.xml file, in the <dependencies> section. E.g.:

<dependency>
    <groupId>com.imalittletester</groupId>
    <artifactId>waiter2</artifactId>
    <version>LATEST-VERSION</version>
</dependency>

This library has as dependency the latest released version of Selenium, which means you don’t need to separately import it. However if you want to manage which Selenium version is imported into your project, you will need to exclude it from the ‘waiter2’ dependency, using an ‘exclusions’ section.

Library contents

There is only one class in the library, called Waiter, in the main -> Java -> utils package. It contains a field, named ‘driver’, and a constructor. It takes the driver instance from a test that initializes the Waiter class and sets it to the Waiter class field. This way you can call all methods from the Waiter class without having to pass the driver instance to each method. The driver instance is used inside the wait methods.

Most of the methods I implemented in the library use the WebDriverWait functionality. Initially, a WebDriverWait variable is created, to define up to how many seconds to wait for the condition specified in the method to happen. Then, the condition is defined. Every half a second the condition is retried, until it is fulfilled successfully, or the timeout has elapsed.

In the same Waiter class you can find a few constant values, whose names contain ‘TIMEOUT’. These are used either inside the methods to set for how long a method waits for a condition to be true, or they can be used by you in tests when calling methods that take a timeout value as a parameter. Each wait method comes in 2 variants: one without a timeout parameter and one with a parameter which specifies a timeout value. The TIMEOUT constants are ints as follows: TINY_TIMEOUT of 10 (corresponding to 10 seconds when passed as parameter to wait methods), TIMEOUT of 30 (the default value unless you provide a timeout parameter), MEDIUM_TIMEOUT of 60 and LONG_TIMEOUT of 120. I did not provide larger numbers, since waiting for more than 2 minutes for any UI event is simply too much.

When it comes to methods that require page elements to be specified as parameters, these also come in 2 flavours: methods that take a WebElement specified through a @FindBy annotation, and the corresponding methods that take a By item.

The methods are written so that if there is a failure due to a condition not being met within the timeout period, instead of a TimeoutException you will get a RunTimeException, with a concise message regarding the failure. This makes it easier and faster to figure out, by looking at a test failure, why the test failed.

The GitHub location of the library is: https://github.com/iamalittletester/waiter2.

Test setup

In order to call the methods from the ‘waiter2’ library, I recommend having a dedicated variable in the test class. I would call it ‘waiter’. In order to initialize the Waiter class (from the ‘waiter2’ library), a driver instance needs to exist. It needs to be passed as parameter to the constructor of the Waiter class. My preferred setup would include initializing the driver instance in the @BeforeAll method (or @BeforeClass, depending on whether you use JUnit5 or TestNG), then initializing the ‘waiter’ variable:

waiter = new Waiter(driver); 

In a nutshell, this is what the ‘waiter2’ library is about. In the next posts I will discuss the methods I implemented in it, and how to use them, so stay tuned!