Debug ElementClickInterceptedException with Overlays and Hit Testing

ElementClickInterceptedException means Selenium refused to deliver a user-like click because another element owned the click point. The target may be present, displayed, and enabled while a loading mask, cookie panel, sticky header, transition layer, or responsive layout still wins the browser's hit test.

Treat the exception as geometry and readiness evidence. Identify the topmost element at the intended point, determine why it is there, and synchronize on the product condition that removes or relocates it.

Follow the Browser's Click Path

Selenium's element interaction documentation states that the element click command acts at the element's center and reports interception when that point is obscured. This is more specific than saying that an overlay exists somewhere on the page. The important overlay is the one that receives pointer input at the computed point after scrolling.

The common errors guide names overlaps and animations as frequent causes. Add responsive reflow, delayed banners, sticky navigation, modal backdrops, skeleton loaders, and zero-opacity elements that still accept pointer events to the root-cause tree.

Confirm the Intended Target First

Before studying overlays, prove the locator resolved the control the scenario intends to click. Duplicate labels, hidden desktop and mobile variants, stale list rows, or an overly broad CSS selector can point Selenium at a different element. Capture tag name, accessible label, stable test attribute, text, rectangle, and a small DOM excerpt.

If the element is inside a frame or a newly opened window, verify the browsing context. If React replaced the control between lookup and click, the likely outcome is a stale reference, but a replacement elsewhere in the layout can also leave the original point covered. Relocate after the readiness condition rather than retaining an element across a major transition.

Avoid selecting by coordinates as the first repair. Coordinates discard the semantic target and can activate the wrong control when layout changes. They are diagnostic data until the test intentionally exercises a low-level pointer gesture.

Capture the Actual Hit-Test Winner

At failure time, execute a read-only diagnostic that records the target center and calls document.elementFromPoint. The result identifies the topmost element according to the document's hit testing at that instant. Preserve a screenshot in the same failure handler; collecting the data on a later retry may observe a different layout.

Java with browser-side hit-test diagnostics:

@SuppressWarnings("unchecked")
static Map<String, Object> hitTest(WebDriver driver, WebElement target) {
  String script = """
      const r = arguments[0].getBoundingClientRect();
      const x = r.left + r.width / 2;
      const y = r.top + r.height / 2;
      const top = document.elementFromPoint(x, y);
      return {
        x, y,
        target: arguments[0].outerHTML.slice(0, 500),
        top: top ? top.outerHTML.slice(0, 500) : null,
        scrollX: window.scrollX,
        scrollY: window.scrollY,
        viewport: {width: window.innerWidth, height: window.innerHeight}
      };
      """;
  return (Map<String, Object>)
      ((JavascriptExecutor) driver).executeScript(script, target);
}

Redact application data before publishing the artifact. outerHTML can contain names, identifiers, or values. For shadow DOM, the document-level result may be a host; inspect the relevant open shadow root separately when product structure requires it.

Classify the Interceptor by Lifecycle

An interceptor usually belongs to one of four lifecycles. A bounded loading mask should disappear when work completes. A modal or consent panel requires an explicit user decision. A sticky element remains but should not cover the target after correct scrolling. An animation layer is temporary, yet its completion must be represented by stable state rather than guessed duration.

Ownership follows lifecycle. The page component owns its loading signal. The test scenario owns whether to accept a consent choice. The application layout owns sticky-header offsets. The design system owns transition classes and pointer-event policy. A generic Selenium helper cannot infer all four safely.

Record the interceptor's stable selector, position, z-index, pointer-events, visibility, and bounding rectangle. A transparent element with pointer-events: auto can intercept even when a screenshot appears clear. Conversely, a large visual layer with pointer-events: none is not the click owner.

Synchronize on Readiness, Not Invisibility Alone

Waiting for an overlay to become invisible is appropriate only when that overlay is the documented blocker. Prefer the business condition behind it: results loaded, save completed, dialog closed, or route settled. The overlay may be removed before the target finishes moving, and another overlay may replace it.

Java (explicit product readiness):

By busyMask = By.cssSelector("[data-testid='results-busy']");
By resultRow = By.cssSelector("[data-testid='result-row'][data-id='42']");

wait.until(ExpectedConditions.invisibilityOfElementLocated(busyMask));
WebElement row = wait.until(ExpectedConditions.elementToBeClickable(resultRow));
row.click();

This sequence is stronger when the application also exposes a stable state on the results region, such as aria-busy="false". Locate the row after readiness so the click uses current geometry. Keep any retry around this read-and-click sequence bounded; do not loop until an unrelated transient layout happens to cooperate.

Control Viewport and Scroll Geometry

Set an explicit viewport or window size in CI and record it. Responsive breakpoints can replace navigation, add fixed toolbars, or move actions into menus. Font availability and device scale can alter line wrapping and element height. A local maximized window and a fixed headless window are different test environments.

Selenium scrolls elements for interaction, but application headers and nested scroll containers can still cover the center. If a sticky header is valid product behavior, scroll the element into a suitable alignment through a deliberate application helper or browser script, then perform a native Selenium click. Validate that the point is owned by the target before acting.

Do not add a fixed vertical offset without documenting the layout contract. Offsets become stale when header height changes. A robust product may use scroll-margin-top; an automation-specific workaround should be the last option and should still verify hit testing.

Distinguish Movement from Coverage

Animations can cause interception in two ways. A target moves between condition evaluation and click, or a transition layer occupies the point. Capture rectangles over successive diagnostic polls to see which one occurs. The solution may be waiting for a stable target rectangle rather than waiting for a named overlay.

A custom stability condition can compare consecutive rectangles, but choose its polling interval and timeout from the application's transition contract, not arbitrary folklore. Reduced-motion settings can also change code paths. If production honors reduced motion, test both the standard experience and that accessibility preference intentionally instead of enabling it solely to silence failures.

Repeated movement after data has settled may indicate layout shift, late font loading, image sizing, or a rendering loop. Escalate that evidence to the UI owner. Automation is exposing a user interaction risk, not merely suffering from it.

Keep Native Click as the Acceptance Path

JavascriptExecutor can invoke element.click(), but that bypasses the WebDriver pointer-interactability path. It can dispatch behavior even though a real pointer cannot reach the control. Using it as the universal fallback changes what the test proves and can skip focus, pointer movement, or other user-level behavior.

The Actions API is appropriate when the requirement is a specific pointer sequence. Selenium's mouse actions documentation exposes low-level input, but moving to an offset does not repair an overlay that would block a user. Use Actions to test gestures, not to route around product geometry.

Script execution remains useful for read-only diagnostics, controlled scrolling, or a product API that is explicitly not user-facing. Keep those cases named so reviewers can see the altered interaction contract.

Preserve Evidence from the Same Attempt

An interception can vanish milliseconds later. Failure handling should capture the exception message, target and interceptor snippets, rectangles, viewport, scroll position, current URL, screenshot, browser console errors, and relevant application state before any retry or cleanup. On Grid, include session and Node identity because font sets and display configuration may vary by image.

Do not take only a screenshot after the test framework has closed a modal or refreshed the page. Order artifact collection ahead of remedial actions. Store structured geometry as JSON so repeated failures can be compared without manually reading images.

End at a Click a User Could Perform

The correct endpoint is not the absence of an exception. It is a native click delivered to the intended control after the UI has reached a valid interactive state. Prove the locator, inspect the center-point winner, classify the blocker, and wait on its actual lifecycle.

Remove JavaScript-click fallbacks that conceal blocked controls. Stabilize viewport and scrolling, retain same-attempt evidence, and send recurring coverage or motion defects to the owning UI component. Once the target wins the browser hit test for the right reason, the Selenium click becomes both reliable and meaningful.