Diagnosing Playwright Auto‑Wait Failures: A Practical Checklist

Recognizable Condition

During test runs you may see ElementNotFound or TimeoutError exceptions when Playwright tries to interact with a selector that seems to exist in the UI. The test passes locally but fails in CI, or it fails intermittently on the same machine. The underlying issue is usually that Playwright’s auto‑waiting mechanism is unable to locate the element before the default timeout expires.

Cause & Diagnostic Table

Cause	What to Look For
Async Render After JS Event	Element appears only after a network response or WebSocket message.
Wrong Frame or Context	Locator is scoped to the wrong frame or root element.
Insufficient Timeout	Page load or animation exceeds Playwright’s default timeout.
Route Transition or Reload	Page navigates away before the element is inserted.
CI Latency or Resource Limits	Network or CPU constraints delay loading.
Visibility Delay	Element exists but is hidden behind a CSS animation.

Ordered Checks

1. Run with Trace
   

   npx playwright test --debug

   Inspect the trace to see when the element is added to the DOM and whether the page navigated or reloaded.

2. Check Network Activity
   

   In the trace, confirm that all required JS, CSS, and WebSocket messages have completed before the element is expected.

3. Verify Frame Context
   

   Use page.frames() to list frames and ensure the locator targets the correct one. Example:

   const frame = page.frame({ name: 'contentFrame' });
   frame.locator('button#submit').click();

4. Test Timeout Tuning
   

   await page.setDefaultTimeout(60000); // 60 seconds
   await page.setDefaultNavigationTimeout(120000); // 2 minutes

   Run the test again. If it passes, the issue is a timeout.

5. Explicit Visibility Wait
   

   await page.waitForSelector('div#modal', { state: 'visible', timeout: 30000 });

   Use this before the action that triggers the element.

6. CI vs Local Comparison
   

   Run the same test locally with the same environment variables used in CI. If it passes locally, review resource limits (CPU, memory) and network speed on the CI runner.

Fixes Tied to Findings

• Async Render
  

  Insert a wait for the network response or WebSocket message before interacting. Example:

  await page.waitForResponse('**/api/data');
  await page.click('button#load');

• Wrong Frame
  

  Scope the locator to the correct frame or use frameLocator:

  await page.frameLocator('iframe#main').getByText('Submit').click();

• Timeout
  

  Increase the default timeout only for the affected test or use page.setDefaultTimeout locally. Avoid global changes unless necessary.

• Route Transition
  

  Use page.waitForNavigation after actions that cause navigation, or chain waitForLoadState to confirm the page is ready.

• CI Latency
  

  Allocate more resources to the CI job, enable caching for dependencies, or use a dedicated runner closer to the network endpoint.

• Visibility Delay
  

  Specify state: 'visible' in waitForSelector or add await expect(locator).toBeVisible() before the action.

Escalation Criteria

If after applying the above fixes the test still fails, consider:

• Consulting the application team to verify that the UI flow hasn’t changed.
• Checking for flaky network or backend endpoints that might intermittently delay responses.
• Reviewing the test runner logs for resource exhaustion or timeouts unrelated to Playwright.

Concrete Example

Scenario: A click on #open-modal triggers a WebSocket message that populates #modal-content. The test fails with TimeoutError: waiting for selector "#modal-content" failed: element not found.

test('opens modal after ws', async ({ page }) => {
  await page.goto('https://app.example.com');
  await page.click('#open-modal');
  await page.waitForSelector('#modal-content', { state: 'visible', timeout: 30000 });
  await expect(page.locator('#modal-content')).toContainText('Success');
});

Diagnostics:

• Run npx playwright test --debug and observe that #modal-content is added only after the WebSocket message completes.
• Verify that page.waitForSelector is set to state: 'visible' to account for the fade‑in animation.
• Ensure the test is not running in a headless mode that disables WebSocket support.

Result: The test passes locally and in CI after adding the explicit visibility wait.

Limitations & Practical Checks

• Increasing timeouts can mask real performance regressions; always measure actual load times with console.time or browser performance APIs.
• Explicit waits should target the most specific selector to avoid false positives.
• Disabling auto‑wait globally (playwright.config.ts timeouts: { ... }) is discouraged because it may hide flaky tests.
• After applying a fix, re‑run the test suite in a single run (not parallel) to confirm deterministic behavior.

Conclusion

Playwright’s auto‑wait is powerful, but it relies on the element being present and in the correct context within the default timeout. By following a systematic diagnostic checklist—trace inspection, network verification, frame validation, timeout tuning, and visibility checks—you can pinpoint the root cause of ElementNotFound or TimeoutError failures and apply targeted fixes. Remember to keep changes minimal and scoped to the affected test to maintain test suite reliability.