Prompt
How do I troubleshoot flaky browser tests that fail only on dynamic pages?
Latest observation
Flaky browser tests on dynamic pages usually come from timing issues, unstable selectors, or unexpected page state. Here’s a practical way to troubleshoot them.
1) Identify the real failure mode
First, determine whether the test is failing because of:
- Element not found → page not ready yet, selector too strict, content rendered asynchronously
- Element not clickable/interactable → overlay, animation, disabled state, offscreen
- Assertion mismatch → data changed, stale content, race condition
- Timeouts → waits too short, page/network slow, hidden infinite loading
Check:
- browser console errors
- network failures
- screenshots/video on failure
- DOM snapshots or HTML at the moment of failure
2) Prefer stable selectors
Dynamic pages often re-render elements, which breaks brittle selectors.
Use:
data-testid,data-qa,aria-label- semantic roles if your framework supports them
Avoid:
- long CSS chains
- text that changes
- nth-child / positional selectors unless unavoidable
Example:
<button data-testid="save-button">Save</button>
3) Wait for the right condition, not just time
Avoid arbitrary sleeps like wait(2000). Instead wait for:
- element to be visible
- element to be enabled
- specific network request to finish
- loading spinner to disappear
- DOM state to match expected content
Examples:
- “wait for selector”
- “wait until text appears”
- “wait for page load state”
- “wait for API response”
If your framework allows it, use explicit waits tied to app state.
4) Deal with animations and transitions
Animations can cause tests to click too early or miss elements.
Try:
- disabling animations in test mode
- waiting for transition end
- ensuring elements are fully visible before clicking
Common symptoms:
- click intercepted
- element detached from DOM
- intermittent “not clickable at point” errors
5) Check for stale elements / re-renders
Dynamic frameworks often replace DOM nodes after load. If you store an element reference and use it later, it may become stale.
Fix:
- re-query the element right before interacting
- avoid caching DOM elements across re-renders
- structure steps so interaction happens immediately after finding the element
6) Make tests independent
Flakes can happen when tests depend on shared state.
Ensure each test:
- creates its own data
- logs in fresh or resets session state
- cleans up after itself
- doesn’t rely on execution order
7) Reduce environmental variability
Dynamic pages can behave differently in CI vs local due to:
- slower CPU
- different viewport sizes
- headless rendering
- blocked third-party resources
- network latency
Check:
- run headless and headed modes
- match viewport and device scale factor
- mock external APIs where possible
- use deterministic test data
- increase CI timeouts modestly, but don’t use them as the only fix
8) Instrument the test and app
Add logging around:
- when requests start/finish
- when the UI enters loading/success/error states
- timestamps for each step
Useful debugging aids:
- screenshots after each step
- trace recording
- DOM dump on failure
- network HAR
- console logs
9) Reproduce with slow network/CPU
If the bug only appears on dynamic pages, intentionally slow things down:
- throttle network
- add CPU slowdown
- test with larger data sets
This often exposes a race condition or missing wait immediately.
10) Look for hidden async work
The UI may look ready while background tasks still run:
- debounced search
- lazy-loaded components
- delayed hydration
- analytics scripts
- API retries
Wait for the app’s own “ready” signal if possible, such as:
- a global loading flag
- a specific DOM marker
- the final network call completing
11) Use retries carefully
Retries can reduce noise, but they hide real bugs.
Good use:
- temporary mitigation while investigating
- rerunning only the failed step to confirm flakiness
Bad use:
- masking unstable tests indefinitely
If a test passes on retry, treat it as flaky and fix the root cause.
12) Common patterns to fix
- Replace
sleep()with explicit waits - Add
data-testid - Wait for API response or spinner disappearance
- Re-find elements after render changes
- Disable animations in tests
- Make test data deterministic
- Run in the same viewport/locale/timezone as CI
A simple debugging checklist
When a test flakes:
- Capture screenshot/video on failure
- Inspect console and network logs
- Confirm selector stability
- Replace fixed delays with condition-based waits
- Check for re-renders/stale elements
- Compare local vs CI environment
- Reproduce under slower conditions
- Verify test independence
If you want, I can also give you:
- a Playwright-specific troubleshooting guide
- a Cypress-specific one
- or a general checklist for Selenium/WebDriver.