UI Test

BrowserbaseOfficialCreated by browserbase

Skill
Review and audit
Software development
MIT
Low risk

From the author

AI-powered adversarial UI testing via the browse CLI. Analyzes git diffs to test only what changed, or explores the full app to find bugs. Tests functional correctness, accessibility, responsive layout, and UX heuristics. Use when the user asks to test UI changes, QA a pull request, audit accessibility, or run exploratory testing. Supports local browser (localhost) and remote Browserbase (deployed sites).

— the description by browserbase

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

UI Test is an agentic skill designed to perform adversarial testing on web applications. Rather than simply verifying that features exist, it actively attempts to break them by simulating real-world user behaviors, such as rapid double-clicks, invalid form inputs, and keyboard-only navigation. It supports three primary workflows: diff-driven testing for targeted PR reviews, exploratory testing for general site QA, and parallel testing for high-coverage scenarios. The skill uses the browse CLI to interact with local or remote environments, producing evidence-based reports with screenshots and deterministic checks.

What it does

Analyzes git diffs to focus testing on specific code changes.
Performs adversarial testing including empty states, race conditions, and XSS attempts.
Conducts accessibility audits using axe-core and keyboard navigation checks.
Generates self-contained HTML reports with embedded screenshots for failed tests.
Supports both local development environments and remote deployed sites.
Uses a structured before/after snapshot pattern to verify UI state changes.

When to use it

When you need to validate UI changes in a pull request.
When performing exploratory QA on a new or existing web application.
When auditing a site for accessibility and responsive layout issues.
When you need to identify edge-case bugs that standard unit tests might miss.

Advantages

Adversarial approach finds bugs developers often overlook.
Evidence-based reporting with screenshots simplifies debugging.
Flexible workflows allow for both targeted and broad testing.
Deterministic checks provide objective pass/fail criteria.
Parallel execution reduces total testing time for large applications.

Usage examples

“Test the UI changes in my current branch against the main branch.”: The agent analyzes the git diff, identifies affected components, creates a test plan, and executes adversarial tests to ensure the changes are robust.
“Perform an exploratory QA pass on the staging site.”: The agent navigates the application, tests forms and navigation, checks for accessibility violations, and reports any bugs found.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/browserbase/ui-test/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip ui-test.zip -d .agents/skills
```

Documentation by browserbase

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.

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>

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)

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.
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.
Before/after comparison — snapshot before action, act, snapshot after. Verify the tree changed in the expected way (element appeared, disappeared, text changed).
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

Target	Mode	Command	Auth
`localhost` / `127.0.0.1`	Local	`browse open <url> --local`	None needed (clean isolated local browser by default)
Deployed/staging site	Remote	`browse open <url> --remote`	Browserbase credentials; use contexts where supported

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).

# 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:

File pattern	UI impact	What to test
`.tsx`, `.jsx`, `.vue`, `.svelte`	Component	Render, interaction, state, edge cases
`pages/`, `app/`, `src/routes/**`	Route/page	Navigation, page load, content, 404 handling
`.css`, `.scss`, `*.module.css`	Style	Visual appearance (screenshot), responsive
`form`, `input`, `field`	Form	Validation, submission, empty input, long input, special chars
`modal`, `dialog`, `dropdown`	Interactive	Open/close, escape, focus trap, cancel vs confirm
`nav`, `menu`, `header`	Navigation	Links, active states, routing, keyboard nav
Non-UI files only	None	Skip — report "no UI tests needed"

Phase 2: Map files to URLs

Framework	Default port	File → URL pattern
Next.js App Router	3000	`app/dashboard/page.tsx` → `/dashboard`
Next.js Pages Router	3000	`pages/about.tsx` → `/about`
Vite	5173	Check router config
Nuxt	3000	`pages/index.vue` → `/`
SvelteKit	5173	`src/routes/+page.svelte` → `/`
Angular	4200	Check routing module

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 "[email protected]", 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

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

Placeholder	Value
`{{TITLE}}`	Report title for `<title>` tag (e.g., "UI Test: PR #1234 — OAuth Settings")
`{{TITLE_HTML}}`	Report title for the visible `<h1>`. If a PR URL is available, wrap the PR reference in an `<a>` tag so it's clickable (e.g., `UI Test: <a href="https://github.com/org/repo/pull/1234">PR #1234</a> — OAuth Settings`). If no URL, use plain text same as `{{TITLE}}`.
`{{META}}`	One-line context: date, app URL, user, branch
`{{TOTAL_TESTS}}`	Total STEP_PASS + STEP_FAIL count
`{{AGENT_COUNT}}`	Number of sub-agents that ran
`{{PASS_COUNT}}`	Number of STEP_PASS
`{{FAIL_COUNT}}`	Number of STEP_FAIL
`{{PASS_RATE}}`	Integer percentage (e.g., "92")
`{{RATE_CLASS}}`	`good` (≥90%), `warn` (70–89%), `bad` (<70%)
`{{FAILURES_SECTION}}`	HTML for failed test cards (see below)
`{{PASSES_SECTION}}`	HTML for passed test cards (see below)

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>

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).

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

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.

Check	What it catches	Assertion
axe-core	WCAG violations	`violations.length === 0`
Console errors	Runtime exceptions, failed requests	empty error array
Broken images	Missing/failed image loads	no images with `naturalWidth === 0`
Form labels	Inputs without accessible labels	every input has `hasLabel: true`

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

Discover the app — read package.json to detect the framework, then open the root URL and snapshot to see what's there
Navigate everything — click through nav links, visit every reachable page, note what exists
Test what you find — for each page, apply the adversarial patterns below (forms, modals, navigation, keyboard, error states)
Run deterministic checks — axe-core, console errors, broken images, form labels on every page
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

Category	How	Assertion type
Accessibility	axe-core + keyboard nav	Deterministic (violation count)
Visual Quality	Screenshot + heuristic evaluation	Visual judgment (weakest — note specifics)
Responsive	Viewport sweep + screenshots	Visual + deterministic (overflow check)
Console Health	Console capture eval	Deterministic (error count)
UX Heuristics	Snapshot + Laws of UX + Nielsen's	Structured judgment (cite specific heuristic)
Error States	Navigate to empty/error states	Before/after comparison
Data Display	Snapshot on tables/dashboards	Element match (column count, formatting)
Design Consistency	Screenshot baseline + changed page comparison	Visual judgment (cite specific property)
Exploratory	Free navigation + adversarial testing	Before/after + judgment

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

Be adversarial — try to break things, don't just confirm they work
Every assertion needs evidence — snapshot ref, eval result, or before/after diff
Before/after for every interaction — snapshot, act, snapshot, compare
Screenshot every failure — browse screenshot immediately on STEP_FAIL, save to .context/ui-test-screenshots/<step-id>.png
Deterministic checks first — axe-core, console errors, form labels before visual judgment
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
Always browse stop when done — for parallel runs, stop every named session
Report failures with reproduction steps — action, expected, actual, screenshot path, suggestion
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"

Files

ATTRIBUTION.mdAdded by AutoGineer916 B
EXAMPLES.md23.4 KiB
LICENSE.txt1.0 KiB
README.md4.0 KiB
SKILL.md28.2 KiB
references/adversarial-patterns.md3.6 KiB
references/browser-recipes.md6.5 KiB
references/design-consistency.md2.5 KiB
references/design-system.example.md4.0 KiB
references/exploratory-testing.md2.9 KiB
references/parallel-testing.md7.2 KiB
references/report-template.html9.3 KiB
references/ux-heuristics.md18.0 KiB

references/ux-heuristics.md

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

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

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

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Needs network access, Needs a command-line tool, Needs Node.js

The author says: Requires the browse CLI (`npm install -g browse`). For remote testing: BROWSERBASE_API_KEY and cookie-sync skill.

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

browserbase

Publisher

Browserbase (Official)

Source

browserbase/skills · skills/ui-test · commit 6811ca3

Licence

MIT License (redistribution allowed)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by browserbase.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download ui-test.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by browserbase

UI Test — Agentic UI Testing Skill

How Testing Works

Planning: multiple angles, then execute once

Principles for splitting work

Giving sub-agents a step budget

Reporting

Testing Philosophy

Assertion Protocol

Step markers

Screenshot Capture for Failures

How to verify (in order of rigor)

Before/after comparison pattern

Setup

Avoid permission fatigue

Mode Selection

Local Mode (default for localhost)

Remote Mode (deployed sites via cookie-sync)

Workflow A: Diff-Driven Testing

Phase 1: Analyze the diff

Phase 2: Map files to URLs

Phase 3: Ensure the right code is running

Phase 4: Generate test plan

Phase 5: Execute tests

Phase 6: Report results

Phase 7: Generate HTML report

How to generate

Adversarial Test Patterns

Deterministic Checks

Workflow B: Exploratory Testing

Approach

Tips for exploratory runs

Workflow C: Parallel Testing

Design Consistency

Test Categories

Best Practices

Troubleshooting

Files

references/ux-heuristics.md

UX Heuristics for AI-Powered UI Testing

1. Laws of UX (Behavioral & Cognitive)

Fitts's Law

Hick's Law

Miller's Law

Jakob's Law

Aesthetic-Usability Effect

Doherty Threshold

Von Restorff Effect (Isolation Effect)

Zeigarnik Effect

2. Nielsen's 10 Usability Heuristics

H1: Visibility of System Status

H2: Match Between System and Real World

H3: User Control and Freedom

H4: Consistency and Standards

H5: Error Prevention

H6: Recognition Rather Than Recall

H7: Flexibility and Efficiency of Use

H8: Aesthetic and Minimalist Design

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

H10: Help and Documentation

3. Error States & Edge Cases

Empty States

Error Boundaries

Form Edge Cases

Loading States

Permission & Auth Edge Cases

4. Data Display Heuristics

Tables

Charts & Graphs

Dashboard Metrics

Filters & Search

Pagination & Infinite Scroll

Numbers, Dates & Formatting