Fix Failing E2E Tests by Watching the Real Browser

## Define What Success Looks Like in the Browser Before Testing Before running an end-to-end test, translate the requested behavior into conditions that can be observed in the real browser. Record the starting URL or route, required account or fixture state, viewport when relevant, user actions, and the exact visible result that constitutes success. Include accessibility state, navigation, persisted state, and network-backed content when they are part of the behavior. - Prefer stable user-facing roles, labels, and dedicated test identifiers over styling classes or DOM position. - Distinguish the test runner interface from the application under test; evidence from one does not automatically describe the other. - Define both positive evidence, such as a visible confirmation or changed value, and negative evidence, such as the absence of an error banner. - State timing expectations in terms of an observable readiness condition, not an arbitrary delay. Do not weaken an assertion merely to make the test pass. If the expected behavior is ambiguous, stop and clarify the acceptance contract before changing test or product code. ## Run the Test in a Real Browser and Save Screenshots and Logs Launch the narrowest relevant E2E scenario in an actual supported browser using the normal application path. Keep configuration, fixture data, authentication state, viewport, and feature flags explicit enough that the run can be repeated. If a headed or debug mode is available, use it when visual state or browser interaction matters. On failure, capture evidence before editing anything: - the failed scenario and exact assertion or command; - a screenshot or snapshot of the browser at failure; - the application DOM around the target element, including accessible name and state; - relevant browser console errors and failed or unexpected network requests; - the current URL, redirects, loading indicators, and application-visible error messages; - timestamps or run identifiers needed to correlate server logs when available. Use targeted inspection rather than dumping unrelated state. Reproduce once under the same conditions when needed to distinguish a stable failure from a transient one, but do not begin an unbounded retry loop. ## Sort the Failure Into a Test, Code, or Environment Cause Classify the observed failure as a test cause, implementation cause, or environment cause. The classification must be supported by browser evidence and, when necessary, the smallest relevant source or log inspection. - Test cause: the product behaves according to the acceptance contract, but the test uses a stale selector, incorrect assertion, invalid fixture, wrong sequence, or inadequate readiness condition. - Implementation cause: the user-visible behavior violates the acceptance contract, such as a control not responding, incorrect state or navigation, an accessibility regression, or a failed application request caused by product code. - Environment cause: the test and implementation may be correct, but a prerequisite is missing or unhealthy, such as an unavailable service, invalid credentials, incompatible browser, missing seed data, wrong configuration, or exhausted resource. When evidence is mixed, write competing hypotheses and run one discriminating check at a time. Do not label every timeout as a test problem, and do not change product code solely because a test failed. Keep the classification provisional until the evidence rules out the closest alternatives. ## Make the Smallest Fix Without Weakening Assertions Choose the correction that addresses the classified cause without broad refactoring. Preserve the acceptance contract and existing user behavior outside the failing path. - For a test cause, update only the selector, assertion, fixture, action sequence, or readiness condition that contradicts the observed browser state. - For an implementation cause, add or retain a failing regression test when practical, then change the narrowest product logic needed to restore the specified behavior. - For an environment cause, repair or document the missing prerequisite; do not hide it with longer waits, disabled assertions, or unconditional retries. - Prefer deterministic signals such as visible readiness, completed requests, or stable state over fixed sleeps. - Keep testability changes user-neutral: add stable identifiers or accessible labels without coupling tests to incidental layout. Before editing protected, generated, production, destructive, or credential-bearing resources, stop and obtain the required authorization. Never expose secrets in tests, logs, screenshots, fixtures, or reports. ## Rerun the Same Scenario and Stop After Repeated Failures After the correction, rerun the exact failing scenario with the same browser conditions and acceptance contract. A pass counts only when the browser visibly reaches the defined success state and the runner reports no hidden failure. Confirm that console and network evidence no longer shows the causal error when those signals were part of the diagnosis. Then run the smallest directly affected regression scope: the surrounding scenario, feature file, or closely coupled test group. Do not expand to an unrelated full suite unless the change has broad impact or the user explicitly requests it. If the rerun fails differently, return to evidence capture and classification rather than stacking speculative edits. Limit repeated attempts. After two ineffective corrections using the same approach, reassess the diagnosis and choose a different discriminating check. After three consecutive failures with no new evidence, stop and report the blocker instead of continuing to mutate the codebase. ## Report Pass, Fail, or Blocked First, With the Evidence Stop successfully only when the original browser-observable acceptance contract passes, the directly affected regression scope passes, and no relevant causal error remains. Also stop when progress requires missing authority, credentials, unavailable infrastructure, destructive action, or a product decision that cannot be inferred safely. Report the outcome with enough evidence for another person to verify it: - the scenario and browser conditions used; - the observed failure and its classification; - the evidence that supported the classification; - the minimal change made, or the unresolved prerequisite; - the exact reruns performed and their results; - remaining risk, skipped broader checks, and the next required action. Lead with pass, fail, or blocked. Do not claim completion from code inspection alone, from a passing unit test, or from a simulated DOM when the success condition depends on a real browser.