Ui Test

UI Test — Agentic UI Testing Skill

Test UI changes in a real browser. Your job is to try to break things, not confirm they work.

Three workflows:

• Diff-driven — analyze a git diff, test only what changed
• Exploratory — navigate the app, find bugs the developer didn't think about
• Parallel — fan out independent test groups across multiple Browserbase browsers

How Testing Works

The main agent coordinates — it plans test strategy, delegates to sub-agents, and merges results. Sub-agents do the actual browser testing.

Planning: multiple angles, then execute once

You MUST complete all three planning rounds yourself and output them before launching any sub-agents. Planning happens in your own response — it is NOT delegated to sub-agents. Do not skip ahead to execution.

Round 1 — Functional: What are the core user flows? What should work? Write out each test as: action → expected result.

Round 2 — Adversarial: Re-read Round 1. What did you miss? Think about: different user types/roles, error paths, empty states, race conditions, edge inputs (empty, huge, special chars, rapid clicks).

Round 3 — Coverage gaps: Re-read Rounds 1–2. What about: accessibility (axe-core, keyboard-only), mobile viewports, console errors, visual consistency with the rest of the app?

Deduplicate: Merge all three rounds into one numbered list of tests. Remove overlaps. Assign each test to a group (e.g. Group A, Group B).

Then execute once — launch one sub-agent per group. Each sub-agent receives its specific list of tests to run, nothing more. Sub-agents do not explore or plan — they execute assigned tests and report results.

Output the three rounds, the merged plan, and the group assignments in your response before calling any Agent tool.

Principles for splitting work

• Sub-agents run assigned tests, not open exploration. The main agent hands each sub-agent a specific numbered list of tests. Sub-agents do not plan, explore, or decide what to test — they execute the list and stop.
• The bottleneck is the slowest agent — split work so no single agent has a disproportionate share. Many small agents > few large ones.
• Size the effort to the change — a single component fix doesn't need many agents or many steps. A full-page redesign does. Let the scope of the diff drive the plan.
• No early stopping on failures — find as many bugs as possible within the assigned tests.

Giving sub-agents a step budget

The main agent MUST include an explicit browse step limit in every sub-agent prompt. Sub-agents do not self-limit — they will run until done unless told otherwise.

As a rough heuristic: ~25 steps for a few targeted checks, ~40 for a full page with functional + adversarial + a11y, ~75 for multiple pages or a broad category. Adjust based on what the assigned tests actually require — these are starting points, not rules.

As a rough heuristic: ~25 steps for a few targeted checks, ~40 for a full page with functional + adversarial + a11y, ~75 for multiple pages or a broad category. Adjust based on what the assigned tests actually require — these are starting points, not rules.

Every sub-agent prompt must include:

You have a budget of N browse steps (each `browse` command = 1 step). Count your steps as you go. When you reach N, stop immediately and report:
- STEP_PASS/STEP_FAIL for every test you completed
- STEP_SKIP|<test-id>|budget reached for every test you didn't get to

Do not retry or continue after hitting the budget.
Run only these tests: [numbered list from the merged plan]
Do not explore beyond the assigned tests.
Do NOT generate an HTML report or write any files. Return only step markers and your findings as text.

The main agent should NOT run browse commands itself (except to verify the dev server is up). All testing happens in sub-agents.

When a sub-agent hits its budget, the main agent accepts the partial results as-is. Do not re-run or retry the sub-agent. Include SKIPPED tests in the final report so the developer knows what wasn't covered.

Reporting

Every sub-agent reports back with:

Tests: 8 | Passed: 5 | Failed: 2 | Skipped: 1 | Pages visited: 2

The main agent merges into a final report with:

Tests: 20 | Passed: 14 | Failed: 4 | Skipped: 2 | Agents: 3 | Pass rate: 70%

Do not report "steps used" — browse command counts are implementation plumbing, not a meaningful metric for reviewers.

Testing Philosophy

You are an adversarial tester. Your goal is to find bugs, not prove correctness.

• Try to break every feature you test. Don't just check "does the button exist?" — click it twice rapidly, submit empty forms, paste 500 characters, press Escape mid-flow.
• Test what the developer didn't think about. Empty states, error recovery, keyboard-only navigation, mobile overflow.
• Every assertion must be evidence-based. Compare before/after snapshots. Check specific elements by ref. Never report PASS without concrete evidence from the accessibility tree or a deterministic check.
• Report failures with enough detail to reproduce. Include the exact action, what you expected, what you got, and a suggested fix.

Assertion Protocol

Every test step MUST produce a structured assertion. Do not write freeform "this looks good."

Step markers

For each test step, emit exactly one marker:

STEP_PASS|<step-id>|<evidence>

or

STEP_FAIL|<step-id>|<expected> → <actual>|<screenshot-path>

• step-id: short identifier like homepage-cta, form-validation-error, modal-cancel
• evidence: what you observed that proves the step passed (element ref, text content, URL, eval result)
• expected → actual: what you expected vs what you got
• screenshot-path: path to the saved screenshot (failures only — see Screenshot Capture below)

Screenshot Capture for Failures

Every STEP_FAIL MUST have an accompanying screenshot so the developer can see what went wrong visually.

When a test step fails:

# 1. Take a screenshot immediately after observing the failure
browse screenshot --path .context/ui-test-screenshots/<step-id>.png

# If --path is not supported, take the screenshot and save manually:
browse screenshot
# The browse CLI will output the screenshot path — move/copy it:
cp /tmp/browse-screenshot-*.png .context/ui-test-screenshots/<step-id>.png

Setup the screenshot directory at the start of any test run:

mkdir -p .context/ui-test-screenshots

Rules:

• File name = step-id (e.g., double-submit.png, axe-audit.png, modal-focus-trap.png)
• Store in .context/ui-test-screenshots/ — this directory is gitignored and accessible to the developer and other agents
• For parallel runs, include the session name: <session>-<step-id>.png (e.g., signup-double-submit.png)
• Take the screenshot at the moment of failure — capture the broken state, not after recovery
• For visual/layout bugs, also screenshot the baseline (working state) for comparison: <step-id>-baseline.png

How to verify (in order of rigor)

1. Deterministic check (strongest) — browse eval returns structured data you can inspect. Examples: axe-core violation count, document.title, form field value, console error array, element count. 2. Snapshot element match — a specific element with a specific role and text exists in the accessibility tree. Check by ref: @0-12 button "Save". An element either exists in the tree or it doesn't. 3. Before/after comparison — snapshot before action, act, snapshot after. Verify the tree changed in the expected way (element appeared, disappeared, text changed). 4. Screenshot + visual judgment (weakest) — only for visual-only properties (color, spacing, layout) that the accessibility tree cannot capture. Always accompany with what specifically you're evaluating.

Before/after comparison pattern

This is the core verification loop. Use it for every interaction:

# 1. BEFORE: capture state
browse snapshot
# Record: what elements exist, their text, their refs

# 2. ACT: perform the interaction
browse click @0-12

# 3. AFTER: capture new state
browse snapshot
# Compare: what changed? What appeared? What disappeared?

# 4. ASSERT: emit marker based on comparison
# If dialog appeared: STEP_PASS|modal-open|dialog "Confirm" appeared at @0-20
# If nothing changed:
browse screenshot --path .context/ui-test-screenshots/modal-open.png
# STEP_FAIL|modal-open|expected dialog to appear → snapshot unchanged|.context/ui-test-screenshots/modal-open.png

Setup

which browse || npm install -g browse

Avoid permission fatigue

This skill runs many browse commands (snapshots, clicks, evals). To avoid approving each one, add browse to your allowed commands:

Add both patterns to .claude/settings.json (project-level) or ~/.claude/settings.json (user-level):

{
  "permissions": {
    "allow": [
      "Bash(browse:*)",
      "Bash(BROWSE_SESSION=*)"
    ]
  }
}

The first pattern covers plain browse commands. The second covers parallel sessions (BROWSE_SESSION=signup browse open ...). Both are needed to avoid approval prompts.

Mode Selection

Rule: If the target URL contains `localhost` or `127.0.0.1`, pass `--local` on the first `browse open`.

Local Mode (default for localhost)

browse open http://localhost:3000 --local

browse open ... --local uses a clean isolated local browser by default, which is best for reproducible localhost QA runs.

Use local-mode variants only when needed:

• browse open <url> --auto-connect — auto-discover an existing debuggable local Chrome. Use this only when the test explicitly needs existing local login/cookies/state.
• browse open <url> --cdp <port|url> — attach to a specific CDP target (explicit local browser attach).

Remote Mode (deployed sites via cookie-sync)

# Step 1: Sync cookies from local Chrome to Browserbase
node .claude/skills/cookie-sync/scripts/cookie-sync.mjs --domains your-app.com
# Output: Context ID: ctx_abc123

# Step 2: Open in remote mode with the synced context
SESSION_JSON="$(browse cloud sessions create --context-id ctx_abc123 --persist --keep-alive)"
SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"

browse open https://staging.your-app.com --cdp "$CONNECT_URL"
browse snapshot
# ... run tests ...
browse stop
browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE

Cookie-sync flags: --domains, --context, --verified, --proxy "City,ST,US"

Workflow A: Diff-Driven Testing

Phase 1: Analyze the diff

git diff --name-only HEAD~1          # or: git diff --name-only / git diff --name-only main...HEAD
git diff HEAD~1 -- <file>            # read actual changes

Categorize changed files:

Phase 2: Map files to URLs

Detect framework: cat package.json | grep -E '"(next|react|vue|nuxt|svelte|@sveltejs|angular|vite)"'

Phase 3: Ensure the right code is running

Before testing, verify the dev server is serving the code from the diff — not a stale branch.

If testing a PR or specific branch:

# Check what branch is currently checked out
git branch --show-current

# If it's not the PR branch, switch to it
git fetch origin <branch> && git checkout <branch>

# Install deps — the lockfile may differ between branches
yarn install  # or npm install / pnpm install

If the dev server was already running on a different branch, restart it after checkout.

Find a running dev server:

for port in 3000 3001 5173 4200 8080 8000 5000; do
  s=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:$port" 2>/dev/null)
  if [ "$s" != "000" ]; then echo "Dev server on port $port (HTTP $s)"; fi
done

If nothing found: tell the user to start their dev server.

Verify it actually renders: After browse open + browse snapshot, check that the accessibility tree contains real page content (navigation, headings, interactive elements) — not just an error overlay or empty body. Next.js dev servers can return HTTP 200 while showing a full-screen build error dialog. If the snapshot is empty or dominated by an error dialog, the server is broken — fix the build before testing.

Phase 4: Generate test plan

For each changed area, plan both happy path AND adversarial tests:

Test Plan (based on git diff)
=============================
Changed: src/components/SignupForm.tsx (added email validation)

1. [happy] Valid email submits successfully
   URL: http://localhost:3000/signup
   Steps: fill valid email → submit → verify success message appears

2. [adversarial] Invalid email shows error
   Steps: fill "not-an-email" → submit → verify error message appears

3. [adversarial] Empty form submission
   Steps: click submit without filling anything → verify error, no crash

4. [adversarial] XSS in email field
   Steps: fill "<script>alert(1)</script>" → submit → verify sanitized/rejected

5. [adversarial] Rapid double-submit
   Steps: click submit twice quickly → verify no duplicate submission

6. [adversarial] Keyboard-only flow
   Steps: Tab to email → type → Tab to submit → Enter → verify success

Phase 5: Execute tests

browse stop 2>/dev/null
mkdir -p .context/ui-test-screenshots
# localhost/default QA → clean, reproducible local run
browse open http://localhost:3000 --local

For each test, follow the before/after pattern:

# Navigate
browse open http://localhost:3000/path --local
browse wait load

# BEFORE snapshot
browse snapshot
# Note the current state: elements, refs, text

# ACT
browse click @0-ref
# or: browse fill "selector" "value"
# or: browse type "text"
# or: browse press Enter

# AFTER snapshot
browse snapshot
# Compare against BEFORE: what changed?

# ASSERT with marker
# STEP_PASS|step-id|evidence  OR  STEP_FAIL|step-id|expected → actual

Phase 6: Report results

## UI Test Results

### STEP_PASS|valid-email-submit|status "Thanks!" appeared at @0-42 after submit
- URL: http://localhost:3000/signup
- Before: form with email input @0-3, submit button @0-7
- Action: filled "user@test.com", clicked @0-7
- After: form replaced by status element with "Thanks! We'll be in touch."

### STEP_FAIL|double-submit|expected single submission → form submitted twice|.context/ui-test-screenshots/double-submit.png
- URL: http://localhost:3000/signup
- Before: form with submit button @0-7
- Action: clicked @0-7 twice rapidly
- After: two success toasts appeared, suggesting duplicate submission
- Screenshot: .context/ui-test-screenshots/double-submit.png
- Suggestion: disable submit button after first click, or debounce the handler

---
**Summary: 4/6 passed, 2 failed**
Failed: double-submit, xss-sanitization

Screenshots saved to `.context/ui-test-screenshots/` — open any failed step's screenshot to see the broken state.

Always browse stop when done.

Phase 7: Generate HTML report

After producing the text report, generate a standalone HTML report that a reviewer can open in a browser. The report embeds screenshots inline (base64) so it works as a single file — no external dependencies.

Why: Text reports are good for the agent conversation, but reviewers (PMs, designers, other engineers) want a visual artifact they can open, scan, and share. Screenshots inline make failures immediately obvious.

How to generate

1. Read the HTML template at references/report-template.html 2. Build the report by replacing the template placeholders with actual test data:

3. For each test result, generate a <details> card. Failed tests should be open by default so reviewers see them immediately:

<!-- Failed test card (open by default) -->
<div class="section">
  <h2>Failures <span class="count">{{FAIL_COUNT}}</span></h2>
  <details class="test-card fail" open>
    <summary>
      <span class="badge fail">FAIL</span>
      <span class="step-id">step-id-here</span>
      <span class="evidence">expected → actual</span>
    </summary>
    <div class="body">
      <dl>
        <dt>URL</dt><dd>http://localhost:3000/path</dd>
        <dt>Action</dt><dd>What was done</dd>
        <dt>Expected</dt><dd>What should have happened</dd>
        <dt>Actual</dt><dd>What happened instead</dd>
      </dl>
      <div class="suggestion">Fix: description of suggested fix</div>
      <div class="screenshot">
        <img src="data:image/png;base64,..." alt="Screenshot of failure">
        <div class="caption">step-id.png — captured at moment of failure</div>
      </div>
    </div>
  </details>
</div>

<!-- Passed test card (collapsed by default) -->
<div class="section">
  <h2>Passed <span class="count">{{PASS_COUNT}}</span></h2>
  <details class="test-card pass">
    <summary>
      <span class="badge pass">PASS</span>
      <span class="step-id">step-id-here</span>
      <span class="evidence">evidence summary</span>
    </summary>
    <div class="body">
      <dl>
        <dt>URL</dt><dd>http://localhost:3000/path</dd>
        <dt>Evidence</dt><dd>What was observed</dd>
      </dl>
    </div>
  </details>
</div>

4. Embed screenshots as base64 so the HTML is fully self-contained:

# Convert screenshot to base64 data URI
base64 -i .context/ui-test-screenshots/step-id.png | tr -d '\n'
# Use as: src="data:image/png;base64,<output>"

Read each screenshot file referenced in STEP_FAIL markers, base64-encode it, and embed it as an <img src="data:image/png;base64,..."> in the corresponding test card. For STEP_PASS, only embed a screenshot if one was explicitly taken (e.g., baseline screenshots).

5. Write the final HTML to .context/ui-test-report.html:

# Write the generated HTML
cat > .context/ui-test-report.html << 'REPORT_EOF'
<!DOCTYPE html>
...generated report...
REPORT_EOF

# Open it for the reviewer
open .context/ui-test-report.html  # macOS
# xdg-open .context/ui-test-report.html  # Linux

6. Tell the user: Report saved to .context/ui-test-report.html and offer to open it.

Rules:

• Failures section comes before passes — reviewers care about what's broken first
• Failed cards are open by default; passed cards are collapsed
• Every STEP_FAIL card MUST have an embedded screenshot — if the screenshot file is missing, note it in the card
• Include the suggestion/fix in each failure card if one was provided
• The report must work offline — no CDN links, no external assets
• Keep the HTML under 5MB — if screenshots push it over, reduce image quality or skip baseline screenshots for passes

Adversarial Test Patterns

Apply these to every interactive element you test. Read references/adversarial-patterns.md for the full pattern library (forms, modals, navigation, error states, keyboard accessibility).

Deterministic Checks

These produce structured data, not judgment calls. Use them as the strongest form of assertion.

For the exact browse eval recipes, read references/browser-recipes.md.

Workflow B: Exploratory Testing

No diff, no plan — just open the app and try to break it. Use this when the user says "test my app", "find bugs", or "QA this site."

Approach

1. Discover the app — read package.json to detect the framework, then open the root URL and snapshot to see what's there 2. Navigate everything — click through nav links, visit every reachable page, note what exists 3. Test what you find — for each page, apply the adversarial patterns below (forms, modals, navigation, keyboard, error states) 4. Run deterministic checks — axe-core, console errors, broken images, form labels on every page 5. Report findings — use STEP_PASS/STEP_FAIL markers, include reproduction steps for failures

Don't try to be systematic about coverage. Just explore like a user would, but with the intent to break things. The agent is good at this — let it roam.

Tips for exploratory runs

• Start with the homepage, then follow the navigation naturally
• Try the 404 page (/does-not-exist) — is it custom or default?
• Look for empty states (pages with no data)
• Test forms with garbage input before valid input
• Check mobile viewport (375px) on every page — does it overflow?
• If the app has auth, use cookie-sync first

Workflow C: Parallel Testing

Run independent test groups concurrently using named browse sessions (BROWSE_SESSION=<name>). Each session gets its own browser. Works with both local and remote mode.

Use when testing multiple pages or categories and you want faster wall clock time.

Read references/parallel-testing.md for the full workflow: session setup, agent fan-out, cookie-sync for auth, and result merging.

Design Consistency

Check whether changed UI matches the rest of the app visually. Read references/design-consistency.md when doing visual or design checks.

Test Categories

Reference guides (load on demand):

• Adversarial patterns — references/adversarial-patterns.md — load when testing forms, modals, navigation, or keyboard a11y
• Browser recipes — references/browser-recipes.md — load when running deterministic checks (axe-core, console, images, form labels)
• Exploratory testing — references/exploratory-testing.md — load for Workflow B (no diff, open exploration)
• UX heuristics — references/ux-heuristics.md — load when evaluating UX quality or citing specific heuristics
• Design system — references/design-system.example.md — template for users to customize
• Design consistency — references/design-consistency.md — load when doing visual consistency checks
• Parallel testing — references/parallel-testing.md — load for Workflow C (concurrent sessions)
• Report template — references/report-template.html — HTML template for Phase 7 report generation

For worked examples with exact commands, read EXAMPLES.md if you need to see the assertion protocol in action.

Best Practices

1. Be adversarial — try to break things, don't just confirm they work 2. Every assertion needs evidence — snapshot ref, eval result, or before/after diff 3. Before/after for every interaction — snapshot, act, snapshot, compare 4. Screenshot every failure — browse screenshot immediately on STEP_FAIL, save to .context/ui-test-screenshots/<step-id>.png 5. Deterministic checks first — axe-core, console errors, form labels before visual judgment 6. For localhost, start with clean local mode — pass --local on the first browse open for reproducible runs; use --auto-connect only when existing local state is required 7. Always `browse stop` when done — for parallel runs, stop every named session 8. Report failures with reproduction steps — action, expected, actual, screenshot path, suggestion 9. Parallelize independent tests — use Workflow C with named sessions when testing multiple pages or categories on a deployed site

Troubleshooting

• "No active page": browse stop, retry. For zombies: pkill -f "browse.*daemon"
• Dev server not responding: curl http://localhost:<port> — ask user to start it
• `browse eval` with `await` fails: Use .then() instead — browse eval doesn't support top-level await
• Element ref not found: browse snapshot again — refs change on page update
• Blank snapshot: browse wait load or browse wait selector ".expected" before snapshotting
• SPA deep links 404: Navigate to / first, then click through
• Remote auth fails: Re-run cookie-sync with --context <id>, try --verified
• Parallel session conflicts: Ensure every browse command uses BROWSE_SESSION=<name> — without it, commands go to the default session
• Session not stopping: BROWSE_SESSION=<name> browse stop. For zombies: pkill -f "browse.*<name>.*daemon"

UI Test Examples

Each example demonstrates the full assertion protocol: before/after comparison, structured markers, and adversarial testing.

Example 1: Diff-Driven Component Test (Happy + Adversarial)

User request: "I updated the CTA button text. Test it."

# Analyze diff
git diff --name-only HEAD~1
# Output: src/components/HeroSection.tsx
git diff HEAD~1 -- src/components/HeroSection.tsx
# Shows: "Get Started" changed to "Start Free Trial"

# Setup
browse open http://localhost:3000/ --local
browse wait load

# BEFORE snapshot
browse snapshot
# Tree: @0-8 button "Start Free Trial"
# Evidence: button exists with new text

# Happy path: button is clickable
browse click @0-8
browse snapshot
# AFTER: check no crash, page still functional

# STEP_PASS|cta-text|button "Start Free Trial" found at @0-8
# STEP_PASS|cta-click|button click succeeded, page intact after click

# Adversarial: rapid click
browse open http://localhost:3000/
browse wait load
browse snapshot
browse click @0-8
browse click @0-8
browse click @0-8
browse snapshot
# Check: no duplicate dialogs, no console errors, page still stable

# STEP_PASS|cta-rapid-click|3 rapid clicks, page remains stable, no duplicate side effects

browse stop

Result:

## UI Test Results
### STEP_PASS|cta-text|button "Start Free Trial" found at @0-8
### STEP_PASS|cta-click|clicked @0-8, page intact
### STEP_PASS|cta-rapid-click|3 rapid clicks, no duplicate effects
**Summary: 3/3 passed**

Example 2: Form Validation — Happy Path, Errors, and Adversarial

User request: "I added email validation to the signup form. Test it thoroughly."

browse open http://localhost:3000/signup --local
browse wait load

# ---- Test 1: Invalid email → error ----
# BEFORE
browse snapshot
# @0-3 textbox "Email", @0-7 button "Sign Up"

# ACT
browse fill "input[name=email]" "not-an-email"
browse click @0-7

# AFTER
browse snapshot
# @0-9 alert "Please enter a valid email"

# STEP_PASS|invalid-email|alert "Please enter a valid email" appeared at @0-9

# ---- Test 2: Valid email → success ----
browse open http://localhost:3000/signup
browse wait load

# BEFORE
browse snapshot

# ACT
browse fill "input[name=email]" "user@example.com"
browse click @0-7
browse wait load

# AFTER
browse snapshot
# heading "Welcome! Check your email." appeared, form gone

# STEP_PASS|valid-email|heading "Welcome!" appeared, form removed from tree

# ---- Test 3: Empty submission ----
browse open http://localhost:3000/signup
browse wait load

# BEFORE
browse snapshot

# ACT: submit with nothing filled
browse click @0-7

# AFTER
browse snapshot
# Check: error message? Or silent failure? Or crash?

# STEP_PASS|empty-submit|alert "Please enter a valid email" appeared — form handles empty input

# ---- Test 4: XSS in email field ----
browse open http://localhost:3000/signup
browse wait load

browse fill "input[name=email]" "<script>alert('xss')</script>"
browse click @0-7
browse snapshot
# Note: the XSS payload WILL appear in the snapshot as StaticText inside the input
# field — that's just the input value, not rendered HTML. The real checks are:
# 1. Is there a validation error? (email format rejected)
# 2. Is the payload rendered as HTML outside the input? (check for script execution)
browse eval "document.querySelector('[role=alert]')?.textContent || 'no alert'"
# Result: "Please enter a valid email"
browse eval "document.querySelector('input[name=email]')?.value"
# Result: "<script>alert('xss')</script>" — payload stays as text in the input, not rendered as HTML

# STEP_PASS|xss-email|XSS payload rejected by validation, no inline script injection detected

# ---- Test 5: Very long email ----
browse open http://localhost:3000/signup
browse wait load

browse fill "input[name=email]" "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa@test.com"
browse snapshot
# Check: does the input overflow its container? Is layout broken?
browse screenshot --path /tmp/long-email.png
# Visual check: input stays within bounds

browse click @0-7
browse snapshot
# Check: does validation handle long but valid emails?

# STEP_PASS|long-email|60-char email accepted, layout intact, no overflow

# ---- Test 6: Keyboard-only flow ----
browse open http://localhost:3000/signup
browse wait load

browse press Tab
browse eval "document.activeElement?.name || document.activeElement?.tagName"
# Should focus email input
browse type "keyboard@test.com"
browse press Tab
# Should move to submit button
browse eval "document.activeElement?.tagName"
# Should be BUTTON
browse press Enter

browse snapshot
# Check: form submitted successfully via keyboard alone

# STEP_PASS|keyboard-flow|form submitted via Tab+type+Tab+Enter, success message appeared

browse stop

Result:

## UI Test Results
### STEP_PASS|invalid-email|alert "Please enter a valid email" at @0-9
### STEP_PASS|valid-email|heading "Welcome!" appeared, form removed
### STEP_PASS|empty-submit|empty form shows validation error
### STEP_PASS|xss-email|XSS payload rejected, not rendered as HTML
### STEP_PASS|long-email|60-char email accepted, layout intact
### STEP_PASS|keyboard-flow|full form flow works via keyboard only
**Summary: 6/6 passed**

Example 3: Modal Lifecycle — Full State Machine

User request: "I added a confirmation modal to delete. Test it."

browse open http://localhost:3000/dashboard --local
browse wait load

# ---- Test 1: Modal opens ----
# BEFORE
browse snapshot
# @0-15 button "Delete Account", no dialog in tree

# ACT
browse click @0-15

# AFTER
browse wait selector "[role=dialog]"
browse snapshot
# @0-20 dialog "Confirm Action", @0-22 button "Cancel", @0-23 button "Confirm"

# STEP_PASS|modal-open|dialog "Confirm Action" appeared at @0-20 with Cancel and Confirm buttons

# ---- Test 2: Cancel closes modal, no side effects ----
# BEFORE: dialog present
browse snapshot

# ACT
browse click @0-22

# AFTER
browse snapshot
# No dialog in tree. @0-15 button "Delete Account" still present.

# STEP_PASS|modal-cancel|dialog removed from tree, delete button still present, no side effects

# ---- Test 3: Escape closes modal ----
browse click @0-15
browse wait selector "[role=dialog]"
browse snapshot
# dialog present

browse press Escape
browse snapshot
# Check: dialog gone?

# STEP_PASS|modal-escape|Escape key closed dialog

# ---- Test 4: Confirm executes action ----
browse click @0-15
browse wait selector "[role=dialog]"
browse snapshot
# dialog present

browse click @0-23
browse snapshot
# Check: dialog gone AND the destructive action occurred

# STEP_PASS|modal-confirm|dialog closed and action executed after Confirm click

# ---- Test 5: Focus trap (adversarial) ----
browse click @0-15
browse wait selector "[role=dialog]"

# Tab through dialog — focus should stay inside
browse press Tab
browse eval "document.activeElement?.textContent?.trim().slice(0,20)"
browse press Tab
browse eval "document.activeElement?.textContent?.trim().slice(0,20)"
browse press Tab
browse eval "document.activeElement?.textContent?.trim().slice(0,20)"
# Check: does focus cycle within dialog, or does it escape to page behind?

# STEP_PASS|focus-trap|focus cycles within dialog (Cancel → Confirm → Cancel)
# or on failure:
browse screenshot --path .context/ui-test-screenshots/focus-trap.png
# STEP_FAIL|focus-trap|expected focus trapped in dialog → focus escaped to nav link behind modal|.context/ui-test-screenshots/focus-trap.png

browse stop

Example 4: Accessibility Audit with Deterministic Assertions

User request: "Run accessibility tests on the settings page."

browse open http://localhost:3000/settings --local
browse wait load

# ---- Test 1: axe-core audit ----
browse eval "const s = document.createElement('script'); s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js'; document.head.appendChild(s); 'loading'"
browse wait timeout 3000
browse eval "axe.run().then(r => JSON.stringify({ violations: r.violations.map(v => ({ id: v.id, impact: v.impact, description: v.description, nodes: v.nodes.length })), passes: r.passes.length }))"
# Result: {"violations":[],"passes":33}

# Assert: violations.length === 0
# STEP_PASS|axe-audit|0 violations, 33 passes

# If violations existed:
# STEP_FAIL|axe-audit|expected 0 violations → found 2: color-contrast (serious, 3 nodes), label (critical, 1 node)

# ---- Test 2: Form labels ----
browse eval "JSON.stringify(Array.from(document.querySelectorAll('input,select,textarea')).map(i => ({ name: i.name, type: i.type, hasLabel: !!i.labels?.length, ariaLabel: i.getAttribute('aria-label') })))"
# Check: every input has hasLabel:true or ariaLabel

# STEP_PASS|form-labels|all 3 inputs have associated labels

# ---- Test 3: Keyboard navigation ----
browse press Tab
browse eval "JSON.stringify({tag: document.activeElement?.tagName, text: document.activeElement?.textContent?.trim().slice(0,30)})"
# Repeat for each interactive element
# Track: element order, whether focus ring is visible

# STEP_PASS|keyboard-nav|8 elements reachable via Tab, logical order, all focusable

# ---- Test 4: Broken images ----
browse eval "JSON.stringify(Array.from(document.querySelectorAll('img')).filter(i => !i.complete || i.naturalWidth === 0).map(i => ({ src: i.src, alt: i.alt })))"
# Result: []

# STEP_PASS|images|0 broken images

browse stop

Example 5: Responsive Testing with Before/After

User request: "Does my app work on mobile?"

browse open http://localhost:3000/ --local
browse wait load

# ---- Desktop baseline ----
browse viewport 1440 900
browse wait timeout 500
browse snapshot
# Record desktop state: nav layout, content width, element positions
browse screenshot --path /tmp/desktop.png --full-page

# ---- Mobile ----
browse viewport 375 812
browse wait timeout 1000
browse snapshot
# Compare against desktop:
# - Did nav collapse to hamburger? Or is it overflowing?
# - Is content full-width? Or is there horizontal scroll?
# - Are buttons large enough for touch (44px+)?
browse screenshot --path /tmp/mobile.png --full-page

# Check for horizontal overflow (deterministic)
browse eval "document.documentElement.scrollWidth > document.documentElement.clientWidth"
# Result: false = PASS, true = FAIL (content overflows viewport)

# STEP_PASS|mobile-overflow|no horizontal overflow at 375px (scrollWidth <= clientWidth)

# Check touch target sizes
browse eval "JSON.stringify(Array.from(document.querySelectorAll('button,a,[role=button]')).map(el => { const r = el.getBoundingClientRect(); return { text: el.textContent?.trim().slice(0,20), width: Math.round(r.width), height: Math.round(r.height) }}).filter(e => e.width < 44 || e.height < 44))"
# Result: [] = all targets >= 44px, otherwise list of undersized elements

# STEP_PASS|touch-targets|all interactive elements >= 44px

# ---- Tablet ----
browse viewport 768 1024
browse wait timeout 1000
browse screenshot --path /tmp/tablet.png --full-page

browse stop

Example 6: Console Health — Deterministic Error Detection

User request: "Are there any JS errors on my app?"

browse open about:blank --local

# Check each route for failed resource loads and JS errors
# Note: console capture injected on about:blank gets wiped on navigation.
# Instead, check per-page with the performance API + inject capture on the page itself.

for_each_route() {
  # Method 1: Check for failed resource loads (works on initial load)
  browse open "TARGET_URL"
  browse wait load
  browse eval "JSON.stringify(performance.getEntries().filter(e => e.entryType === 'resource' && e.responseStatus >= 400).map(e => ({ url: e.name, status: e.responseStatus })))"
  # Result: [] = PASS, any failed resources = FAIL

  # Method 2: Inject capture on the page, then interact to catch runtime errors
  browse eval "window.__logs = []; const _origErr = console.error; console.error = (...a) => { window.__logs.push({type:'error', text: a.join(' ')}); _origErr(...a); }; window.addEventListener('error', e => window.__logs.push({type:'uncaught', text: e.message})); 'installed'"

  # Now interact (click buttons, submit forms, navigate)
  browse click @some-button
  browse eval "JSON.stringify(window.__logs)"
  # Any errors captured during interaction
}

# Example: check homepage
browse open http://localhost:3000/
browse wait load
browse eval "JSON.stringify(performance.getEntries().filter(e => e.entryType === 'resource' && e.responseStatus >= 400).map(e => e.name))"
# Result: [] — no failed loads
# STEP_PASS|console-home|0 failed resources on initial load

# Example: check dashboard with interaction
browse open http://localhost:3000/dashboard
browse wait load
browse eval "window.__logs=[]; const _orig=console.error; console.error=(...a)=>{window.__logs.push({t:'e',m:a.join(' ')}); _orig(...a);}; 'ok'"
browse click @some-button
browse eval "JSON.stringify(window.__logs)"
# Result: [{"t":"e","m":"Failed to fetch /api/items"}]
# STEP_FAIL|console-dashboard|expected 0 errors → 1 error during interaction: "Failed to fetch /api/items"

browse stop

Example 7: Remote Authenticated Test (Browserbase + Cookie-Sync)

User request: "Test our staging dashboard. I'm logged in locally."

# Step 1: Sync cookies
node .claude/skills/cookie-sync/scripts/cookie-sync.mjs --domains staging.myapp.com
# Output: Context ID: ctx_7f3a9b2c

# Step 2: Remote mode with the synced context
SESSION_JSON="$(browse cloud sessions create --context-id ctx_7f3a9b2c --persist --keep-alive)"
SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"

browse open https://staging.myapp.com/dashboard --cdp "$CONNECT_URL"
browse wait load

# Verify authenticated state
browse snapshot
# Check: user avatar present? Dashboard content loaded? Not a login redirect?
browse get url
# Verify URL is /dashboard, not /login

# STEP_PASS|remote-auth|authenticated dashboard loaded, user avatar present, URL is /dashboard

# Run tests against authenticated pages
browse open https://staging.myapp.com/settings
browse wait load
browse snapshot
# Verify settings content loads

# STEP_PASS|remote-settings|settings page loaded with form fields, not login redirect

# axe-core on remote page
browse eval "const s = document.createElement('script'); s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js'; document.head.appendChild(s); 'loading'"
browse wait timeout 3000
browse eval "axe.run().then(r => JSON.stringify({ violations: r.violations.length, passes: r.passes.length }))"

browse stop
browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE

Example 8: Exploratory Testing — Try to Break It

User request: "Explore my app and find bugs."

browse open http://localhost:3000/ --local
browse wait load

# ---- First impressions ----
browse snapshot
browse screenshot --path /tmp/explore-home.png

# Console health check
browse eval "JSON.stringify({errors: (window.__logs || []).length})"

# ---- Empty state audit ----
browse open http://localhost:3000/dashboard
browse wait load
browse snapshot
# Is there a designed empty state? Or just blank space?
# Check for: message, CTA, illustration
# STEP_PASS|empty-state|dashboard shows "No items yet." with CTA "Create your first item"
# or on failure:
browse screenshot --path .context/ui-test-screenshots/empty-state.png
# STEP_FAIL|empty-state|expected designed empty state → page is blank with no guidance|.context/ui-test-screenshots/empty-state.png

# ---- 404 handling ----
browse open http://localhost:3000/this-page-does-not-exist
browse wait load
browse snapshot
# Check: custom 404? Or generic error? Or blank?
browse get url
# STEP_PASS|404-page|custom 404 page with "Page not found" and link to home
# or: STEP_FAIL|404-page|expected custom 404 → got default Next.js error page

# ---- Form stress test ----
browse open http://localhost:3000/contact
browse wait load
browse snapshot

# Extremely long input
browse fill "textarea[name=message]" "This is a very long message that keeps going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going and going"
browse snapshot
browse screenshot --path /tmp/long-input.png
# Check: does textarea grow? Overflow? Break layout?

# Special characters
browse fill "input[name=email]" "test@test.com"
browse fill "textarea[name=message]" "<img src=x onerror=alert(1)> & \"quotes\" and emoji 🎉"
browse click @submit-ref
browse snapshot
# Check: content rendered safely? Not interpreted as HTML?

# ---- Navigation dead ends ----
# Click every nav link, check each page has a way back
browse open http://localhost:3000/pricing
browse wait load
browse snapshot
# Are there nav links? Can you get back to home?

browse stop

Report format for exploratory findings:

FINDING: Contact form textarea has no maxlength — 500+ char input accepted without truncation
SEVERITY: low
ROUTE: /contact
EVIDENCE: Filled 280 chars into message field, form accepted it, layout intact
RECOMMENDATION: Consider adding maxlength or character counter if there's a backend limit

FINDING: No custom 404 page — default Next.js error shown
SEVERITY: medium
ROUTE: /does-not-exist
EVIDENCE: Navigated to non-existent route, got default "404 | This page could not be found."
RECOMMENDATION: Add a custom not-found.tsx with navigation back to the app

Example 9: Parallel Testing on a Deployed Site (Browserbase)

User request: "QA the staging site — test signup, dashboard, and accessibility in parallel."

The key insight: each test group gets its own BROWSE_SESSION, which spins up an independent Browserbase browser. Groups run concurrently via the Agent tool.

Step 1: Plan parallel groups

Parallel Groups
===============
Group 1 (session: signup)     → /signup form tests (happy path + adversarial)
Group 2 (session: dashboard)  → /dashboard content + empty state
Group 3 (session: a11y)       → /settings axe-core + keyboard nav

Step 2: Cookie-sync (if auth needed)

node .claude/skills/cookie-sync/scripts/cookie-sync.mjs --domains staging.myapp.com
# Output: Context ID: ctx_7f3a9b2c

Step 3: Launch agents in parallel

Use the Agent tool — send all three in a single message so they run concurrently:

Agent 1 prompt:
  "You are running UI tests on https://staging.myapp.com/signup.
   Use BROWSE_SESSION=signup for every browse command.
   Start with:
     SESSION_JSON="$(browse cloud sessions create --context-id ctx_7f3a9b2c --keep-alive)"
     SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
     CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
     BROWSE_SESSION=signup browse open https://staging.myapp.com/signup --cdp "$CONNECT_URL"

   Run these tests using the before/after snapshot pattern:
   1. [happy] Fill valid email, submit, verify success
   2. [adversarial] Submit empty form, verify error
   3. [adversarial] Fill XSS payload, verify rejected
   4. [adversarial] Double-click submit, verify no duplicate

   For each test: snapshot BEFORE, act, snapshot AFTER, compare, emit:
     STEP_PASS|<id>|<evidence>  or  STEP_FAIL|<id>|<expected> → <actual>

   When done: BROWSE_SESSION=signup browse stop; browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE"

Agent 2 prompt:
  "You are running UI tests on https://staging.myapp.com/dashboard.
   Use BROWSE_SESSION=dashboard for every browse command.
   Start with:
     SESSION_JSON="$(browse cloud sessions create --context-id ctx_7f3a9b2c --keep-alive)"
     SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
     CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
     BROWSE_SESSION=dashboard browse open https://staging.myapp.com/dashboard --cdp "$CONNECT_URL"

   Run these tests:
   1. Check empty state — is there a message and CTA, or blank?
   2. Check data display — table columns, row count, formatting
   3. Check console errors — inject capture, interact, check __logs

   Emit STEP_PASS/STEP_FAIL markers. When done: BROWSE_SESSION=dashboard browse stop; browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE"

Agent 3 prompt:
  "You are running accessibility tests on https://staging.myapp.com/settings.
   Use BROWSE_SESSION=a11y for every browse command.
   Start with:
     SESSION_JSON="$(browse cloud sessions create --context-id ctx_7f3a9b2c --keep-alive)"
     SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
     CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
     BROWSE_SESSION=a11y browse open https://staging.myapp.com/settings --cdp "$CONNECT_URL"

   Run these tests:
   1. axe-core audit — load script, run, check violations
   2. Form labels — every input has an associated label
   3. Keyboard nav — Tab through all elements, verify focus order
   4. Broken images — check naturalWidth on all img elements

   Emit STEP_PASS/STEP_FAIL markers. When done: BROWSE_SESSION=a11y browse stop; browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE"

Step 4: Merge results

As each agent returns, collect markers into a unified report:

## UI Test Results (Parallel Run — 3 Browserbase sessions)

### Group: signup (session: signup)
STEP_PASS|valid-email|heading "Welcome!" appeared at @0-15 after submit
STEP_PASS|empty-submit|alert "Email required" appeared at @0-9
STEP_PASS|xss-email|XSS payload rejected by validation
STEP_FAIL|double-submit|expected single submission → two success toasts|.context/ui-test-screenshots/signup-double-submit.png

### Group: dashboard (session: dashboard)
STEP_PASS|empty-state|"No items yet" with CTA "Create first item"
STEP_PASS|data-display|table: 5 rows, 4 columns, dates formatted
STEP_PASS|console-health|0 errors during interaction

### Group: a11y (session: a11y)
STEP_FAIL|axe-audit|expected 0 violations → 2: color-contrast (serious, 3 nodes), label (critical, 1 node)|.context/ui-test-screenshots/a11y-axe-audit.png
STEP_PASS|form-labels|all 4 inputs have associated labels
STEP_PASS|keyboard-nav|10 elements reachable, logical order
STEP_PASS|images|0 broken images

---
**Summary: 9/11 passed, 2 failed (3 parallel sessions)**
Failed: double-submit (signup), axe-audit (a11y)
**Wall-clock time: ~45s (vs ~2min sequential)**

Step 5: Cleanup

# Safety net — stop any lingering sessions
BROWSE_SESSION=signup browse stop 2>/dev/null
BROWSE_SESSION=dashboard browse stop 2>/dev/null
BROWSE_SESSION=a11y browse stop 2>/dev/null

Tips

• Before/after for every interaction — never assert without comparing state change
• Deterministic checks are strongest — axe-core count, console error array, overflow boolean
• Try to break it — empty input, long input, special chars, rapid clicks, keyboard-only
• Use structured markers — STEP_PASS|id|evidence or STEP_FAIL|id|expected → actual|screenshot-path
• Screenshot every failure — save to .context/ui-test-screenshots/<step-id>.png so devs can see what broke
• Local for localhost — never send localhost traffic through Browserbase
• Default localhost run — start with browse open <url> --local for clean, reproducible QA
• Use `--auto-connect` selectively — only when a localhost test explicitly needs existing local Chrome login/cookies/state (browse open <url> --auto-connect)
• Explicit local CDP attach — use browse open <url> --cdp <port|url> when you must target a specific local browser instance
• Always `browse stop` when done — for parallel runs, stop every named session
• `.then()` not `await` — browse eval doesn't support top-level await
• Parallelize with `BROWSE_SESSION` — each named session gets its own Browserbase browser; fan out via Agent tool

ui-test — Agentic UI Testing Skill

Adversarial UI testing that catches what Playwright can't. Analyzes git diffs to test only what changed, or explores the full app to find bugs. Runs in a real browser via the browse CLI.

Install

npx skills add browserbase/ui-test

Quick Start

"Test the UI changes in my PR"         → diff-driven (Workflow A)
"Explore my app and find bugs"         → exploratory (Workflow B)
"QA the staging site in parallel"      → parallel Browserbase sessions (Workflow C)

How It Works

1. Analyzes the diff (or explores the app) to decide what to test 2. Opens a real browser — clean isolated local browser for localhost, Browserbase for deployed sites 3. Tries to break things — adversarial inputs, rapid clicks, keyboard-only, empty states, XSS 4. Runs deterministic checks — axe-core, console errors, broken images, form labels 5. Reports structured results — STEP_PASS|id|evidence or STEP_FAIL|id|expected → actual 6. Generates an HTML report — standalone file with embedded screenshots, shareable with reviewers

What It Tests

Browser Execution

which browse || npm install -g browse

• Localhost → browse open <url> --local (no API key needed)
• Need existing local login/cookies/state on localhost → browse open <url> --auto-connect (requires an existing debuggable local Chrome)
• Need explicit local CDP attach → browse open <url> --cdp <port|url>
• Deployed sites → browse open <url> --remote (uses Browserbase cloud browsers)
• Parallel → BROWSE_SESSION=<name> for independent concurrent sessions

For default localhost QA, pass --local on the first browse open for clean, reproducible runs.

Project Structure

ui-test/
├── SKILL.md                              # Skill definition — workflows, assertion protocol, budget
├── EXAMPLES.md                           # 9 worked examples with exact commands
├── README.md
└── references/
    ├── adversarial-patterns.md           # Adversarial test patterns (forms, modals, nav, keyboard)
    ├── browser-recipes.md                # Copy-paste browse CLI recipes for deterministic checks
    ├── design-consistency.md             # Design consistency checking methodology
    ├── design-system.example.md          # Example design system template (copy to design-system.md)
    ├── exploratory-testing.md            # Guide for agent-driven exploratory QA
    ├── parallel-testing.md              # Parallel testing with named Browserbase sessions
    ├── report-template.html              # HTML report template with embedded screenshots
    └── ux-heuristics.md                  # 6 evaluation frameworks (Laws of UX, Nielsen's, etc.)

Philosophy

Traditional tests verify intentions. This skill finds blind spots.

No YAML files, no generated test suites, no artifacts. The agent reads the diff (or explores the app), opens a browser, tries to break things, and reports what it found. Like a human QA tester with perfect knowledge of every design principle.

Requirements

• browse CLI (npm install -g browse)
• For remote testing: BROWSERBASE_API_KEY environment variable
• A running web app (localhost or deployed URL)

Adversarial Test Patterns

Use these patterns to try to break features. Apply them to every interactive element you test.

Forms — try to break them

# Empty submission
browse snapshot                          # BEFORE: note form fields
browse click @submit-ref                 # ACT: submit empty
browse snapshot                          # AFTER: error messages should appear

# Long input (500+ chars)
browse fill "#name" "aaaa....(500 chars)"
browse snapshot                          # Check: does layout break? Is text truncated?

# Special characters
browse fill "#name" "<script>alert('xss')</script>"
browse fill "#email" "'; DROP TABLE users;--"
browse snapshot                          # Check: input sanitized? No raw HTML rendered?

# Rapid submit
browse click @submit-ref
browse click @submit-ref                 # Click twice immediately
browse snapshot                          # Check: only one submission processed?

Modals — test the full lifecycle

browse snapshot                          # BEFORE: no dialog in tree

# Open
browse click @trigger-ref
browse snapshot                          # AFTER: dialog element should appear
# ASSERT: dialog role exists in tree

# Escape to close
browse press Escape
browse snapshot                          # AFTER: dialog should be gone
# ASSERT: dialog role removed from tree

# Re-open and cancel
browse click @trigger-ref
browse snapshot                          # dialog present
browse click @cancel-ref
browse snapshot                          # dialog gone

# Re-open and confirm
browse click @trigger-ref
browse snapshot                          # dialog present
browse click @confirm-ref
browse snapshot                          # dialog gone + side effect occurred

Navigation — verify routing works

browse snapshot                          # BEFORE: note current URL and content
browse click @nav-link-ref               # ACT: click a navigation link
browse wait load
browse get url                           # Check URL changed
browse snapshot                          # AFTER: content matches the destination
# Compare: different heading, different page content

# Back button
browse back
browse get url                           # Should return to original URL
browse snapshot                          # Content matches original page

Error states — find missing ones

# Navigate to a page with no data
browse open http://localhost:3000/items
browse snapshot
# Check: is there a designed empty state with a message and CTA?
# Or just blank space?

# Navigate to a non-existent route
browse open http://localhost:3000/does-not-exist
browse snapshot
# Check: 404 page? Or blank/error?

# Submit invalid data and check error recovery
browse fill "#field" "invalid"
browse click @submit-ref
browse snapshot
# Check: is the error message helpful? Does it tell you what's wrong?
# Check: is the user's input preserved? Or was the form cleared?

Keyboard accessibility — can you use it without a mouse?

browse open http://localhost:3000/page
browse wait load

# Tab through all interactive elements
browse press Tab
browse eval "JSON.stringify({tag: document.activeElement?.tagName, text: document.activeElement?.textContent?.trim().slice(0,40), role: document.activeElement?.getAttribute('role')})"
# Repeat Tab + eval until activeElement returns to BODY
# Check: every interactive element reachable? Focus ring visible? Order logical?

# Try activating elements via keyboard
browse press Enter                       # Should activate focused button
browse snapshot                          # Verify the action happened

Browser Recipes for UI Testing

Copy-paste recipes using the browse CLI for deterministic UI checks. Works with both local and remote browsers.

Important: browse eval does not support top-level await. Use .then() for async operations, or split into multiple eval calls.

Accessibility Audit (axe-core)

Two-step recipe (load script, then run):

browse open "TARGET_URL"
browse wait load

# Step 1: Load axe-core
browse eval "const s = document.createElement('script'); s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js'; document.head.appendChild(s); 'loading'"

# Step 2: Wait for script to load
browse wait timeout 3000

# Step 3: Run audit
browse eval "axe.run().then(r => JSON.stringify({ violations: r.violations.map(v => ({ id: v.id, impact: v.impact, description: v.description, nodes: v.nodes.length, help: v.helpUrl })), passes: r.passes.length, incomplete: r.incomplete.length }))"

Interpret results:

• impact: "critical" or "serious" = must fix
• impact: "moderate" or "minor" = should fix
• Check helpUrl for remediation guidance

Performance Metrics

browse open "TARGET_URL"
browse wait load
browse eval "
  const nav = performance.getEntriesByType('navigation')[0];
  const paint = performance.getEntriesByType('paint');
  JSON.stringify({
    domContentLoaded: Math.round(nav?.domContentLoadedEventEnd),
    loadComplete: Math.round(nav?.loadEventEnd),
    firstPaint: Math.round(paint.find(p => p.name === 'first-paint')?.startTime),
    firstContentfulPaint: Math.round(paint.find(p => p.name === 'first-contentful-paint')?.startTime),
    transferSize: nav?.transferSize,
    domInteractive: Math.round(nav?.domInteractive),
  });
"

Thresholds (Doherty Threshold + Web Vitals):

• FCP < 1.8s = good, < 3s = needs improvement, > 3s = poor
• Load complete < 3s = good for SaaS dashboards
• DOM interactive < 400ms = feels instant (Doherty Threshold)

Broken Images

browse open "TARGET_URL"
browse wait load
browse eval "
  const imgs = Array.from(document.querySelectorAll('img'));
  const broken = imgs.filter(i => !i.complete || i.naturalWidth === 0);
  JSON.stringify(broken.map(i => ({ src: i.src, alt: i.alt })));
"

Console Errors

Important: Injecting on about:blank then navigating wipes the capture (different page context). Instead, use one of these approaches:

Method 1: Check failed resources on page load (deterministic)

browse open "TARGET_URL"
browse wait load
browse eval "JSON.stringify(performance.getEntries().filter(e => e.entryType === 'resource' && e.responseStatus >= 400).map(e => ({ url: e.name, status: e.responseStatus })))"

Method 2: Capture runtime errors during interaction

browse open "TARGET_URL"
browse wait load

# Inject capture on the page itself
browse eval "window.__logs = []; const orig = { error: console.error, warn: console.warn }; console.error = (...args) => { window.__logs.push({type:'error', text: args.join(' ')}); orig.error(...args); }; console.warn = (...args) => { window.__logs.push({type:'warn', text: args.join(' ')}); orig.warn(...args); }; window.addEventListener('error', e => window.__logs.push({type:'uncaught', text: e.message})); window.addEventListener('unhandledrejection', e => window.__logs.push({type:'rejection', text: String(e.reason)})); 'installed'"

# Interact with the page (clicks, form submits, etc.)
browse click @some-ref
browse eval "JSON.stringify(window.__logs)"

This captures errors that occur during interaction, not on initial load. For initial load errors, use Method 1.

Keyboard Navigation

Tab through all focusable elements and record the order:

# Start on the page
browse open "TARGET_URL"
browse wait load

# Tab through elements one at a time
browse press Tab
browse eval "JSON.stringify({tag: document.activeElement?.tagName, text: document.activeElement?.textContent?.trim().slice(0,40), role: document.activeElement?.getAttribute('role'), ariaLabel: document.activeElement?.getAttribute('aria-label'), hasFocus: (() => { const s = window.getComputedStyle(document.activeElement); return s.outlineStyle !== 'none' || s.boxShadow !== 'none'; })()})"

# Repeat browse press Tab + eval to build the full tab order
# Stop when activeElement returns BODY (looped back)

What to check in the results:

• Every interactive element should appear in the tab order
• Order should follow visual layout (top-to-bottom, left-to-right)
• hasFocus should be true for every element (visible focus ring)
• No elements should be skipped or appear out of order

Responsive Screenshot Sweep

browse open "TARGET_URL"
browse wait load

# Mobile (iPhone SE)
browse viewport 375 812
browse wait timeout 1000
browse screenshot --path /tmp/mobile.png --full-page

# Tablet (iPad)
browse viewport 768 1024
browse wait timeout 1000
browse screenshot --path /tmp/tablet.png --full-page

# Desktop
browse viewport 1440 900
browse wait timeout 1000
browse screenshot --path /tmp/desktop.png --full-page

After capturing, read each screenshot with the Read tool and evaluate:

• Mobile: is there a hamburger menu? Are touch targets ≥44px? Does content overflow?
• Tablet: does the layout adapt or just shrink? Is the sidebar behavior correct?
• Desktop: is content width reasonable? Not stretched edge-to-edge?

Check All Links

browse open "TARGET_URL"
browse wait load
browse eval "
  const links = Array.from(document.querySelectorAll('a[href]'));
  JSON.stringify(links.map(a => ({
    href: a.href,
    text: a.textContent?.trim().slice(0, 50),
    isExternal: !a.href.startsWith(location.origin),
    opensNewTab: a.target === '_blank'
  })));
"

Check Form Structure

browse open "TARGET_URL"
browse wait load
browse eval "
  const forms = Array.from(document.querySelectorAll('form'));
  JSON.stringify(forms.map(f => ({
    action: f.action,
    method: f.method,
    inputs: Array.from(f.querySelectorAll('input,select,textarea')).map(i => ({
      name: i.name, type: i.type, required: i.required,
      hasLabel: !!(i.labels?.length || i.getAttribute('aria-label') || i.getAttribute('aria-labelledby')),
      placeholder: i.placeholder
    }))
  })));
"

Check Empty State

Navigate to a page/section with no data and screenshot it:

browse open "TARGET_URL"  # e.g., /sessions with no sessions
browse wait load
browse screenshot --path /tmp/empty-state.png --full-page
browse snapshot  # check if there's helpful text/CTA

Evaluate: does it have a message? An illustration? A CTA to create the first item? Or is it just blank?

Design Consistency

Check whether changed UI is visually consistent with the rest of the app. This catches "it works but looks wrong" — mismatched spacing, colors, border radii, component styles.

If references/design-system.md exists

The user has documented their design tokens and conventions. Use it as ground truth. (See references/design-system.example.md for the expected format.)

# Read the design system
cat references/design-system.md
# or: cat .claude/skills/ui-test/references/design-system.md

# Then screenshot the changed page and check against documented patterns
browse screenshot
# Compare: does spacing match the grid? Are colors from the palette? Correct font weights?

Flag any deviation from the documented system as a STEP_FAIL:

STEP_FAIL|design-spacing|design system specifies 8px grid → new modal uses 6px gap
STEP_FAIL|design-button|design system: destructive buttons use outline style → new delete button uses filled red

If no design system exists — learn from the app

Before testing the changed page, screenshot 2-3 unchanged pages to establish a baseline:

# Step 1: Capture baseline from existing pages
browse open http://localhost:3000/
browse screenshot
# Note: spacing rhythm, border radii, font sizes, button styles, color palette

browse open http://localhost:3000/settings  # or any other established page
browse screenshot
# Note: same patterns — confirm consistency

# Step 2: Now visit the changed page
browse open http://localhost:3000/changed-page
browse screenshot
# Compare against baseline: does it match the established patterns?

Look for:

• Spacing rhythm — does the new UI use the same gaps/padding as existing pages?
• Border radius — rounded-sm vs rounded-md vs rounded-lg consistency
• Button styles — same primary/secondary/destructive patterns?
• Typography — same heading sizes, font weights, body text size?
• Color usage — same palette? Same semantic colors (red=error, green=success)?
• Component patterns — if other pages use inline confirms, does the new page use a modal instead?

Report as structured findings:

STEP_PASS|design-consistency|new sidebar uses same border-l, bg-white, and shadow pattern as existing sidebar on /sessions
STEP_FAIL|design-inconsistency|existing pages use rounded-lg on cards → new component uses rounded-sm

Design consistency is a visual judgment — the weakest assertion type. Always be specific about what you're comparing (which page, which element, which property).

Design System Reference (Example)

This is an example. Copy this file to design-system.md and replace with your own design tokens. The ui-test skill uses design-system.md (not this file) as ground truth for visual consistency checks.

>

```bash

cp references/design-system.example.md references/design-system.md

# Then edit design-system.md with your brand's values

```

---

Below is the Browserbase design system as a reference for the expected format and level of detail.

Brand Colors

brand-primary: #F03603   (Bright orange-red — main brand color)
brand-blue:    #4DA9E4   (Active/running states)
brand-yellow:  #F4BA41   (Warnings, highlights)
brand-purple:  #9C71F0   (Accents)
brand-pink:    #EC679B   (Accents)
brand-green:   #90C94D   (Success/completed)
brand-black:   #100D0D   (Text, hover states)
brand-gray:    #514F4F   (Borders, secondary text)
brand-white:   #F9F6F4   (Warm off-white backgrounds)

Semantic Color Usage

UI Elements

• Primary actions: brand-primary (#F03603)
• Hover on primary: brand-black (#100D0D)
• Text on primary: White (#FFFFFF)
• Borders: brand-gray (#514F4F) or gray-200 (#edebeb)
• Backgrounds: White (#FFFFFF) or brand-white (#F9F6F4)

Typography

• Body: Inter 400/500/600/700 (Google Fonts)
• Display/Brand: PP Supply Sans (custom, loaded via woff2)
• Code: JetBrains Mono (monospace)
• Body text size: 14px (text-sm) is the standard
• Labels: 14px medium (text-sm font-medium)
• Badges: 12px semibold (text-xs font-semibold)

Border Radius

Tiered system based on --radius: 6px:

Spacing

4px base unit. Common patterns:

• p-2 / px-2 / py-2 — 8px
• p-3 / px-3 / py-3 — 12px (very common)
• p-4 / px-4 / py-4 — 16px (very common)
• gap-2 — 8px, gap-3 — 12px, gap-4 — 16px

Component Patterns

Buttons

Sizes: default=40px (h-10), sm=36px (h-9), lg=44px (h-11), icon=40x40

Inputs

• Height: 40px (h-10)
• Border: border border-brand-gray (#514F4F)
• Radius: rounded-sm (4px)
• Padding: px-3 py-2
• Focus: ring-2 ring-ring ring-offset-2

Badges

• Radius: rounded-[2px] (2px)
• Padding: px-2.5 py-0.5
• Font: text-xs font-semibold

Cards

• Radius: rounded-sm (4px)
• Border: border border-gray-200
• Padding: p-4

Status Dots

• Size: h-2 w-2
• Shape: rounded-full
• Color: matches semantic status colors above

Focus States

All interactive elements:

focus-visible:outline-none
focus-visible:ring-2
focus-visible:ring-ring
focus-visible:ring-offset-2

Disabled States

disabled:pointer-events-none
disabled:cursor-not-allowed
disabled:opacity-50

Visual Principles

• Borders over shadows — Browserbase prefers borders for visual separation, not box-shadow
• Sharp brand edges — Brand-specific CTAs use rounded-none (sharp corners)
• Warm neutrals — Off-white (#F9F6F4) not pure white for backgrounds
• Class-based dark mode — .dark class on <html> element
• 4px spacing grid — All spacing should be multiples of 4px

Exploratory Testing

Exploratory testing is agent-driven: you navigate the app freely using browse commands, making decisions about what to click, what to try, and what looks wrong — like a human QA tester.

How It Works

Unlike test suite execution (structured tests against specific routes), exploratory testing is open-ended. The agent uses browse snapshot to understand the page, makes a judgment call on what to do next, acts, and observes the result.

Workflow

1. browse open "TARGET_URL"
2. browse snapshot          → understand what's on the page
3. browse screenshot        → see what it looks like (Read the screenshot)
4. Decide: what looks wrong? What should I try?
5. browse click/fill/press  → interact
6. browse snapshot          → observe result
7. Repeat 4-6, navigating through the app freely

What to Look For

First Impressions (30 seconds)

• Is the purpose of this page immediately clear?
• Is there a clear visual hierarchy?
• Does anything look broken, misaligned, or out of place?
• Are there any console errors? (browse eval "JSON.stringify(window.__logs || [])")

Navigation Test

• Can you reach every major section from the current page?
• Does the back button work?
• Are breadcrumbs accurate?
• Are there any dead ends (pages with no way to navigate away)?
• Does the logo link to the homepage?

Form Stress Test

• Try submitting empty forms
• Enter extremely long text (200+ characters)
• Enter special characters: <script>alert('xss')</script>, "quotes", emoji 🎉
• Double-click submit buttons rapidly
• Tab through all fields — is the order logical?
• What happens when validation fails? Is the error helpful?

State Persistence

• Fill a form halfway, navigate away, come back — is data preserved?
• Create an item, refresh the page — does it still exist?
• Apply filters, refresh — are filters preserved?
• Open a modal, press Escape — does it close cleanly?

Edge Cases

• What does the page look like with no data (empty state)?
• What happens when you navigate to a URL that doesn't exist (404)?
• What happens with an expired session / no auth?
• Resize the viewport to mobile — does it still work?

Performance Perception

• Does the page feel fast or sluggish?
• Are there loading indicators for slow operations?
• Does content pop in or load smoothly?

Exploratory Testing Report Format

For each finding:

FINDING: [brief description]
SEVERITY: critical / high / medium / low
ROUTE: /path/where/found
EVIDENCE: [screenshot path or snapshot excerpt]
RECOMMENDATION: [specific fix suggestion]

Example:

FINDING: Settings page — "Regenerate API Key" button has no confirmation dialog
SEVERITY: high
ROUTE: /orgs/:slug/:projectId/settings/general
EVIDENCE: Clicked "Regenerate" and the key changed immediately with no warning
RECOMMENDATION: Add a confirmation dialog: "This will invalidate your existing key. Are you sure?"

Parallel Testing

Run multiple tests concurrently using named browse sessions. Each named session gets its own independent browser. Use this when you have multiple independent test groups (different pages, different categories) and want faster results.

Works with both local and remote mode. Named sessions are fully independent — each has its own browser process.

How sessions work

The --session flag (or BROWSE_SESSION env var) gives each browse command its own isolated browser:

# Session "signup" gets its own browser
# For localhost/default QA, use clean local mode first
BROWSE_SESSION=signup browse open http://localhost:3000/signup --local

# Session "dashboard" gets a completely separate browser
BROWSE_SESSION=dashboard browse open http://localhost:3000/dashboard --local

# They don't share state — each has its own page, cookies, refs

Local mode variants follow the CLI contract:

• browse open <url> --local — clean isolated local browser (default; preferred for reproducible localhost testing)
• browse open <url> --auto-connect — auto-discover an existing debuggable local Chrome (use only when a test needs existing local login/cookies/state)
• browse open <url> --cdp <port|url> — explicit CDP attach to a specific local browser target

When to use parallel vs sequential

Phase 1: Group tests by independence

After generating your test plan (from Workflow A), or identifying pages to test (Workflow B), group tests that can run in parallel:

Parallel Groups (from diff-driven test plan)
=============================================
Group 1 (session: signup)     → /signup form validation (happy + adversarial)
Group 2 (session: dashboard)  → /dashboard empty state + data display
Group 3 (session: a11y)       → /settings accessibility audit (axe-core + keyboard)

Rule: tests within a group run sequentially. Groups run in parallel.

Phase 2: Launch parallel agents

Use the Agent tool to fan out. Each agent gets a unique session name and runs its test group independently:

Launch agents in parallel (use Agent tool with multiple invocations in one message):

Agent 1 — prompt: "Run signup form tests using BROWSE_SESSION=signup.
  Start with `BROWSE_SESSION=signup browse open <localhost URL> --local`. Run these tests: [list tests].
  Follow the before/after assertion protocol.
  On any STEP_FAIL, immediately take a screenshot:
    BROWSE_SESSION=signup browse screenshot --path .context/ui-test-screenshots/signup-<step-id>.png
  Return structured STEP_PASS/STEP_FAIL markers (include screenshot path for failures).
  Run `BROWSE_SESSION=signup browse stop` when done."

Agent 2 — prompt: "Run dashboard tests using BROWSE_SESSION=dashboard.
  Start with `BROWSE_SESSION=dashboard browse open <localhost URL> --local`. Run these tests: [list tests].
  Follow the before/after assertion protocol.
  On any STEP_FAIL, immediately take a screenshot:
    BROWSE_SESSION=dashboard browse screenshot --path .context/ui-test-screenshots/dashboard-<step-id>.png
  Return structured STEP_PASS/STEP_FAIL markers (include screenshot path for failures).
  Run `BROWSE_SESSION=dashboard browse stop` when done."

Agent 3 — prompt: "Run accessibility audit using BROWSE_SESSION=a11y.
  Start with `BROWSE_SESSION=a11y browse open <localhost URL> --local`. Run these tests: [list tests].
  Follow the before/after assertion protocol.
  On any STEP_FAIL, immediately take a screenshot:
    BROWSE_SESSION=a11y browse screenshot --path .context/ui-test-screenshots/a11y-<step-id>.png
  Return structured STEP_PASS/STEP_FAIL markers (include screenshot path for failures).
  Run `BROWSE_SESSION=a11y browse stop` when done."

Critical rules for parallel agents:

• Every browse command in the agent MUST be prefixed with BROWSE_SESSION=<name>
• If the target URL is localhost/127.0.0.1, each agent should start with browse open <url> --local for clean/reproducible runs
• Use browse open <url> --auto-connect only when the test explicitly needs existing local Chrome state
• Each agent must call browse stop when done (with its session name)
• Pass the full test steps and assertion protocol to each agent — they don't have the skill context
• Include the before/after snapshot pattern in each agent's prompt
• Tell each agent to mkdir -p .context/ui-test-screenshots and save screenshots on failure with the naming convention <session>-<step-id>.png

Phase 3: Collect and merge results

As agents complete, collect their STEP_PASS/STEP_FAIL markers and merge into one report:

## UI Test Results (Parallel Run)

### Group: signup (session: signup)
STEP_PASS|valid-email|heading "Welcome!" appeared after submit
STEP_PASS|empty-submit|validation error shown for empty form
STEP_FAIL|double-submit|expected single submission → two success toasts appeared|.context/ui-test-screenshots/signup-double-submit.png

### Group: dashboard (session: dashboard)
STEP_PASS|empty-state|"No items yet" message with CTA displayed
STEP_PASS|data-display|table rendered 5 rows with correct columns

### Group: a11y (session: a11y)
STEP_FAIL|axe-audit|expected 0 violations → 2 critical: color-contrast, missing-label|.context/ui-test-screenshots/a11y-axe-audit.png
STEP_PASS|keyboard-nav|all 12 elements reachable via Tab

---
**Summary: 5/7 passed, 2 failed (across 3 parallel sessions)**
Failed: double-submit (signup), axe-audit (a11y)

Screenshots: `.context/ui-test-screenshots/`
- signup-double-submit.png — duplicate toast after rapid submit
- a11y-axe-audit.png — page showing color contrast and missing label violations

Parallel with cookie-sync (authenticated pages)

If testing authenticated pages, sync cookies once and share the context ID across sessions:

# Sync once
node .claude/skills/cookie-sync/scripts/cookie-sync.mjs --domains staging.app.com
# Output: Context ID: ctx_abc123

# Each named browse session attaches to its own Browserbase session with the same context ID.
SETTINGS_JSON="$(browse cloud sessions create --context-id ctx_abc123 --keep-alive)"
SETTINGS_ID="$(echo "$SETTINGS_JSON" | jq -r .id)"
SETTINGS_CDP="$(echo "$SETTINGS_JSON" | jq -r .connectUrl)"
BROWSE_SESSION=settings browse open https://staging.app.com/settings --cdp "$SETTINGS_CDP"

PROFILE_JSON="$(browse cloud sessions create --context-id ctx_abc123 --keep-alive)"
PROFILE_ID="$(echo "$PROFILE_JSON" | jq -r .id)"
PROFILE_CDP="$(echo "$PROFILE_JSON" | jq -r .connectUrl)"
BROWSE_SESSION=profile browse open https://staging.app.com/profile --cdp "$PROFILE_CDP"

Cleanup

Always stop all sessions when done, even if a test fails:

BROWSE_SESSION=signup browse stop 2>/dev/null
BROWSE_SESSION=dashboard browse stop 2>/dev/null
BROWSE_SESSION=a11y browse stop 2>/dev/null
browse cloud sessions update "$SETTINGS_ID" --status REQUEST_RELEASE 2>/dev/null
browse cloud sessions update "$PROFILE_ID" --status REQUEST_RELEASE 2>/dev/null

UX Heuristics for AI-Powered UI Testing

These heuristics guide the LLM when evaluating screenshots and page interactions. Five evaluation frameworks targeting SaaS applications, dashboards, and internal tools.

---

1. Laws of UX (Behavioral & Cognitive)

Fitts's Law

Principle: The time to reach a target is a function of distance and size. What to check:

• Primary CTAs should be the largest clickable elements in their section
• Destructive actions (delete, cancel) should NOT be larger than constructive ones
• Mobile tap targets must be at least 44x44px (Apple HIG) / 48x48px (Material)
• Navigation items should have generous padding, not just text-sized hit areas
• Form submit buttons should be full-width on mobile
• Frequently used actions should be closer to the user's current focus area

Hick's Law

Principle: Decision time increases with the number and complexity of choices. What to check:

• Navigation menus with more than 7±2 items should be grouped/categorized
• Settings pages with many options should use sections/tabs, not a flat list
• Modals should present one clear action, not multiple competing choices
• Dropdown menus with 15+ items should have search/filter
• Onboarding flows should not present all options at once
• Action menus (right-click, "more" menus) should be organized by frequency of use

Miller's Law

Principle: Working memory holds approximately 7±2 items at once. What to check:

• Long lists should be chunked into groups of 5-9 items
• Phone numbers, credit cards, and codes should be visually grouped
• Dashboards should prioritize 3-5 key metrics, not show everything
• Sidebar navigation should group related items under headings
• Multi-step wizards should show no more than 5-7 steps

Jakob's Law

Principle: Users spend most of their time on OTHER sites and expect yours to work the same way. What to check:

• Login forms should have email/username on top, password below, submit at bottom
• Logo should link to homepage/dashboard
• External links should be visually distinguished or open in new tab
• Back buttons should be top-left
• Search should be in the header area
• Settings gear icon should lead to settings
• User avatar/menu should be top-right
• Sidebar navigation on the left, content on the right

Aesthetic-Usability Effect

Principle: Users perceive aesthetically pleasing designs as more usable. What to check:

• Consistent border radius across all components
• Unified color palette (not more than 3-4 primary colors + neutrals)
• Consistent spacing rhythm (multiples of 4px or 8px)
• Typography hierarchy is clear (headings > subheadings > body > captions)
• Alignment is consistent (left-aligned text, centered headings, etc.)
• No orphaned elements floating without visual grouping

Doherty Threshold

Principle: Productivity soars when system response is <400ms. What to check:

• System response time < 400ms for user actions
• Loading indicators appear for operations > 1 second
• Optimistic UI updates for common actions (toggle, like, save)
• Skeleton screens for content loading, not just spinners
• No full-page reloads for in-page actions

Von Restorff Effect (Isolation Effect)

Principle: Items that stand out from their peers are more memorable. What to check:

• The most important element on each page is visually distinct
• Pricing page highlights the recommended plan
• Error messages stand out from surrounding content
• New/updated features have visual indicators (badges, highlights)
• Primary action is visually differentiated from secondary actions

Zeigarnik Effect

Principle: People remember incomplete tasks better than completed ones. What to check:

• Multi-step forms show progress indicators
• Onboarding flows show completion percentage
• Profile/settings completion is shown if relevant
• Incomplete tasks are visually distinct from complete ones

---

2. Nielsen's 10 Usability Heuristics

H1: Visibility of System Status

Principle: The system should always keep users informed about what's going on. What to check:

• Current page/section is highlighted in navigation
• Breadcrumbs show where the user is in the hierarchy
• Form submissions show success/failure feedback
• File uploads show progress bars with percentage
• Background operations show status (syncing, saving, processing)
• Active filters/sorts are visually indicated
• "You are here" indicators exist in multi-step flows
• Timestamps show when data was last updated ("Updated 2 min ago")

H2: Match Between System and Real World

Principle: Use language and concepts familiar to the user, not system-oriented terms. What to check:

• Error messages use plain language, not error codes or stack traces
• Labels use domain terminology the user understands
• Icons match real-world metaphors (trash can for delete, etc.)
• Dates use the user's locale format, not ISO/Unix timestamps
• Numbers use appropriate formatting (commas, currency symbols, abbreviations)
• Status labels are meaningful ("Processing payment" not "State: 3")

H3: User Control and Freedom

Principle: Users need a clearly marked "emergency exit" from unwanted states. What to check:

• Undo is available for destructive actions
• Cancel buttons exist on all forms and modals
• Back navigation works and preserves state
• Multi-step flows allow going back to previous steps
• Bulk selections can be cleared with one click
• Filters can be reset to defaults
• Modal/dialog can be closed via Escape key AND clicking outside

H4: Consistency and Standards

Principle: Users should not have to wonder whether different words, situations, or actions mean the same thing. What to check:

• Same action uses same button style everywhere (primary, secondary, destructive)
• Terminology is consistent (don't mix "delete" and "remove" for the same action)
• Icons mean the same thing across the app
• Date/time formatting is consistent throughout
• Table column behaviors are consistent (all sortable or none)
• Empty states follow the same pattern across different sections
• Error message style is consistent (toast, inline, banner)

H5: Error Prevention

Principle: Even better than good error messages is preventing errors in the first place. What to check:

• Destructive actions require confirmation ("Are you sure you want to delete?")
• Form inputs have appropriate constraints (type=email, maxlength, pattern)
• Disabled states prevent impossible actions (can't submit empty form)
• Dangerous buttons are visually distinct (red) and not adjacent to safe ones
• Unsaved changes trigger a "Leave page?" confirmation
• Auto-save is indicated when available
• Input fields show format hints before the user types (placeholder, helper text)

H6: Recognition Rather Than Recall

Principle: Minimize memory load by making objects, actions, and options visible. What to check:

• Recently used items are shown (recent searches, recent files)
• Form fields show current values, not empty fields requiring user to remember
• Navigation labels are visible, not hidden behind icons only
• Search has autocomplete/suggestions
• Contextual help is available where needed (tooltips, info icons)
• Dashboard widgets show labels, not just numbers

H7: Flexibility and Efficiency of Use

Principle: Accelerators for expert users should not encumber novice users. What to check:

• Keyboard shortcuts exist for power users (and are discoverable)
• Bulk actions are available for repetitive tasks
• Search/filter is available on long lists
• Copy-to-clipboard exists for IDs, keys, URLs
• Quick actions exist (inline edit, single-click actions)
• Default values are sensible and save time

H8: Aesthetic and Minimalist Design

Principle: Every extra unit of information competes with relevant information. What to check:

• No redundant information on the page
• Above-the-fold content is the most important content
• Visual noise is minimized (unnecessary borders, dividers, decorations)
• White space is used to create focus
• Secondary information is accessible but not prominent (expandable sections, tooltips)
• Forms only ask for what's truly needed

H9: Help Users Recognize, Diagnose, and Recover from Errors

Principle: Error messages should be expressed in plain language, indicate the problem, and suggest a solution. What to check:

• Error messages explain WHAT went wrong in plain language
• Error messages suggest HOW to fix it
• Form validation errors appear next to the relevant field, not just at the top
• Error states don't lose the user's input (form data preserved after error)
• Network errors offer a retry option
• 404 pages suggest alternatives (search, navigation, homepage link)
• API errors don't leak technical details to the user (no stack traces, no raw JSON)

H10: Help and Documentation

Principle: Help should be easy to search, focused on the user's task, and concise. What to check:

• Contextual help exists for complex features (tooltips, "?" icons, inline hints)
• Onboarding/tour exists for new users
• Empty states include guidance on what to do next
• Documentation links are accessible from within the app
• Error states link to relevant help articles when appropriate

---

3. Error States & Edge Cases

SaaS applications spend 80% of development time on the happy path and 20% on everything else. These checks catch the 80% of user frustration that comes from the "everything else."

Empty States

What to check:

• Every list/table has a designed empty state (not just blank space)
• Empty states explain what this section is for
• Empty states include a CTA to create the first item
• Empty states have an illustration or icon (not just text)
• Search with no results offers suggestions or "try different terms"
• Filtered views with no matches say "No results match your filters" with a clear filter button

Error Boundaries

What to check:

• JavaScript errors don't crash the entire page (error boundary catches them)
• Failed API calls show a meaningful error, not a blank section
• Network disconnection shows an offline indicator
• Timeout errors offer retry
• Authentication expiry redirects to login with a message, doesn't show a broken page
• Partial data load doesn't leave the UI in a half-rendered state

Form Edge Cases

What to check:

• Extremely long text input doesn't break layout (truncation or scroll)
• Special characters in input don't cause errors (quotes, unicode, emoji)
• Pasting content into fields works correctly
• Double-clicking submit doesn't create duplicate entries
• Required field indicators are visible before submission, not just after
• Tab order through form fields follows visual order
• Date pickers handle timezone edge cases
• Number inputs handle negative numbers, decimals, and zero

Loading States

What to check:

• Initial page load has skeleton screens or loading indicators
• Data refresh shows subtle loading indicator (not full-page spinner)
• Long-running operations show progress (not just a spinner)
• Stale data is indicated ("Last updated 5 min ago" or visual dimming)
• Optimistic updates revert gracefully if the server rejects them
• Infinite scroll has a loading indicator at the bottom
• Image loading uses blur-up, skeleton, or placeholder

Permission & Auth Edge Cases

What to check:

• Unauthorized access shows a meaningful message, not a 403 page
• Expired session redirects to login and returns user to where they were
• Role-based UI hides actions the user can't perform (not just disables them)
• Shared links work for users with appropriate permissions
• "Access denied" messages suggest who to contact for access

---

4. Data Display Heuristics

SaaS apps are data-heavy. Tables, charts, dashboards, and lists are where users spend most of their time. These are the most common sources of visual bugs and usability issues.

Tables

What to check:

• Column headers are clear and concise
• Columns are appropriately sized (not all equal width)
• Long cell content is truncated with tooltip/expand, not overflowing
• Numeric columns are right-aligned
• Text columns are left-aligned
• Row hover state exists for visual tracking
• Sortable columns are indicated (sort icon)
• Active sort direction is shown (ascending/descending)
• Empty table has a designed empty state
• Pagination shows total count and current range ("Showing 1-25 of 142")
• Table is keyboard navigable
• On mobile: table scrolls horizontally OR transforms to card layout

Charts & Graphs

What to check:

• Charts have clear titles and axis labels
• Legend is visible and matches chart colors
• Tooltips show exact values on hover
• Zero-data state shows a message, not an empty chart
• Color palette is accessible (not relying solely on color to distinguish series)
• Y-axis starts at zero for bar charts (unless there's a clear reason not to)
• Time-series x-axis has appropriate intervals
• Charts are responsive (don't overflow on small screens)

Dashboard Metrics

What to check:

• Key metrics have labels, values, AND context (trend, comparison period)
• Large numbers use appropriate formatting (1.2K not 1200, $1.5M not $1500000)
• Percentage changes show direction (up/down arrow or color)
• Metrics refresh is indicated (timestamp or refresh button)
• Metric cards have consistent sizing and alignment
• Too many metrics create cognitive overload — prioritize 3-5 key ones

Filters & Search

What to check:

• Active filters are visible and individually removable
• "Clear all filters" button exists when any filter is active
• Filter state persists across page navigation
• Search is responsive (results appear as you type, or after Enter)
• Search handles empty query gracefully
• Filter combinations that yield no results show a helpful message
• Date range filters validate that start < end

Pagination & Infinite Scroll

What to check:

• Total item count is shown
• Current page/position is indicated
• Page size selector exists for tables
• URL updates with page state (shareable/bookmarkable)
• Navigating back preserves scroll position and page
• Infinite scroll has a clear "end of list" indicator
• Loading more items doesn't jump the scroll position

Numbers, Dates & Formatting

What to check:

• Dates use consistent format throughout the app
• Relative dates where appropriate ("3 hours ago" vs "2026-03-24T16:30:00Z")
• Currency values show appropriate symbol and decimal places
• Large numbers are abbreviated consistently (K, M, B)
• Percentages show appropriate precision (don't show 33.333333%)
• Duration formatting is human-readable ("2h 15m" not "135 minutes" or "8100000ms")
• Null/undefined values show a dash or "N/A", not "null" or "undefined" or blank

---

5. Visual Design Checks

Typography

• Body text: 16px minimum on desktop, 14px minimum on mobile
• Line height: 1.4-1.6 for body text
• Heading scale: clear size difference between h1 → h2 → h3
• Maximum line length: 60-80 characters for readability
• No more than 2-3 font families on a page
• Font weight variation is intentional and consistent
• Monospace font used for code, IDs, and technical values

Color & Contrast

• WCAG AA: 4.5:1 contrast ratio for normal text
• WCAG AA: 3:1 contrast ratio for large text (18px+ or 14px+ bold)
• Interactive elements have distinct hover/active/focus states
• Error states use red (or culturally appropriate warning color)
• Success states use green
• Warning states use yellow/amber
• Info states use blue
• Disabled states are visually muted but still readable
• Status colors are consistent throughout the app (same green = same meaning)

Spacing & Layout

• Consistent gutters between grid columns
• Section spacing follows a predictable rhythm
• Related items are closer together than unrelated items (proximity principle)
• Whitespace is intentional, not accidental
• No content touches the edge of the viewport without padding
• Cards/containers have consistent internal padding
• Sidebar width is appropriate (not too narrow to read, not too wide eating content)

Interactive Elements

• All buttons have visible hover states
• All links are distinguishable from regular text
• Form inputs have clear focus states (not just browser default outline)
• Disabled elements look disabled (muted, no pointer cursor)
• Loading buttons show a spinner and prevent double-click
• Toggle/switch states are clearly on vs off
• Dropdown indicators (chevron) point in the correct direction (down when closed, up when open)
• Destructive buttons are visually distinct (red or outlined, not primary style)

---

6. Accessibility Checks

Keyboard Navigation

• All interactive elements reachable via Tab
• Tab order follows visual order (top-to-bottom, left-to-right)
• Focus is visible on all elements (not just browser default — custom focus ring)
• Escape closes modals/dropdowns
• Enter/Space activates buttons
• Arrow keys navigate within component groups (tabs, menus, radio groups)
• Skip-to-content link exists for screen reader users
• Focus is trapped inside open modals (can't Tab to elements behind the modal)
• Focus returns to trigger element when modal closes

Screen Reader

• All images have alt text (or aria-hidden if decorative)
• Form inputs have associated labels (not just placeholder text)
• Headings are hierarchical (no skipping from h1 to h4)
• Landmark regions exist (nav, main, aside, footer)
• Live regions announce dynamic content updates (toast notifications, loading states)
• Modals trap focus and announce their title
• Tables have proper th/td structure and scope attributes
• Custom components (tabs, accordions, dropdowns) have correct ARIA roles

Motion & Reduced Motion

• Respects prefers-reduced-motion media query
• No auto-playing animations that can't be paused
• No flashing content (3 flashes per second max)
• Parallax/scroll-triggered animations have alternatives
• Loading spinners are simple (no complex animations)

Color Independence

• Information is never conveyed by color alone
• Error states have icons AND color (not just red text)
• Charts use patterns/shapes in addition to color
• Status indicators have text labels alongside color dots
• Form validation shows icons (checkmark, X) not just green/red borders