Debug Playwright Click Timeouts Caused by Overlays, Motion, and Re-Renders

A timed-out click is not proof that Playwright failed to wait. It usually means the page never satisfied one of the action's user-facing preconditions within the available budget. Find the last unsatisfied check, then repair the UI contract or the scenario prerequisite that kept it false.

Overlays, moving elements, disabled controls, and rapid replacement can produce similar timeout messages while requiring different fixes. Raising the timeout before classifying the path only makes the same uncertainty more expensive.

Read the timeout as an actionability report

For a click, Playwright waits for one matching element that is visible, stable, receiving events, and enabled. The official actionability guide defines receiving events through hit testing at the action point; another element, often an overlay, can capture that point even when the target is visibly present.

Read the call log from the bottom upward. Repeated messages about interception point to hit testing. Repeated stability checks suggest movement or layout churn. Waiting for enabled identifies an unfinished application condition. Multiple matches belong to locator strictness and should be debugged before any timing change.

Capture evidence before changing timing

Reproduce one failing test with trace recording enabled. The trace aligns the action log with DOM snapshots, screenshots, console entries, and network activity. In CI, retain the trace on failure or first retry and ensure artifact upload runs even when the test command exits nonzero.

Use a trial click during local diagnosis to ask whether the actionability contract can become true without triggering the action. Keep an assertion for the prerequisite so the failure names product state rather than ending as a generic click timeout.

import { expect, test } from '@playwright/test';

test('submits a reviewed transfer', async ({ page }) => {
  await page.goto('/transfers/draft-204');

  const submit = page.getByRole('button', { name: 'Submit transfer' });
  await expect(page.getByTestId('review-status')).toHaveText('Ready');
  await expect(submit).toBeEnabled();
  await submit.click({ trial: true });
  await submit.click();

  await expect(page.getByRole('status')).toHaveText('Transfer submitted');
});

Do not leave every action doubled with a trial click. It is a diagnostic tool and can be useful around unusually risky interactions, but normal click() already performs the same readiness checks before dispatching the event.

Follow the overlay root-cause path

When the log says another element intercepts pointer events, identify that element in the trace snapshot. Common blockers include loading scrims, cookie banners, sticky headers, modal backdrops, toast containers with oversized boxes, and invisible elements that still accept pointer events.

Ask why the blocker exists at that moment. A loading overlay may correctly prevent interaction until a save completes, in which case the test missed a prerequisite. It may also remain mounted after an API error, cover more area than its visuals, or fade to zero opacity while retaining pointer events. Those are product defects, not synchronization problems.

For a one-off local investigation, record the hit target at the center of the intended control. This is evidence only because Playwright may choose a different action point.

const button = page.getByRole('button', { name: 'Confirm order' });
const box = await button.boundingBox();

if (box) {
  const hitTarget = await page.evaluate(({ x, y }) => {
    const element = document.elementFromPoint(x, y);
    return element
      ? {
          tag: element.tagName,
          id: element.id,
          className: String(element.className),
          text: element.textContent?.trim().slice(0, 120),
        }
      : null;
  }, { x: box.x + box.width / 2, y: box.y + box.height / 2 });

  console.log(hitTarget);
}

The durable test should wait for the business condition, such as the order quote becoming final, and optionally assert that the named progress indicator is hidden. It should not delete the overlay through page.evaluate() or inject CSS to make the click pass.

Follow the motion and stability path

Playwright considers an element stable after its bounding box remains unchanged across consecutive animation frames. Persistent transforms, expanding panels, layout shifts from late assets, and a component repeatedly unmounting and mounting can prevent that condition.

First determine whether the motion should end. A drawer transition should have a finite product lifecycle, so wait for its open state or an accessible attribute that represents completion. A continuously animated child should not move the button's own box. If it does, the component layout may need a fixed boundary.

Compare the target's bounding box in trace snapshots before assuming the named animation is responsible. A late banner, image without reserved dimensions, or font swap can move an otherwise static button. The visual motion and the root cause may belong to different components. Fixing layout reservation often improves both user interaction and test stability without adding synchronization code.

Disabling all animations globally can make tests faster but removes coverage of interaction during transitions. Reserve reduced-motion projects or injected animation controls for suites whose contract explicitly excludes motion, such as visual baselines. Keep at least one path that exercises the production transition and its input blocking behavior.

Follow the disabled and re-render path

A disabled target often reflects an upstream requirement: validation, permission loading, inventory confirmation, or an unfinished request. Assert that requirement directly. Waiting only for toBeEnabled() is better than a sleep, but a domain assertion such as "quote status is Ready" gives the failure an owner.

Locators re-resolve against the current DOM, so ordinary component replacement is supported. Trouble begins when replacement oscillates between incompatible states, changes the accessible name, or leaves both generations alive. Check console errors, failed responses, and state markers around the replacement. A test that finds the button by stale text may also be observing the wrong phase of the workflow.

const quoteResponse = page.waitForResponse((response) =>
  response.url().endsWith('/api/quotes/current') && response.request().method() === 'GET',
);

await page.getByRole('button', { name: 'Recalculate' }).click();
await expect(await quoteResponse).toBeOK();
await expect(page.getByTestId('quote-state')).toHaveText('Final');
await page.getByRole('button', { name: 'Accept quote' }).click();

Start the response wait before the triggering action. A late waitForResponse() can miss a fast request and create a second timeout that obscures the original issue.

Resist force and DOM event shortcuts

click({ force: true }) disables nonessential actionability checks, including whether the target receives events. It can be appropriate for a narrow test of programmatic behavior, but it no longer demonstrates that a user can click through the rendered page. dispatchEvent('click') is further removed from pointer behavior.

If force makes the test pass, use that as confirmation of an actionability blocker, then remove it and fix the blocker. Never use force to bypass a consent dialog, modal backdrop, disabled state, or overlapping navigation. That changes the scenario rather than stabilizing it.

Keep timeout boundaries intentional

The test timeout covers the test function, fixture work, and hooks according to their runner boundaries; action and assertion timeouts have their own roles. A longer action timeout can be reasonable for a known slow, user-visible transition, but it should not consume the entire test budget and leave no time for result assertions or cleanup.

Prefer a narrow timeout on the explicit readiness assertion when one operation has a justified service objective. Avoid setting a large global timeout in response to one click. Global increases delay every genuine failure and make capacity problems harder to spot.

Handle CI-only failures operationally

CI may expose slower resources, different viewport behavior, missing feature flags, or a race hidden by local execution. Compare environment inputs before changing code. Open the trace at the timed-out action, inspect the before and after snapshots, read the action log, and correlate unfinished network calls or console exceptions.

Preserve enough evidence for someone who did not run the test. A useful incident bundle includes the trace, screenshot, project name, commit, seed identity, and application logs correlated by request or run ID. Redact secrets from attachments and set retention appropriate to the data under test.

When retries are enabled, compare the first attempt with the retry rather than reviewing only the passing artifact. A retry may start in a clean worker, use a warmer backend, or avoid a one-time banner. Those differences narrow the root cause; they should not turn the original timeout into ordinary success.

Use this closure checklist:

• The call log identifies the last unsatisfied actionability check.
• The trace shows the covering element or unstable target at failure time.
• A named application condition explains when interaction becomes valid.
• The fix does not rely on a sleep, forced click, or injected DOM removal.
• Timeout changes are narrow and backed by expected product behavior.
• The final assertion proves the intended business transition completed.

Close the issue by rerunning the exact failing environment and a stress sample that exercises the transition repeatedly. The goal is not merely a click that stops timing out; it is a page with a clear interaction boundary and a test that proves the boundary before acting.