How to Debug a failing test in VS Code in Selenium (2026)

TL;DR

To handle a failing Selenium test in VS Code, reproduce the failure, pause on the responsible line, inspect browser and test state, and preserve evidence for CI-only failures. Use Selenium 4 public APIs, explicit waits, precise assertions, isolated test state, and reliable cleanup.

Key Takeaways

• Treat a failing Selenium test in VS Code as a state transition with a clear postcondition.
• Use explicit, bounded synchronization instead of fixed sleeps.
• Verify the business result, not only that WebDriver issued a command.
• Keep test data and artifacts isolated for safe parallel execution.
• Capture diagnostic context without exposing secrets or personal data.
• Run the scenario with CI-equivalent browser and environment settings.

selenium how to debug a failing test in VS Code means more than making WebDriver perform an action. The dependable solution is to reproduce the failure, pause on the responsible line, inspect browser and test state, and preserve evidence for CI-only failures. This guide shows a Java and Selenium 4 approach that remains readable in local runs, headless CI, and remote execution.

The examples use public WebDriver APIs and JUnit 5. Selenium Manager is available through the normal driver constructor, so the examples do not hard-code a driver executable path. Adapt locators and application URLs to your system, but keep the synchronization, evidence, security, and assertion boundaries intact.

TL;DR

• Identify the browser or application state that proves the operation is ready.
• Use a bounded explicit wait, not a fixed sleep.
• Verify the business result, not only the WebDriver command.
• Isolate test data and execution artifacts for parallel safety.
• Capture safe diagnostic context and always clean up.

1. Build a Reproducible Debugging Baseline

Run one test with fixed data and a known browser window before changing code. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

A suite run adds unrelated logs and shared-state failures. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Record the test name, URL, browser, headless mode, and first exception. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. The related guide to Selenium explicit wait patterns provides a useful pattern when this flow has synchronization or design concerns.

What to assert

The same line and exception fail on two consecutive runs. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

2. Configure VS Code for Selenium Java Debugging

Use the Extension Pack for Java and let VS Code discover JUnit tests. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

Attaching to the wrong process makes breakpoints appear hollow. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Open the Maven or Gradle project root, compile it, then use Debug Test above the method. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. The related guide to maintainable page objects provides a useful pattern when this flow has synchronization or design concerns.

What to assert

A solid breakpoint stops in the test JVM. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

3. Use Breakpoints, Watches, and the Call Stack

Stop immediately before the failing WebDriver command and inspect values. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

A breakpoint after the exception never executes. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Watch locator strings, URLs, element state, and data objects while stepping over calls. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. The related guide to Selenium stale element fixes provides a useful pattern when this flow has synchronization or design concerns.

What to assert

The call stack identifies the application helper that issued the command. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

4. Read Selenium Exceptions as Diagnostic Evidence

Treat the exception type, message, selector, and remote stack as evidence. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

Catching Exception hides the command that actually failed. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Separate lookup, wait, action, and assertion so the failing operation is visible. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. Keep the implementation close to the observable requirement so a reviewer can see why each wait and assertion exists.

What to assert

The report names one failed condition instead of a generic workflow. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

5. Debug Timing Without Adding Sleeps

Pause around state transitions and test the exact readiness condition. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

Thread.sleep can conceal races and lengthen every successful run. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Use WebDriverWait with a condition tied to visibility, clickability, URL, or application state. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. Keep the implementation close to the observable requirement so a reviewer can see why each wait and assertion exists.

What to assert

The test passes at normal speed and fails with a useful timeout message. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

6. Capture Screenshots, HTML, Logs, and State

Collect evidence at the point of failure before cleanup closes the browser. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

A screenshot alone misses network, console, frame, and DOM context. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Save screenshot, page source, current URL, title, and selected application identifiers. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. Keep the implementation close to the observable requirement so a reviewer can see why each wait and assertion exists.

What to assert

Artifacts share a test ID and are attached to the failing result. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

7. Investigate CI-Only and Headless Failures

Make local execution match CI dimensions one at a time. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

Assuming headless is identical ignores viewport, fonts, locale, resources, and permissions. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Match browser version, arguments, viewport, timezone, test data, and parallelism. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. Keep the implementation close to the observable requirement so a reviewer can see why each wait and assertion exists.

What to assert

A controlled change reproduces or removes the CI symptom. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

8. Debug Frames, Windows, and Stale Elements

Verify the active browsing context before interacting. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

An element reference becomes invalid after navigation or a component rerender. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Log window handles, switch deliberately, return to default content, and relocate after DOM replacement. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. Keep the implementation close to the observable requirement so a reviewer can see why each wait and assertion exists.

What to assert

The active URL, handle, and frame match the target element. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

9. Create a Repeatable Failure Triage Workflow

Move from symptom to smallest proven cause using one change per experiment. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

Editing locators, waits, and data together destroys causal evidence. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Classify, reproduce, localize, inspect, hypothesize, test, fix, and rerun nearby coverage. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. Keep the implementation close to the observable requirement so a reviewer can see why each wait and assertion exists.

What to assert

The final fix explains every observed artifact. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

10. Selenium How to Debug a Failing Test in VS Code Checklist

Turn successful investigations into a short team checklist. That is the practical center of a failing Selenium test in VS Code. Start by naming the observable state before the action and the state expected afterward. A reliable test does not assume that a click, navigation, or command succeeded. It gathers evidence at the boundary where control moves between the test, browser, application, and operating environment.

Knowledge trapped in one engineer causes repeated diagnosis work. This matters most on CI, where CPU load, filesystem speed, browser policy, viewport, locale, and network routing may differ from a developer laptop. Keep the scenario narrow and make preconditions visible in setup. If the action depends on data, use a known record and log its nonsecret identifier. If it depends on browser state, assert that state before proceeding. These habits make a failed assertion explain the product behavior rather than merely report a timeout.

Implementation approach

Store launch settings, artifact hooks, environment facts, and escalation rules with the project. Prefer a bounded explicit wait over an unbounded retry. Re-locate elements after navigation or a component rerender, and reserve JavaScript execution for cases where it represents the supported behavior rather than a way to bypass the UI. Keep the implementation close to the observable requirement so a reviewer can see why each wait and assertion exists.

What to assert

Another engineer can reproduce the investigation from the failure report. Add a negative or boundary check when it protects a distinct risk. Assertion messages should include expected state, safe actual state, and the step being performed. Do not print tokens, passwords, personal data, or full payloads. On failure, preserve enough context to reproduce the issue, then let cleanup run even if evidence collection itself encounters an error. This produces a test that is diagnostic, reviewable, and safe to run repeatedly.

11. selenium how to debug a failing test in VS Code: Runnable Selenium 4 Java Example

The following example uses current, public Java APIs. Add Selenium Java and JUnit Jupiter to a Maven or Gradle test project, then run it with a locally installed supported browser. The normal driver constructor delegates driver discovery to Selenium Manager. Avoid copying only the central command. Setup, explicit synchronization, assertions, and cleanup are all part of the example's reliability contract.

import java.time.Duration;
import java.nio.file.Files;
import java.nio.file.Path;
import org.junit.jupiter.api.*;
import org.openqa.selenium.*;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ui.*;

class CheckoutDebugTest {
  WebDriver driver;

  @BeforeEach void start() {
    driver = new ChromeDriver(); // Selenium Manager resolves the driver
    driver.manage().window().setSize(new Dimension(1440, 900));
  }

  @Test void completesCheckout() {
    driver.get("https://www.selenium.dev/selenium/web/web-form.html");
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    WebElement input = wait.until(ExpectedConditions.visibilityOfElementLocated(By.name("my-text")));
    input.sendKeys("debug-value"); // Put a breakpoint here and inspect input
    driver.findElement(By.cssSelector("button")).click();
    wait.until(ExpectedConditions.urlContains("submitted-form"));
    Assertions.assertTrue(driver.getTitle().contains("Web form"));
  }

  @AfterEach void stop(TestInfo info) throws Exception {
    if (driver != null) {
      Files.write(Path.of("debug-" + info.getDisplayName().replaceAll("[^a-zA-Z0-9]", "_") + ".png"),
          ((TakesScreenshot) driver).getScreenshotAs(OutputType.BYTES));
      driver.quit();
    }
  }
}

Keep this example small enough to debug. In a production framework, move repeated browser lifecycle and evidence capture into focused fixtures, while keeping the test's business intent visible. Never create a universal helper that catches every exception and returns a boolean, because that destroys the original stack trace and weakens failure diagnosis.

Run the scenario twice locally, then once with the same headless and browser arguments used by CI. A passing run should leave no shared state. A failing run should name the unmet condition and preserve safe evidence. Review maintainable page objects before turning the example into a larger page-object abstraction.

Interview Questions and Answers

A strong interview response explains both the Selenium API and the engineering reason behind it. Use the answers below as models, then add a brief example from your own framework.

Q: Why does a VS Code breakpoint stay hollow?

The source may not be loaded by the test JVM, the project may not be compiled, or the debugger may be attached to another process. Start with Debug Test on the exact JUnit method and confirm that the source matches the compiled class.

Q: What should you inspect first in a Selenium failure?

Inspect the first meaningful Selenium exception, its selector, the current URL, and the operation that issued it. Later errors often result from the first failure and are less useful.

Q: How do you debug a test that passes only with a breakpoint?

Treat that as timing evidence. Replace the accidental pause with an explicit wait for the application condition that the next action requires.

Q: What artifacts help with CI-only failures?

Capture the screenshot, page source, browser console where supported, test logs, browser version, arguments, viewport, and test data identity. Correlate them with a unique test-run ID.

Q: Should a debugger replace logging?

No. A debugger is excellent for a reproducible local failure, while structured logs and artifacts preserve evidence from unattended runs. Strong frameworks support both.

Q: How do you diagnose StaleElementReferenceException?

Find the navigation or rerender that replaced the node. Wait for the new state and locate the element again instead of retaining a WebElement across the transition.

Q: What is the best order for failure triage?

Reproduce, classify, localize the first bad state, form one hypothesis, run one controlled experiment, implement the smallest fix, and rerun related tests.

Common Mistakes

• Debugging the entire suite instead of one deterministic test. Explain what state the test assumes, replace the assumption with an observable condition, and add a focused postcondition. During review, ask whether this mistake could create a false pass, a flaky failure, leaked data, or a result that cannot be diagnosed on CI.
• Putting a breakpoint after the line that throws. Explain what state the test assumes, replace the assumption with an observable condition, and add a focused postcondition. During review, ask whether this mistake could create a false pass, a flaky failure, leaked data, or a result that cannot be diagnosed on CI.
• Adding Thread.sleep as the first response to a race. Explain what state the test assumes, replace the assumption with an observable condition, and add a focused postcondition. During review, ask whether this mistake could create a false pass, a flaky failure, leaked data, or a result that cannot be diagnosed on CI.
• Catching broad exceptions and discarding the original stack trace. Explain what state the test assumes, replace the assumption with an observable condition, and add a focused postcondition. During review, ask whether this mistake could create a false pass, a flaky failure, leaked data, or a result that cannot be diagnosed on CI.
• Closing the browser before failure artifacts are captured. Explain what state the test assumes, replace the assumption with an observable condition, and add a focused postcondition. During review, ask whether this mistake could create a false pass, a flaky failure, leaked data, or a result that cannot be diagnosed on CI.
• Comparing local and CI runs without matching browser arguments and viewport. Explain what state the test assumes, replace the assumption with an observable condition, and add a focused postcondition. During review, ask whether this mistake could create a false pass, a flaky failure, leaked data, or a result that cannot be diagnosed on CI.

Conclusion

The practical answer to selenium how to debug a failing test in VS Code is to reproduce the failure, pause on the responsible line, inspect browser and test state, and preserve evidence for CI-only failures. The WebDriver call is only one part of the solution. Deterministic setup, state-based synchronization, business-focused assertions, secure evidence, and unconditional cleanup are what make the test trustworthy.

Start with one representative happy path, add the most valuable negative or boundary case, and run both under CI-equivalent conditions. Then extract only the mechanics that genuinely repeat. That sequence gives the team maintainable coverage without hiding the behavior that an engineer needs to understand when a test fails.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Debug a failing test in VS Code in Cypress (2026)
• How to Debug a failing test in VS Code in Playwright (2026)
• How to Run a single test in Selenium (2026)
• How to Test a dropdown in Selenium (2026)
• How to Use Selenium DevTools in Selenium 4 in Java (2026)
• How to Add CI to a test framework (2026)