Tutorial Selenium Exceptions
& mastering to handle them✨

Selenium, especially Selenium WebDriver is a still popular open-source test automation framework, that provides test execution across different browsers and environments. It allows testers to write autotests in various programming languages (such as Java, Python, C#, and Ruby) to simulate user interactions with web applications and verify their functionality. Selenium helps reduce manual testing efforts and improves the efficiency of testing processes.

Although discussions about Selenium’s obsolescence are growing within the tester’s community, it remains a strong position as many test frameworks are scripted with it and migrating away is not always beneficial in ROI.

You may interested in:

💫 Journey: Migrating from Selenium to Playwright

During test runs it is common to face unexpected issues, called exceptions. Automation Test Engineers master handling exception. The process of managing them is important. But before proceeding, let’s first explore the term Exception.

What are Selenium exceptions?

Exception is an event that occurs during test execution to reflect the specific error or unexpected state.

Exceptions are more fixable than bugs or errors as they throw logical termination. Sometimes an exception is also considered as a fault, the test running stops and the rest of the tests of the framework do not go ahead.

An Exception can arise from a variety of factors, including:

• Logical errors occur when the code App does not work properly or when improper reasoning leads to unintended outcomes. For instance, it might be an attempt to interact with elements in the wrong order or access to non-existent DOM elements.
• Using outdated or invalid locators in the script (e.g., XPath, CSS selectors) to find elements or they had been changed.
• Timing issues occur when web elements are not loaded or interactable when the script tries to access them, often caused by asynchronous loading.
• Dynamic web element interruptions are caused by unexpected alerts, modals or pop-up elements that appear, disappear, or change attributes dynamically based on user interactions or API responses. Modern web applications often involve them.
• Browser issues occur due to problems with the browser or WebDriver, such as mismatched versions, compatibility issues, crashes or other unexpected browser behavior.
• Environment issues include problems with network instability, slow internet, or server downtime causing elements to fail to load or respond.
• System issues are a lack of system resources, such as running out of memory or experiencing file I/O errors.
• Security or session issues are when web applications face security features such as CAPTCHAs, session timeouts, or restricted access to certain elements.

Selenium provides ways to handle these exceptions gracefully, providing meaningful feedback on crashed tests.

Why is Exception Handling in Selenium Important?

Exception handling is significant because it provides critical information about problems encountered during the execution of automated tests or browser interactions and you can find out what caused the error easily.

Here’s why it matters more detail:

1. Improves test stability. Exception handling ensures that unexpected errors do not cause the entire test script to crash. By managing exceptions gracefully, the script can recover and continue execution.
2. Facilitates debugging. Proper exception handling provides clear error messages and logs, helping testers quickly identify and resolve issues in their scripts.
3. Handles dynamic web elements. Exception handling allows scripts to wait for or retry actions, addressing issues like elements not being loaded yet or interactable.
4. Reduces maintenance effort. Scripts with well-implemented exception handling are easier to maintain, as they are less likely to break due to minor changes in the application under test.
5. Ensures consistent test results. By managing unexpected events, exception handling helps maintain the accuracy of test results, reducing false positives and negatives.
6. Provides recovery scenarios — refreshing pages, reinitializing elements, or taking screenshots for further analysis.
7. Helps to create better test reports. By recording clear information about the exceptions we face, we can measure how stable our applications are and where we can improvements.

In summary, a good exception-handling strategy is essential for making your test automation scripts reliable and test execution smoother. If you do not handle them, they can stop your test too soon and give the wrong results.

⬇️ Look, at how it works in order of script execution:

Statement1;
Statement2;
Statement3;  //Exception occurred at this 3rd line
Statement4;  //This line wont be executed
Statement5;  //This line wont be executed

On the occurrence of a certain exception, you can do a set of actions.

Common methods to handle the exceptions

Programming languages provide several ways to handle exceptions.

Try-Catch Blocks

The most common approach to exception handling is using try-catch blocks. It looks like a first line of defence. The risky code that may cause an exception should be put in a try block. Then comes the catch block to handle issues that might happen while running the code, which means exceptions. This simple mechanism allows the script to keep running or exit well.

The following JavaScript code example without exception handling demonstrates a simple arithmetic operation that attempts to divide a number by zero, which causes an error.

// Without exception handling
let num1 = 10;
let num2 = 0;

let result = num1 / num2; // This results in Infinity
console.log("The result is: " + result);

In this version, we add an exception structure to manage the arithmetic errors gracefully:

// With try-catch structure
try {
    // Code that might throw exceptions
} catch (ExceptionType1 e1) {
    // Handle ExceptionType1
} catch (ExceptionType2 e2) {
    // Handle ExceptionType2
}

// Code example
let num1 = 10;
let num2 = 0;

// Handle division
try {
    let result = num1 / num2;
    if (!isFinite(result)) {
        console.error("Error: Division by zero results in an invalid operation.");
    } else {
        console.log("The result is: " + result);
    }
} catch (error) {
    console.error("An unexpected error occurred during division: " + error.message);
}

Now, let’s include the throw keyword. It is used to explicitly raise an exception from a method. It signals an error in the condition and immediately transfers control to the associated catch block for handling.

let num1 = 10;
let num2 = 0;

try {
    if (num2 === 0) {
        throw new Error("Division by zero is not allowed.");
    }
    let result = num1 / num2;
    console.log("The result is: " + result);
} catch (error) {
    console.error("Error occurred: " + error.message);
}

The finally block in try-catch construction is used to execute code that should run regardless of whether an exception was thrown or not. This is useful for cleanup operations, such as closing files or releasing resources.

try {
    // Code that might throw an exception
} catch (ExceptionType1 e1) {
    // Handle ExceptionType1
} catch (ExceptionType2 e2) {
    // Handle ExceptionType2
} finally {
    // Code that always executes
}

try {
    let num = 0;
    if (num === 0) {
        throw new Error("Division by zero is not allowed.");
    }
    let result = 10 / num;
    console.log("Result is: " + result);
} catch (error) {
    console.error("An error occurred: " + error.message);
} finally {
    console.log("Execution completed. Cleaning up resources if necessary.");
}

Exception Information Methods

To get detailed information about exceptions, you can use additionally the exception information methods:

• .trace() prints the stack trace of the exception, including the exception name and a description, which helps in debugging.
• .stack() exception information method traces the errors origin in the code by adding its specific fragment.
• .name() determine the error type.
• .code()returns a string representation of the exception, including its name and description.
• .message() retrieves the description of the exception, providing more context about what went wrong.

try {
    let num = 0;
    if (num === 0) {
        let error = new Error("Division by zero is not allowed.");
        error.code = 1001; // Adding a custom property
        throw error;
    }
    let result = 10 / num;
    console.log("Result is: " + result);
} catch (error) {
    console.log("Error name: " + error.name);
    console.log("Error message: " + error.message);
    console.log("Error code: " + error.code); // Custom property
    console.log("Stack trace: " + error.stack);
}

Using Page Object Model (POM)

Encapsulate interactions and validations in page objects. This can centralize error-handling logic and make your tests more maintainable.

Types of exceptions commonly encountered in Selenium

Selenium WebDriver has more than just the basic try-catch tool. Its API gives us many methods to handle different exceptions. The table below shows the different types of Exceptions that we commonly face while working with Selenium WebDriver:

* You can find a comprehensive list of Selenium exceptions in the official documentation. Keep in mind that some outdated elements may no longer be supported in Selenium 4, so it’s essential to verify their compatibility

Implicit waits

Implicit waits can help manage situations where elements are not immediately available by setting a default waiting time. This reduces the likelihood of encountering NoSuchElementException when elements are not immediately present.
from selenium import WebDriver

Explicit Waits

Explicit waits allow you to wait for specific conditions to be met before proceeding. This approach can help avoid exceptions related to timing issues.

Validate Pre-Conditions

Perform checks before interacting with elements to avoid exceptions like NoSuchElementException or StaleElementReferenceException.

if driver.find_elements(By.ID, "example"):
    driver.find_element(By.ID, "example").click()
else:
    print("Element not found, skipping action.")

Element State Validation

Check the state of elements (e.g., visibility, interactability) before performing actions to avoid state-related errors.

element = driver.find_element(By.ID, "example")
if element.is_displayed() and element.is_enabled():
    element.click()
else:
    print("Element is not ready for interaction.")

Fallback Mechanisms

Implement alternative workflows or locators if the primary approach fails.

try:
    driver.find_element(By.ID, "primary_locator").click()
except Exception:
    print("Primary locator failed. Trying fallback.")
    driver.find_element(By.XPATH, "//button[text()='Fallback']").click()

Error Recovery

Build recovery logic to reset the browser state or retry the test flow when an error occurs.

try:
    driver.find_element(By.ID, "example").click()
except Exception:
    print("Recovering from error.")
    driver.refresh()  # Refresh the page to recover

Timeout Handling with Custom Wait

Use custom wait logic instead of Selenium’s implicit or explicit waits.

import time

timeout = 10
elapsed = 0

while elapsed < timeout:
    if driver.find_elements(By.ID, "example"):
        driver.find_element(By.ID, "example").click()
        break
    time.sleep(1)
    elapsed += 1
else:
    print("Element not found within timeout.")

Selenium exception handling best practices

By following these best practices, you can reduce flaky tests, improve script stability, and ensure smooth exception handling in Selenium automation framework.

• Maintain browser and WebDriver compatibility. Ensure that the WebDriver version matches the browser version.
• Handle specific exceptions. Catch and handle specific Selenium exceptions (e.g., NoSuchElementException, StaleElementReferenceException) instead of using generic Exception. This ensures better error handling and debugging.
• Use explicit waits to avoid timing issues. Explicit waits help ensure that elements are ready for interaction before actions are performed. Avoid relying solely on .sleep() for synchronization.
• Regularly update locators. Outdated or incorrect locators can lead to exceptions like NoSuchElementException. Ensure locators are updated with DOM changes.
• Use assertions to fail early. Use assertions to validate conditions, ensuring that errors are caught early in the execution flow.
• Use finally block for cleanup resources like closing browser sessions, even when an exception occurs.

Your strategy for effective Selenium exception handling

Effective exception-handling strategy is key to developing robust and reliable test automation framework.

• Handle common conditions without throwing exceptions. Anticipate and address common conditions or errors in your code without relying on exceptions. This helps prevent unnecessary exception handling and keeps your code cleaner.
• Design classes or methods to avoid exceptions. Structure your classes and methods to minimize the likelihood of exceptions. Proper design and validation checks can prevent errors from occurring in the first place.
• Write meaningful error messages. Provide clear and informative error messages in your catch blocks. This helps in diagnosing the problem quickly and understanding the context of the error.
• Create custom exceptions when needed. Define custom exceptions to make error handling more readable and specific to your application’s needs. Custom exceptions can provide more meaningful error messages and enhance code clarity.
• Use proper naming conventions for custom exceptions. Follow consistent naming conventions when creating custom exceptions. This improves code readability and helps in identifying the purpose of the exception easily.
• Differentiate between test case errors and coding errors. Distinguish between errors that occur due to test case failures (e.g., assertion errors) and those caused by coding issues. This helps in isolating and addressing problems more effectively.
• Log exception details. Log meaningful error messages, stack traces, and test data to make debugging easier.

Conclusion

Exception handling is a very crucial part of every Selenium Script. Exceptions in Selenium can not be ignored as they disrupt the normal execution of the test automation framework. As you can see, Automation QA engineers can handle exceptions through various techniques depending on requirements and existing project test design.

This process helps us manage problems. It stops problems from moving up and causing the test script to fail.

Frequently asked questions