Welcome to the second post of our new How To…Series. Each month on the first Tuesday of the month, we will post a new blog post to take you through a step-by-step guide on how to address a particular aspect of a tool, platform or device that you might need to address in your testing. The series continues with Alec Siminiuc on difference aspects of Selenium that you might need to cover as part of your testing. This looks at Explicit Wait Selenium WEbdriver.
Read other posts in the series:
How To…Select Elements In Selenium WebDriver Scripts
How To…Take Screen Shots in Selenium
How To…Manage Exceptions In Selenium WebDriver
How To…Execute Javascript In Selenium
If you think you would like to help your fellow testers and want to write a How To… post then get in touch: hello [at] testhuddle.com
———————————————————————————————————————————————–
Explicit Waits in Selenium WebDriver
Test automation scripts should synchronise with the web site every time they interact with website elements.
The synchronisation is done using explicit waits and expected conditions.
Why do we need Explicit Wait?
Lets take the simplest Selenium WebDriver method:
driver.findElement(locator)
How does it work?
findElement() tries finding the element matched by the locator in the browser DOM.
If the element is found in the browser DOM, findElement() returns it.
Otherwise, findElement() fails.
findElement() works well if the website is fast.
But if the website is slow and elements are not in the browser DOM when findElement() is executed, findElement() will fail.
We need a way of interacting with website elements that waits until the website elements are in the browser DOM.
What are Explicit Wait?
An explicit wait object uses the WebDriverWait class.
It gets 2 parameters:
- the driver object
- a timeout
WebDriverWait wait = new WebDriverWait(driver, timeout);
The explicit wait works by waiting until an expected condition is reached.
The expected condition is created using the ExpectedConditions class:
wait.until(ExpectedConditions.condition(parameters));
To explain how an explicit wait works, I will use the following example:
WebDriverWait wait;
wait = new WebDriverWait(driver, 10);
WebElement element;
element=wait.until(ExpectedConditions.elementToBeClickable(locator));
1. the wait object is created using the driver object and a 10 seconds timeout as parameters.
2. the until() method will start a timer.
3. the until() method verifies if the expected condition is met:
element matched by the locator is in the browser DOM and is clickable
4. If the condition is met, the until() method returns the found element;
the explicit wait process finishes successfully
5. If the condition is not met and the timer did not reach yet the timeout value, the process continues from step 3
6. if the condition is not met and the time reached the timeout value, the explicit wait finished with an error
When can we use Explicit Wait?
Explicit waits can be used in the following cases:
1. find single web element
2. find multiple web elements
3. check web page title and url
4. check element’s status
5. interact with frames (not included in this article)
The following expected conditions can be used for finding a web element.
It is recommended that they are used instead driver.findElement().
elementToBeClickable
static ExpectedCondition<WebElement> elementToBeClickable(By locator)
static ExpectedCondition<WebElement> elementToBeClickable(WebElement element)
Defines an expectation for checking that an element is visible and enabled such that you can click it.
Example
The next 2 lines of code search for the element matched by the locator.
If the element can be found in the browser DOM and has the clickable status within 10 seconds, it is returned and saved in a WebElement variable.
The locator can be by xpath, css, id or name locator.
WebDriverWait wait = new WebDriverWait(driver, 10);
WebElement element = wait.until(ExpectedConditions.elementToBeClickable(locator));
presenceOfElementLocated
static ExpectedCondition<WebElement> presenceOfElementLocated(By locator)
Defines an expectation for checking that an element is present on the DOM of a page.
Example
The next 2 lines of code search for the element matched by the locator.
If the element can be found in the browser DOM within 10 seconds, it is returned and saved in a WebElement variable.
The locator can be by xpath, css, id or name locator.
WebDriverWait wait = new WebDriverWait(driver, 10);
WebElement element = wait.until(ExpectedConditions.presenceOfElementLocated(locator));
visibilityOfElementLocated
static ExpectedCondition<WebElement> visibilityOfElementLocated(By locator)
static ExpectedCondition<WebElement> visibilityOf(WebElement element)
Defines an expectation for checking that an element is present on the DOM of a page and visible.
Example
The next 2 lines of code search for the element matched by the locator.
If the element can be found in the browser DOM and is visible within 10 seconds, it is returned and saved in a WebElement variable.
The locator can be by xpath, css, id or name locator.
WebDriverWait wait = new WebDriverWait(driver, 10);
WebElement element = wait.until(ExpectedConditions.visibilityOfElementLocated(locator));
The following expected conditions can be used for finding multiple web elements.
It is recommended to use them instead of driver.findElements().
visibilityOfAllElementsLocatedBy
static ExpectedCondition<List<WebElement>> visibilityOfAllElementsLocatedBy(By locator)
static ExpectedCondition<List<WebElement>> visibilityOfAllElements(List<WebElement> elements)
Defines an expectation for checking that all elements present on the web page that match the locator are visible.
Example
The next 2 lines of code search for all elements matched by the locator.
If element(s) can be found in the browser DOM and is (are) visible within 10 seconds, they are returned and saved in a list of WebElement variables.
The locator can be by xpath, css, id or name locator.
WebDriverWait wait = new WebDriverWait(driver, 10);
List<WebElement> elements = wait.until(ExpectedConditions.visibilityOfAllElementsLocatedBy(locator));
presenceOfAllElementsLocatedBy
static ExpectedCondition<List<WebElement>> presenceOfAllElementsLocatedBy(By locator)
Defines an expectation for checking that there is at least one element present on a web page.
Example
The next 2 lines of code search for all elements matched by the locator.
If element(s) can be found in the browser DOM within 10 seconds, they are returned and saved in a list of WebElement variables.
The locator can be by xpath, css, id or name locator.
WebDriverWait wait = new WebDriverWait(driver, 10);
List<WebElement> elements = wait.until(ExpectedConditions.presenceOfAllElementsLocatedBy(locator));
The following expected conditions can be used for checking the web page title and url.
It is recommended that they are used instead of driver.getTitle() and driver.getCurrentUrl().
titleContains
static ExpectedCondition<java.lang.Boolean> titleContains(java.lang.String title)
An expectation for checking that the title contains a case-sensitive substring
Example
The next 2 lines of code verify if the page title contains a keyword.
If the keyword is included in page title within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.titleContains(keyword)));
titleIs
static ExpectedCondition<java.lang.Boolean> titleIs(java.lang.String title)
Defines an expectation for checking the title of a page.
Example
The next 2 lines of code verify if the page title is equal to a specific value.
If the page title is equal to a specific value within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.titleIs(titleValue)));
urlContains
static ExpectedCondition<java.lang.Boolean> urlContains(java.lang.String fraction)
Defines an expectation for the URL of the current page to contain specific text.
Example
The next 2 lines of code verify if the page url contains a keyword.
If the keyword is included in the page url within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.urlContains(keyword)));
urlToBe
static ExpectedCondition<java.lang.Boolean> urlToBe(java.lang.String url)
An expectation for the URL of the current page to be a specific url.
Example
The next 2 lines of code verify if the page url is equal to a specific value.
If the page url is equal to a specific value within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.urlToBe(urlValue)));
urlMatches
static ExpectedCondition<java.lang.Boolean> urlMatches(java.lang.String regex)
Expectation for the URL to match a specific regular expression
Example
The next 2 lines of code verify if the page url matches a regular expression.
If the page url matches the regular expression within 10 seconds, explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.urlMatches(regularExpression)));
These expected conditions can be used for verifying the element’s status.
They are ideal for being used in assertions.
elementSelectionStateToBe
static ExpectedCondition<java.lang.Boolean> elementSelectionStateToBe(By locator, boolean selected)
static ExpectedCondition<java.lang.Boolean> elementSelectionStateToBe(WebElement element, boolean selected)
Defines an expectation for checking if the given element is selected.
Example
The next 2 lines of code verify if the element is selected.
If the element is selected within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.elementSelectionStateToBe(locator, true)));
elementToBeSelected
static ExpectedCondition<java.lang.Boolean> elementToBeSelected(By locator)
static ExpectedCondition<java.lang.Boolean> elementToBeSelected(WebElement element)
An expectation for checking if the given element is selected.
Example
The next 2 lines of code verify if the element is selected.
If the element is selected within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.elementToBeSelected(locator)));
invisibilityOfElementLocated
static ExpectedCondition<java.lang.Boolean> invisibilityOfElementLocated(By locator)
An expectation for checking that an element is either invisible or not present on the DOM.
Example
The next 2 lines of code verify if the element is invisible.
If the element is invisible within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.invisibilityOfElementLocated(locator)));
invisibilityOfElementWithText
static ExpectedCondition<java.lang.Boolean> invisibilityOfElementWithText(By locator, java.lang.String text)
Defines an expectation for checking that an element with text is either invisible or not present on the DOM.
Example
The next 2 lines of code verify if the element is invisible.
If the element is invisible within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.invisibilityOfElementWithText(locator, text)));
stalenessOf
static ExpectedCondition<java.lang.Boolean> stalenessOf(WebElement element)
Wait until an element is no longer attached to the DOM.
Example
The next 2 lines of code verify if the element is no longer included in the browser DOM.
If the element is no longer included in the DOM within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.stalenessOf(element)));
textToBePresentInElement
static ExpectedCondition<java.lang.Boolean> textToBePresentInElement(WebElement element, java.lang.String text)
static ExpectedCondition<java.lang.Boolean> textToBePresentInElementLocated(By locator, java.lang.String text)
An expectation for checking if the given text is present in the element that matches the given locator.
Example
The next 2 lines of code verify if a keyword is included in an element.
If the keyword is included in the element within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.textToBePresentInElementLocated(locator, keyword)));
textToBePresentInElementValue
static ExpectedCondition<java.lang.Boolean> textToBePresentInElementValue(By locator, java.lang.String text)
static ExpectedCondition<java.lang.Boolean> textToBePresentInElementValue(WebElement element, java.lang.String text)
Defines an expectation for checking if the given text is present in the specified elements value attribute.
Example
The next 2 lines of code verify if a keyword is included in the value attribute of an element.
If the keyword is included in the value attribute of the element within 10 seconds, the explicit wait returns true.
Otherwise, the explicit wait returns false.
WebDriverWait wait = new WebDriverWait(driver, 10);
assertTrue(wait.until(ExpectedConditions.textToBePresentInElementValue(locator, keyword)));
