How to Debug Selenium WebDriver Tests with Breakpoints

A breakpoint pauses a Selenium test at a chosen line so you can inspect the test’s variables, call stack, current command, and browser state. Start the test in your IDE’s debug mode, stop just before the action or assertion that fails, inspect the state, then fix the underlying issue and rerun without relying on the pause to make the test pass.

Breakpoints are diagnostic tools, not synchronization fixes. Selenium identifies poor synchronization as a common source of errors: navigation can finish before JavaScript has made a dynamic element ready. Use an explicit wait for the condition your next command needs, and keep the debugger pause out of the permanent test behavior.

1. Set a breakpoint and start a debug session

1. Open the Selenium test in an IDE that supports your language and test runner.
2. Find the executable line immediately before, or at, the action or assertion under investigation. Place the breakpoint where the inputs and page state are still useful to inspect.
3. Start the test with the IDE’s debug command rather than its normal run command. The exact control depends on the IDE and test runner.
4. When execution pauses, inspect local variables, the call stack, the current test step, and the browser. Step over a WebDriver command to see its result; step into a helper when its implementation may be relevant; resume to observe what happens next.

For example, if a click is followed by an assertion that a menu is visible, pause before the click. Check the locator and current page, step over the click, then inspect whether the menu appeared and whether the assertion is checking the intended state. IntelliJ IDEA documents this breakpoint-and-debug workflow for Selenium; Selenium’s project also lists IDE choices rather than requiring a single debugger.

2. Inspect the failure boundary

First determine which command completed last and which command failed next. At the breakpoint, check:

• Inputs: locator, URL, text, and values passed to the command or assertion.
• Element state: whether the target exists, is visible, and is in the state the next action requires.
• Browsing context: whether the test is on the expected page and, when applicable, in the correct frame or window.
• Timing: whether the page’s JavaScript has completed the change the test expects.
• Execution path: the call stack and helper code that led to the failing line.

A breakpoint can change timing. If a flaky test passes only when paused, treat that as evidence to inspect synchronization. The pause may have given the application time to update; it does not prove the test is fixed.

3. Replace timing guesses with an explicit wait

Selenium’s page-load wait uses a document readiness state, but that does not guarantee that later JavaScript changes or dynamic elements are ready. After navigation or an interaction that reveals content, wait for the specific condition required by the next command, such as presence or visibility.

In Python, a targeted explicit wait looks like this:

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

# Assume driver has been created and navigated to the page.
wait = WebDriverWait(driver, 10)
menu_button = wait.until(
    EC.visibility_of_element_located((By.CSS_SELECTOR, "#menu-button"))
)
menu_button.click()
wait.until(
    EC.visibility_of_element_located((By.CSS_SELECTOR, "#account-menu"))
)

Choose a timeout that fits the application and environment, and make the awaited condition match the operation: presence does not necessarily mean visible or clickable. A fixed sleep can help as a temporary diagnostic experiment to see whether extra time changes a symptom, but it is brittle as a lasting fix because the needed delay can vary.

Selenium cautions against mixing implicit and explicit waits because the resulting elapsed timeout can be unpredictable. Keep the wait strategy understandable, and inspect the condition, timeout, and ignored exceptions when a wait expires.

4. Separate test, application, and driver problems

• Test or locator issue: inspect the selector and the actual element state at the failure boundary. Confirm the test is using the expected page, frame, and values.
• Application timing issue: check whether a JavaScript-driven change or dynamic element is ready. Add an explicit wait for the needed state and rerun without the breakpoint.
• Browser or driver issue: compare the same WebDriver operation in another browser when practical. Different behavior can help determine whether the problem is specific to a browser or driver.
• Insufficient command detail: enable Selenium diagnostic logging. The Selenium logging guide describes Java FINE and Python DEBUG levels for detailed debugging; configuration varies by binding.

For failures that appear only in CI or are hard to reproduce interactively, logs and focused diagnostic output can help show which command ran and where execution diverged. Treat this as practical guidance: an IDE debugger is useful when a local reproduction is available, while unattended runs require evidence that can be collected without pausing.

5. Troubleshooting common breakpoint and Selenium failures

Symptom	Likely cause	What to do
The breakpoint is never reached.	The test was started normally, the wrong test or configuration ran, or execution did not reach that line.	Start the test with the IDE’s debug command, confirm the selected test and configuration, and verify that the breakpoint is on executable code.
The test passes while paused but fails at normal speed.	The pause changes timing and masks a race between the application and the test.	Identify the state the next command needs and wait explicitly for it. Rerun without the debugger.
An element lookup or interaction fails after navigation.	Navigation readiness did not guarantee that a later JavaScript update or dynamic element was ready.	Inspect the page and element at the failure boundary; wait for the required presence, visibility, or other specific condition.
An explicit wait takes longer than expected or times out unpredictably.	Implicit and explicit waits may be combined, or the waited condition does not match the required state.	Use a consistent wait strategy, inspect the condition and timeout, and avoid combining implicit and explicit waits.
The browser appears to show the right state, but the test checks another context.	The active page, window, or frame may differ from the one being inspected.	Check the test’s current context and switch to the intended window or frame before locating or asserting.
Behavior differs between browsers.	A browser or driver difference may be involved, though test timing and application behavior should also be considered.	Compare the same operation across browsers and use Selenium diagnostic logs to inspect command-level details.
The failure occurs only in CI.	An interactive breakpoint cannot reveal state in an unattended run, and the CI environment may expose a timing-sensitive failure.	Collect Selenium logs and focused state diagnostics around the last successful command; reproduce locally if possible, then fix synchronization rather than depending on a pause.

6. Make debugging repeatable and efficient

• Place breakpoints at the boundary where useful state is still available, rather than scattering them through the test.
• Inspect one failing transition at a time: the last completed command, its result, and the next expected state.
• Use step over for routine WebDriver calls and step into when test helpers or application-facing logic need inspection.
• Remove temporary sleeps and diagnostic changes after identifying the cause. Keep a meaningful explicit wait when the application state is asynchronous.
• Rerun the test without the debugger to confirm the fix does not depend on debugger timing.

Or skip the browser setup

If you need a screenshot of the page state while investigating, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request captures a URL as an image or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers say the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.

Sign up free for 1,000 screenshots a month, with no card required.

FAQ

Does a breakpoint pause the browser too?

It pauses the test process at the selected line. Inspect the browser alongside the suspended test to understand the current page state.

Should I leave breakpoints in committed tests?

Use them during local diagnosis, then remove or disable them before relying on unattended test runs.

Can a screenshot tell me why a WebDriver command failed?

A screenshot can show visible page state, but it does not replace the test’s call stack, command logs, or checks of the active window and frame.