Handling Auto Suggestions in Selenium with Java

Handling auto-suggestions (or autocomplete) is a common task when automating web forms, such as search bars, location pickers, or tag inputs. This guide walks you through interacting with dynamic suggestion dropdowns using Selenium WebDriver with Java, covering both clickable and non-clickable suggestions, plus robust waiting strategies.

What You’ll Need

Java Development Kit (JDK) 8 or higher
Maven or Gradle (optional but recommended for dependency management)
Selenium Java library (version 4.x recommended)
WebDriver executable (e.g., ChromeDriver, GeckoDriver) matching your browser version
An IDE like IntelliJ IDEA or Eclipse

Step-by-Step

Set up your project. Create a Maven project and add the Selenium dependency to your pom.xml:

<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.21.0</version>
</dependency>

Or download the JARs manually if not using Maven.

Initialize the WebDriver. Set the system property for your driver and instantiate it. For Chrome:

System.setProperty("webdriver.chrome.driver", "path/to/chromedriver");
WebDriver driver = new ChromeDriver();

Navigate to the target page. Use driver.get("https://example.com") to open the page with the auto-suggest field.
Locate the input field. Find the text box where suggestions appear. Use a unique locator, e.g., driver.findElement(By.id("search")).
Type into the field. Send the text that triggers suggestions. Use sendKeys() to simulate typing:
```
WebElement input = driver.findElement(By.id("search"));
input.sendKeys("New York");
```
For dynamic fields, you may need to clear first: input.clear().

Wait for the suggestion list to appear. Do not use Thread.sleep(); instead, use WebDriverWait with an expected condition. For example, wait for a specific suggestion element to be visible:

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement suggestion = wait.until(ExpectedConditions.visibilityOfElementLocated(
    By.xpath("//ul[@class='suggestions']/li[contains(text(),'New York')]")
));

Select the desired suggestion. There are two main approaches:
- Click the suggestion: If the suggestion is a clickable element (like an <li> or <div>), simply call suggestion.click().
- Press Enter or arrow keys: If suggestions are not clickable or you want to select the first one, send arrow keys and press Enter:
```
input.sendKeys(Keys.ARROW_DOWN);
input.sendKeys(Keys.ENTER);
```
Handle non-clickable suggestions (e.g., custom dropdowns). Sometimes suggestions are rendered as a <div> with text, and clicking may not work because the element is hidden or has an overlay. In that case, use JavaScript to click:
```
JavascriptExecutor js = (JavascriptExecutor) driver;
js.executeScript("arguments[0].click();", suggestion);
```

Verify the selection. After selecting, check that the input field contains the expected value:

String selectedValue = input.getAttribute("value");
if (!selectedValue.equals("New York")) {
    throw new AssertionError("Selection failed");
}

Close the browser. Always quit the driver after tests: driver.quit(); in a finally block or using try-with-resources.

Common Mistakes

Using fixed sleeps: Thread.sleep() makes tests flaky and slow. Always use explicit waits.
Incorrect locators: Suggestion lists are often dynamically generated. Avoid brittle XPath that depends on index; use text or class names.
Clicking before the list is fully loaded: The suggestion may be present in DOM but not visible or clickable. Wait for visibility or clickability.
Not clearing the field: If the field has a default value, clear it before typing to avoid concatenation.
Assuming suggestions are always <li> elements: They can be <div>, <span>, or even a table. Inspect the actual HTML.

Tips

Use ExpectedConditions.elementToBeClickable() instead of just visibilityOfElementLocated() if the element is initially disabled.
Prefer CSS selectors over XPath for better performance and readability.
If suggestions are loaded via AJAX, consider using FluentWait to poll for the element with custom polling intervals.
For multiple suggestions, iterate over the list and select the one matching your criteria using driver.findElements().
Always use relative waits (e.g., wait for the suggestion list container to be visible) rather than waiting for a specific suggestion that may not appear.

Troubleshooting

Problem: Suggestions never appear.
Check if the input field triggers suggestions only after a certain number of characters. Try sending more text. Also verify that the page is fully loaded; use driver.manage().timeouts().implicitlyWait() as a fallback, but prefer explicit waits.

Problem: Element not found exception.
The locator may be wrong. Open the browser’s developer tools (F12) and inspect the suggestion elements. Look for dynamic IDs or classes that change. Use relative XPath like //div[contains(@class,'suggestion')].

Problem: Click does nothing.
The element might be hidden or covered by another element. Try scrolling to it: ((JavascriptExecutor) driver).executeScript("arguments[0].scrollIntoView(true);", suggestion); then click. If that fails, use JavaScript click as described above.

Problem: StaleElementReferenceException.
The DOM has changed after you located the element. Re-locate the element right before interacting with it. For example, move the findElement inside the wait condition.

Problem: Suggestions load too slowly.
Increase the timeout in your WebDriverWait. Also, consider waiting for a specific condition like the suggestion list to have a certain number of items: wait.until(driver -> driver.findElements(By.cssSelector(".suggestion")).size() > 0);

Frequently Asked Questions

Q: Can I handle auto-suggestions without using XPath?
Yes, you can use CSS selectors, link text, or even tag names. For example, By.cssSelector("ul#suggestions li") is often more readable and faster than XPath.

Q: What if the suggestion list is inside an iframe?
You need to switch to the iframe first using driver.switchTo().frame("frameId") before interacting with suggestions. After selecting, switch back to the default content.

Q: How do I handle suggestions that appear as a table?
Treat them like any other elements. Use driver.findElements(By.cssSelector("table#suggestions tr")) to get rows, then click the one containing your text.

Q: Is it possible to select a suggestion without clicking, just by pressing Enter?
Yes, many autocomplete implementations accept the first suggestion when you press Enter. Send Keys.ENTER after typing. However, this may not always select the intended suggestion; it depends on the site’s behavior.

Q: Why does my test pass locally but fail on CI?
Different screen resolutions or browser versions can affect element visibility. Use explicit waits with generous timeouts, and avoid relying on element positions. Also, ensure the correct WebDriver binary is used on CI.

Q: Can I handle suggestions that are not in a dropdown but appear as a list below the input?
Yes, that’s the typical case. The steps are the same: wait for the list to appear, locate the desired item, and click it. The key is to use robust locators and waits.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →