Selenium WebDriver: Understanding the findElements() Method in Java

The findElements() method in Selenium WebDriver for Java is a key tool for locating, collecting, and interacting with multiple web elements that match a given locator strategy on a web page. This capability is essential for handling collections of elements, such as lists, tables, and groups of buttons or links in web automation.

What Does findElements() Do?

• Purpose: Locates all web elements that match a specified locator and returns them as a list.
• Return Type: List<WebElement>
• No Matches: If no elements meet the criteria, it returns an empty list—it does not throw an exception.
• Usage: Commonly used when the page contains multiple similar items (e.g., links, checkboxes, rows).

Syntax

List<WebElement> elements = driver.findElements(By.<locatorStrategy>("locatorValue"));

• driver: The active WebDriver instance.
• By.<locatorStrategy>: Locator method, such as By.id, By.className, By.xpath, or By.cssSelector.
• “locatorValue”: The value for the chosen strategy.

Complete Code Example

Locate all buttons with the class “btn-primary”:

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;
import java.util.List;

public class FindElementsExample {
    public static void main(String[] args) {
        System.setProperty("webdriver.chrome.driver", "/path/to/chromedriver");
        WebDriver driver = new ChromeDriver();
        
        driver.get("https://www.example.com");

        // Find all elements with class 'btn-primary'
        List<WebElement> buttons = driver.findElements(By.className("btn-primary"));
        System.out.println("Button count: " + buttons.size());
        for(WebElement button : buttons) {
            System.out.println(button.getText());
        }
        
        driver.quit();
    }
}

Workflow:

• All elements matching the criteria are added to the list.
• The size of the list indicates how many matches were found.
• Looping allows access and interaction with each element individually.

Key Behaviors and Best Practices

• Returns Empty List: If no matching elements are found, the returned list has size 0. This makes it easy to check for the absence of elements without handling exceptions.
• Indexing: Returned elements are zero-indexed—e.g., elements.get(0) retrieves the first found element.
• Chainable on WebElements: You can use findElements() on both WebDriver (root page) and individual WebElement (to search within a particular element, such as finding rows inside a table).
• Typical Locator Strategies: Works with all locator types (ID, name, class name, tag name, CSS selector, XPath, link text, partial link text).

Feature	findElements()
Returns	List of all matching elements (may be empty)
Exception on No Match	No (returns empty list)
Usable With	Any locator strategy
Common Use Cases	Lists, tables, groups, multiple checkboxes/radios
Indexing	Yes (zero-based)

Real-World Scenarios

• Retrieve all links in a footer:
  List<WebElement> footerLinks = driver.findElements(By.cssSelector("footer a"));
• Interact with multiple checkboxes:
  Loop through the list and check/uncheck each box as needed.
• Table Rows:
  List<WebElement> rows = driver.findElements(By.xpath("//table/tbody/tr"));

Example: Find Elements Within a Parent

You can search within a section or parent element:

WebElement table = driver.findElement(By.id("my-table"));
List<WebElement> rows = table.findElements(By.tagName("tr"));
for (WebElement row : rows) {
    System.out.println(row.getText());
}

This approach is useful for working within a defined DOM scope.