selectors-and-waits

Instruction file imported from Xellos1010/sdlc-visual-workflow-workspace (.cursor/rules/15-chome-extension/selectors-and-waits.mdc). Copyright stays with the author.

Purpose

Eliminate flaky waits like your failing step “Wait for contact page load (post-navigation phased)” after clicking the first search result.

Rules

1. Phased wait recipe (content side)

   • Phase A: Wait for URL or route token change (e.g., /contacts/ segment).
   • Phase B: Wait for layout anchor (stable container) to attach.
   • Phase C: Wait for feature element (e.g., [data-test-id="fieldSectionWrapperShowAll"]) to be visible + enabled.
   • Phase D: Extra: check for SPA loader gone (common aria-busy=false, or absence of busy indicator).

2. If Phase C times out

   • Confirm not in an iframe; if frames exist, query within the correct frame.
   • If SPA renders in waves, add a MutationObserver for up to 5s to catch lateness.
   • Allow one route-refresh fallback (history.replaceState → same URL) only once.

3. Wait API

   • Add waitForRouteAndSelector({ routePattern: /contacts\/\d+/, selector: '[data-test-id="fieldSectionWrapperShowAll"]', timeoutMs: 30000 }).

4. Idempotent “Show All”

   • Clicking the “Show All” button should check an “expanded” state (aria-expanded or a body class). If already expanded, no-op.

5. Instrumentation

   • Each phase logs phase:start → phase:ok|timeout, emits ms duration, stored in session log for panel playback.

Keep this consistent with the “robust page load detection”/phased approach your README uses for pagination.