# How to investigate flaky browser tests

Start with the failing step, test data and observed outcome. Keep recovery visible instead of treating a retry as proof that nothing was wrong.

## Why it is hard

- Timing, shared state and external services can produce similar symptoms.
- A rerun can change the evidence you needed to investigate.
- A locator failure and a product assertion failure require different fixes.

## Plan the test around an observable outcome

1. Keep the original failure’s artifacts.
2. Check whether the expected account and fixture state existed.
3. Wait for meaningful app state instead of arbitrary time.
4. Assign an owner to the root cause before restoring a trusted merge gate.

## Where Zerocheck fits

1. Inspect the exact test revision, failing step and screenshots in the run detail.
2. Read console errors, failure type and all recorded attempts.
3. Review healing history separately from retry results.
4. Use --fail-on-flaky when the CI policy should reject a flaky blocking test.

## What a retry means in Zerocheck

A transient AI-service error can be retried once in the same browser. If the test then passes it is labeled flaky. Assertion failures are not retried, and the shipped CLI and hosted workflow do not automatically replay a failed test after its browser actions have run.

## Review the expected outcome first

If a test verifies “success” without saying which record or value should exist, a green result may be difficult to interpret. Tighten the expectation and ensure the fixture is stable before investigating target resolution or timing.

## Pitfalls

- Do not retry assertion failures until they pass.
- Do not label every infrastructure error a product bug.
- Do not confuse a healed target with a retried test.

## Frequently asked questions

### Does Zerocheck hide a pass after retry?

No. It remains labeled flaky in the result, CLI and PR reporting.

### Can a harmless layout change heal?

A moved target can be resolved again. A heal is saved only after the full unchanged test passes with independent evidence.

Related: [Flaky Test Triage](https://tryzerocheck.com/use-cases/flaky-test-triage/)

---
Canonical: https://tryzerocheck.com/guides/fix-flaky-tests/
Updated: 2026-09-14