StaleElementReferenceException in Selenium

1. Overview

The StaleElementReferenceException is a common error that we encounter while testing web applications using Selenium. When we reference a stale element, Selenium throws the StaleElementReferenceException. An element becomes stale due to a page refresh or DOM update.

In this tutorial, we’ll learn what a StaleElementReferenceException in Selenium is and why it occurs. Then, we’ll look at how we can avoid the exception in our Selenium tests.

2. Strategy to Avoid StaleElementReferenceException

To avoid the StaleElementReferenceException, it is essential to ensure that elements are located and interacted with dynamically rather than storing references to them. This means we should find elements each time we need them rather than keeping them in variables.

In some situations, this approach is not possible, and we need to refresh the element before interacting with it again. So, our solution is to catch the StaleElementReferenceException and perform a retry after refreshing the element. We can do this directly in our test or globally for all tests.

For our tests, we’ll define a couple of constants for our locators:

By LOCATOR_REFRESH = By.xpath("//a[.='click here']");
By LOCATOR_DYNAMIC_CONTENT = By.xpath("(//div[@id='content']//div[@class='large-10 columns'])[1]");

For the setup, we’re using the automated approach using WebDriverManager.

2.1. Generating the StaleElementReferenceException

First, we’ll take a look at a test that ends in a StaleElementReferenceException:

void givenDynamicPage_whenRefreshingAndAccessingSavedElement_thenSERE() {
    driver.navigate().to("https://the-internet.herokuapp.com/dynamic_content?with_content=static");
    final WebElement element = driver.findElement(LOCATOR_DYNAMIC_CONTENT);

    driver.findElement(LOCATOR_REFRESH).click();
    Assertions.assertThrows(StaleElementReferenceException.class, element::getText);
}

This test stores an element and updates the DOM by clicking on the link on that page. When reaccessing the element, which is no longer present, the StaleElementReferenceException is thrown.

2.2. Refresh Element

Let’s use retry logic that refreshes the element before reaccessing it:

boolean retryingFindClick(By locator) {
    boolean result = false;
    int attempts = 0;
    while (attempts < 5) {
       try {
            driver.findElement(locator).click();
            result = true;
            break;
        } catch (StaleElementReferenceException ex) {
            System.out.println(ex.getMessage());
        }
        attempts++;
    }
    return result;
}

Whenever the StaleElementReferenceException occurs, we’ll use the stored locator of the element to locate the element again before performing the click again.

Now, let’s update our test to use the new retry logic:

void givenDynamicPage_whenRefreshingAndAccessingSavedElement_thenHandleSERE() {
    driver.navigate().to("https://the-internet.herokuapp.com/dynamic_content?with_content=static");
    final WebElement element = driver.findElement(LOCATOR_DYNAMIC_CONTENT);

    if (!retryingFindClick(LOCATOR_REFRESH)) {
        Assertions.fail("Element is still stale after 5 attempts");
    }
    Assertions.assertDoesNotThrow(() -> retryingFindGetText(LOCATOR_DYNAMIC_CONTENT));
}

We see that we’ll need to update the test, which is cumbersome if we need to do this for many tests. Fortunately, we can use this logic in a central location without the need to update all our tests.

3. Generic Strategy to Avoid StaleElementReferenceException

We’ll create two new classes for the generic solution: RobustWebDriver and RobustWebElement.

3.1. RobustWebDriver

First, we need to create a new class that implements the WebDriver instance. We’ll write it as a wrapper for the WebDriver. It calls the WebDriver methods, and the methods findElement and findElements will return the RobustWebElement:

class RobustWebDriver implements WebDriver {

    WebDriver originalWebDriver;

    RobustWebDriver(WebDriver webDriver) {
        this.originalWebDriver = webDriver;
    }
...
    @Override
    public List<WebElement> findElements(By by) {
        return originalWebDriver.findElements(by)
                 .stream().map(e -> new RobustWebElement(e, by, this))
                 .collect(Collectors.toList());
    }

    @Override
    public WebElement findElement(By by) {
        return new RobustWebElement(originalWebDriver.findElement(by), by, this);
    }
...
}

3.2. RobustWebElement

The RobustWebElement is a wrapper for WebElement. The class implements the WebElement interface and contains the retry logic:

class RobustWebElement implements WebElement {

    WebElement originalElement;
    RobustWebDriver driver;
    By by;

    int MAX_RETRIES = 10;
    String SERE = "Element is no longer attached to the DOM";

    RobustWebElement(WebElement element, By by, RobustWebDriver driver) {
        originalElement = element;
        by = by;
        driver = driver;
    }
...
}

We must implement each method of the WebElement interface to perform the refresh of the element whenever a StaleElementReferenceException is thrown. For this, let’s introduce some helper methods that contain the refresh logic. We’ll call them from these overridden methods.

We can make use of functional interfaces and create a helper class to call the various methods of the WebElement:

class WebElementUtils {

    private WebElementUtils(){
    }

    static void callMethod(WebElement element, Consumer<WebElement> method) {
        method.accept(element);
    }

    static <U> void callMethod(WebElement element, BiConsumer<WebElement, U> method, U parameter) {
        method.accept(element, parameter);
    }

    static <T> T callMethodWithReturn(WebElement element, Function<WebElement, T> method) {
        return method.apply(element);
    }

    static <T, U> T callMethodWithReturn(WebElement element, BiFunction<WebElement, U, T> method, U parameter) {
        return method.apply(element, parameter);
    }
}

In WebElement, we implement four methods that contain the refresh logic and call the previously introduced WebElementUtils:

void executeMethodWithRetries(Consumer<WebElement> method) { ... }

<T> T executeMethodWithRetries(Function<WebElement, T> method) { ... }

<U> void executeMethodWithRetriesVoid(BiConsumer<WebElement, U> method, U parameter) { ... }

<T, U> T executeMethodWithRetries(BiFunction<WebElement, U, T> method, U parameter) { ... }

The click method will look like:

@Override
public void click() {
    executeMethodWithRetries(WebElement::click);
}

All we need to change for our tests now is the WebDriver instance:

driver = new RobustWebDriver(new ChromeDriver(options));

Everything else can stay the same, and the StaleElementReferenceException should not occur anymore.

4. Conclusion

In this tutorial, we learned that a StaleElementReferenceException could occur when accessing elements after the DOM has changed and the element has not been refreshed. We introduced retry logic in our tests to refresh the element whenever a StaleElementReferenceException occurs.