UI States & Dynamic Behavior
Run 35 test cases across 4 parallel agents covering loading states, empty/error states, overlays, and animations.
Setup
URL="${ARGUMENTS:-http://localhost:3000}"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
OUTDIR="test-results/test-states/$TIMESTAMP"
mkdir -p "$OUTDIR/screenshots" "$OUTDIR/snapshots" "$OUTDIR/traces"
Before running, verify prerequisites per references/prerequisites.md.
Parallel Execution — 4 Subagents
Agent 1: Loading (-s=states-loading)
Tests loading, skeleton, and transition states.
playwright-cli -s=states-loading open "$URL"
playwright-cli -s=states-loading tracing-start
Test Cases:
| TC |
Test |
How to Check |
| TC-ST1 |
Loading spinner appears during async ops |
run-code to intercept network requests (delay responses), check for spinner/loading indicator |
| TC-ST2 |
Skeleton screens render before data loads |
run-code to intercept API calls (delay response), check for skeleton CSS (animated pulse/shimmer) |
| TC-ST3 |
No FOUC (Flash of Unstyled Content) |
run-code to observe page load, check if unstyled flash occurs (watch for style recalculation) |
| TC-ST4 |
No layout shift when content loads |
run-code to measure CLS during page load via PerformanceObserver |
| TC-ST5 |
Progressive loading — above-fold first |
run-code to check if above-fold images/content load before below-fold |
| TC-ST6 |
Optimistic UI — updates before server response |
run-code to intercept a mutation request (delay it), check if UI updates immediately |
| TC-ST7 |
Loading states on buttons (prevent double-click) |
Click a submit button, check if it shows loading state / becomes disabled |
playwright-cli -s=states-loading tracing-stop
playwright-cli -s=states-loading close
Agent 2: Empty/Error (-s=states-empty)
Tests empty states, error states, and edge cases.
playwright-cli -s=states-empty open "$URL"
playwright-cli -s=states-empty tracing-start
Test Cases:
| TC |
Test |
How to Check |
| TC-ST8 |
Empty state shown for empty lists/tables |
run-code to mock API returning empty array, check for empty state UI |
| TC-ST9 |
Empty state has helpful CTA |
When empty state shown, check for action button/link (e.g., "Add your first item") |
| TC-ST10 |
404 page exists and is helpful |
Navigate to $URL/nonexistent-page-xyz-404, verify custom 404 page with navigation back |
| TC-ST11 |
500 error page exists (no stack trace) |
run-code to mock API returning 500, check error page doesn't show stack trace |
| TC-ST12 |
Network error state (offline/timeout) |
run-code to set page offline mode, trigger action, check for error UI |
| TC-ST13 |
Permission denied state |
run-code to mock API returning 403, check for appropriate UI |
| TC-ST14 |
Session expired state + redirect |
run-code to mock API returning 401, check for redirect to login or session expired message |
| TC-ST15 |
Partial failure — some items load, some don't |
run-code to mock mixed success/failure responses, verify partial UI renders |
playwright-cli -s=states-empty tracing-stop
playwright-cli -s=states-empty close
Agent 3: Overlays (-s=states-overlay)
Tests modals, toasts, tooltips, and dropdowns.
playwright-cli -s=states-overlay open "$URL"
playwright-cli -s=states-overlay tracing-start
playwright-cli -s=states-overlay snapshot --filename="$OUTDIR/snapshots/overlay-initial.yaml"
Test Cases:
| TC |
Test |
How to Check |
| TC-ST16 |
Modal opens/closes correctly |
Find and click modal trigger, verify modal appears. Click close, verify dismissed |
| TC-ST17 |
Modal traps focus (Tab cycles within) |
Open modal, Tab repeatedly, verify focus stays within modal via run-code checking activeElement |
| TC-ST18 |
Modal closes on Escape |
Open modal, press Escape, verify modal dismissed |
| TC-ST19 |
Modal closes on backdrop click |
Open modal, click outside modal content area, verify dismissed |
| TC-ST20 |
Body scroll locked when modal open |
Open modal, run-code to check document.body.style.overflow is hidden |
| TC-ST21 |
Multiple modals stack correctly |
If multiple modals possible: open two, verify z-index stacking, top modal is interactive |
| TC-ST22 |
Toast/notification appears + auto-dismisses |
Trigger toast (e.g., form submit), verify it appears then disappears after timeout |
| TC-ST23 |
Multiple toasts stack (don't overlap) |
Trigger multiple toasts, verify they stack vertically without overlapping |
| TC-ST24 |
Tooltip shows on hover + keyboard focus |
hover over tooltip trigger, verify tooltip appears. Tab to it, verify also appears |
| TC-ST25 |
Dropdown closes on outside click |
Open dropdown, click outside it, verify it closes |
| TC-ST26 |
Dropdown closes on Escape |
Open dropdown, press Escape, verify it closes |
| TC-ST27 |
Context menu doesn't go off-screen |
run-code to find context menus/dropdowns near edges, verify they reposition to stay in viewport |
playwright-cli -s=states-overlay tracing-stop
playwright-cli -s=states-overlay close
Agent 4: Animation (-s=states-animation)
Tests animations, transitions, and motion.
playwright-cli -s=states-animation open "$URL"
playwright-cli -s=states-animation tracing-start
Test Cases:
| TC |
Test |
How to Check |
| TC-ST28 |
Animations are smooth (no jank) |
run-code with requestAnimationFrame to measure frame timing, flag >16ms gaps |
| TC-ST29 |
prefers-reduced-motion disables animations |
run-code: page.emulateMedia({reducedMotion:'reduce'}), verify animations disabled via computed transition/animation styles |
| TC-ST30 |
Transitions complete (not stuck mid-animation) |
run-code to observe transition elements, verify they reach final state |
| TC-ST31 |
Hover effects work |
hover over interactive elements, run-code to check style changes (color, background, transform) |
| TC-ST32 |
Active/pressed states visible on buttons |
run-code to simulate mousedown on buttons, check for active state styles |
| TC-ST33 |
Scroll-triggered animations fire |
run-code to scroll page, check if animation classes are added to elements entering viewport |
| TC-ST34 |
Page transitions in SPA (not abrupt) |
Navigate between pages, check for transition effects (fade, slide) rather than abrupt replacement |
| TC-ST35 |
Micro-interactions smooth |
Find toggle switches/checkboxes, interact, check for smooth animation via run-code |
playwright-cli -s=states-animation tracing-stop
playwright-cli -s=states-animation close
Fix Loop
After execution, if any tests failed, follow the fix loop process in references/fix-loop.md.
Max 3 attempts. Only re-run failed test cases.
Include fix attempt history in the report.
Report Generation
After all 4 agents complete, merge results into $OUTDIR/report.md following the standard report format.
Group results by agent category:
- Loading (TC-ST1 through TC-ST7)
- Empty/Error (TC-ST8 through TC-ST15)
- Overlays (TC-ST16 through TC-ST27)
- Animation (TC-ST28 through TC-ST35)
Cleanup
playwright-cli -s=states-loading close 2>/dev/null
playwright-cli -s=states-empty close 2>/dev/null
playwright-cli -s=states-overlay close 2>/dev/null
playwright-cli -s=states-animation close 2>/dev/null
1---2name: test-states3description: Test UI states and dynamic behavior including loading, empty, error, overlay, and animation states. Use when user wants to test modals, toasts, loading spinners, empty states, error handling, or animations.4---56# UI States & Dynamic Behavior78Run 35 test cases across 4 parallel agents covering loading states, empty/error states, overlays, and animations.910## Setup1112```bash13URL="${ARGUMENTS:-http://localhost:3000}"14TIMESTAMP=$(date +%Y%m%d-%H%M%S)15OUTDIR="test-results/test-states/$TIMESTAMP"16mkdir -p "$OUTDIR/screenshots" "$OUTDIR/snapshots" "$OUTDIR/traces"17```1819Before running, verify prerequisites per `references/prerequisites.md`.2021## Parallel Execution — 4 Subagents2223### Agent 1: Loading (`-s=states-loading`)2425Tests loading, skeleton, and transition states.2627```bash28playwright-cli -s=states-loading open "$URL"29playwright-cli -s=states-loading tracing-start30```3132**Test Cases:**3334| TC | Test | How to Check |35|----|------|-------------|36| TC-ST1 | Loading spinner appears during async ops | `run-code` to intercept network requests (delay responses), check for spinner/loading indicator |37| TC-ST2 | Skeleton screens render before data loads | `run-code` to intercept API calls (delay response), check for skeleton CSS (animated pulse/shimmer) |38| TC-ST3 | No FOUC (Flash of Unstyled Content) | `run-code` to observe page load, check if unstyled flash occurs (watch for style recalculation) |39| TC-ST4 | No layout shift when content loads | `run-code` to measure CLS during page load via PerformanceObserver |40| TC-ST5 | Progressive loading — above-fold first | `run-code` to check if above-fold images/content load before below-fold |41| TC-ST6 | Optimistic UI — updates before server response | `run-code` to intercept a mutation request (delay it), check if UI updates immediately |42| TC-ST7 | Loading states on buttons (prevent double-click) | Click a submit button, check if it shows loading state / becomes disabled |4344```bash45playwright-cli -s=states-loading tracing-stop46playwright-cli -s=states-loading close47```4849### Agent 2: Empty/Error (`-s=states-empty`)5051Tests empty states, error states, and edge cases.5253```bash54playwright-cli -s=states-empty open "$URL"55playwright-cli -s=states-empty tracing-start56```5758**Test Cases:**5960| TC | Test | How to Check |61|----|------|-------------|62| TC-ST8 | Empty state shown for empty lists/tables | `run-code` to mock API returning empty array, check for empty state UI |63| TC-ST9 | Empty state has helpful CTA | When empty state shown, check for action button/link (e.g., "Add your first item") |64| TC-ST10 | 404 page exists and is helpful | Navigate to `$URL/nonexistent-page-xyz-404`, verify custom 404 page with navigation back |65| TC-ST11 | 500 error page exists (no stack trace) | `run-code` to mock API returning 500, check error page doesn't show stack trace |66| TC-ST12 | Network error state (offline/timeout) | `run-code` to set page offline mode, trigger action, check for error UI |67| TC-ST13 | Permission denied state | `run-code` to mock API returning 403, check for appropriate UI |68| TC-ST14 | Session expired state + redirect | `run-code` to mock API returning 401, check for redirect to login or session expired message |69| TC-ST15 | Partial failure — some items load, some don't | `run-code` to mock mixed success/failure responses, verify partial UI renders |7071```bash72playwright-cli -s=states-empty tracing-stop73playwright-cli -s=states-empty close74```7576### Agent 3: Overlays (`-s=states-overlay`)7778Tests modals, toasts, tooltips, and dropdowns.7980```bash81playwright-cli -s=states-overlay open "$URL"82playwright-cli -s=states-overlay tracing-start83playwright-cli -s=states-overlay snapshot --filename="$OUTDIR/snapshots/overlay-initial.yaml"84```8586**Test Cases:**8788| TC | Test | How to Check |89|----|------|-------------|90| TC-ST16 | Modal opens/closes correctly | Find and click modal trigger, verify modal appears. Click close, verify dismissed |91| TC-ST17 | Modal traps focus (Tab cycles within) | Open modal, Tab repeatedly, verify focus stays within modal via `run-code` checking activeElement |92| TC-ST18 | Modal closes on Escape | Open modal, `press Escape`, verify modal dismissed |93| TC-ST19 | Modal closes on backdrop click | Open modal, click outside modal content area, verify dismissed |94| TC-ST20 | Body scroll locked when modal open | Open modal, `run-code` to check `document.body.style.overflow` is `hidden` |95| TC-ST21 | Multiple modals stack correctly | If multiple modals possible: open two, verify z-index stacking, top modal is interactive |96| TC-ST22 | Toast/notification appears + auto-dismisses | Trigger toast (e.g., form submit), verify it appears then disappears after timeout |97| TC-ST23 | Multiple toasts stack (don't overlap) | Trigger multiple toasts, verify they stack vertically without overlapping |98| TC-ST24 | Tooltip shows on hover + keyboard focus | `hover` over tooltip trigger, verify tooltip appears. Tab to it, verify also appears |99| TC-ST25 | Dropdown closes on outside click | Open dropdown, click outside it, verify it closes |100| TC-ST26 | Dropdown closes on Escape | Open dropdown, `press Escape`, verify it closes |101| TC-ST27 | Context menu doesn't go off-screen | `run-code` to find context menus/dropdowns near edges, verify they reposition to stay in viewport |102103```bash104playwright-cli -s=states-overlay tracing-stop105playwright-cli -s=states-overlay close106```107108### Agent 4: Animation (`-s=states-animation`)109110Tests animations, transitions, and motion.111112```bash113playwright-cli -s=states-animation open "$URL"114playwright-cli -s=states-animation tracing-start115```116117**Test Cases:**118119| TC | Test | How to Check |120|----|------|-------------|121| TC-ST28 | Animations are smooth (no jank) | `run-code` with requestAnimationFrame to measure frame timing, flag >16ms gaps |122| TC-ST29 | `prefers-reduced-motion` disables animations | `run-code`: `page.emulateMedia({reducedMotion:'reduce'})`, verify animations disabled via computed transition/animation styles |123| TC-ST30 | Transitions complete (not stuck mid-animation) | `run-code` to observe transition elements, verify they reach final state |124| TC-ST31 | Hover effects work | `hover` over interactive elements, `run-code` to check style changes (color, background, transform) |125| TC-ST32 | Active/pressed states visible on buttons | `run-code` to simulate mousedown on buttons, check for active state styles |126| TC-ST33 | Scroll-triggered animations fire | `run-code` to scroll page, check if animation classes are added to elements entering viewport |127| TC-ST34 | Page transitions in SPA (not abrupt) | Navigate between pages, check for transition effects (fade, slide) rather than abrupt replacement |128| TC-ST35 | Micro-interactions smooth | Find toggle switches/checkboxes, interact, check for smooth animation via `run-code` |129130```bash131playwright-cli -s=states-animation tracing-stop132playwright-cli -s=states-animation close133```134135## Fix Loop136137After execution, if any tests failed, follow the fix loop process in `references/fix-loop.md`.138Max 3 attempts. Only re-run failed test cases.139140Include fix attempt history in the report.141142## Report Generation143144After all 4 agents complete, merge results into `$OUTDIR/report.md` following the standard report format.145146Group results by agent category:1471. Loading (TC-ST1 through TC-ST7)1482. Empty/Error (TC-ST8 through TC-ST15)1493. Overlays (TC-ST16 through TC-ST27)1504. Animation (TC-ST28 through TC-ST35)151152## Cleanup153154```bash155playwright-cli -s=states-loading close 2>/dev/null156playwright-cli -s=states-empty close 2>/dev/null157playwright-cli -s=states-overlay close 2>/dev/null158playwright-cli -s=states-animation close 2>/dev/null159```
az9713