git:20260509.14d6b51 to git:20260911.22df896

---

name: ui-test

description: >-

Runs UI tests described in plain English by driving real Chrome via the

Claude-in-Chrome extension. Covers end-to-end flows (clicks, forms,

assertions), visual checks (screenshot + optional baseline diff),

accessibility (axe-core), performance (Web Vitals + light Lighthouse-style

metrics), and an interactive --debug mode that tails console + network and

surfaces issues without needing explicit assertions. Accepts inline

descriptions or test files in `./tests/ui/*.md`. Per-run folders contain

artifacts (screenshots, console, network, axe report, perf metrics) plus a

single-file 2026-aesthetic HTML report with a verdict-forward layout. Learns

from per-run feedback — false-positive categories, screenshot strategy,

severity floors, and per-project baselines personalize future runs. Use when

the user wants to verify a UI flow, screenshot a regression, audit

accessibility, profile a page, or debug something visibly broken in a real

browser session.

argument-hint: "<description> | --file <path> | --suite <glob> | --debug <url|description> | record <name> [--env <url>] [--viewport WxH] [--only e2e,visual,a11y,perf] [--baseline] [--verbose]"

disable-model-invocation: true

allowed-tools:

- AskUserQuestion

- Read

- Write

- Edit

- Glob

- Grep

- Bash(mkdir *)

- Bash(ls *)

- Bash(open *)

- Bash(date *)

- Bash(pwd)

- Bash(echo *)

- Bash(curl *)

- Bash(git *)

- Bash(file *)

- Bash(test *)

- WebFetch

- mcp__claude-in-chrome__tabs_context_mcp

- mcp__claude-in-chrome__tabs_create_mcp

- mcp__claude-in-chrome__tabs_close_mcp

- mcp__claude-in-chrome__navigate

- mcp__claude-in-chrome__get_page_text

- mcp__claude-in-chrome__read_page

- mcp__claude-in-chrome__javascript_tool

- mcp__claude-in-chrome__find

- mcp__claude-in-chrome__resize_window

- mcp__claude-in-chrome__form_input

- mcp__claude-in-chrome__read_console_messages

- mcp__claude-in-chrome__read_network_requests

- mcp__claude-in-chrome__browser_batch

- mcp__claude-in-chrome__gif_creator

---

## Preferences

_On startup, use Read to load `~/.claude/skills/ui-test/preferences.md`. If missing, treat as first-run (see First-time detection)._

Defaults when no preferences exist:

- `output-root`: `./test-results/ui-test/` (cwd-relative when in a project; falls back to `~/.claude/skills/ui-test/runs/` outside a project)

- `viewport`: `1440x900` (single) — accepts a comma list for matrix runs (e.g. `375x812,1440x900`)

- `categories`: `e2e,visual,a11y,perf` (debug is a separate mode, not a category)

- `screenshot-strategy`: `per-step` (per-step / on-fail / never)

- `a11y-severity-floor`: `serious` (minor / moderate / serious / critical — anything at-or-above is a failure)

- `perf-budget`: `lcp<=2500,cls<=0.1,inp<=200,js-heap<=50mb` — overridable per-run via `--perf-budget`

- `verbosity`: `verbose-on-failure` (concise / detailed / verbose-on-failure)

- `spec-priority`: `inline-first` (inline-first / project-first / both)

- `auto-baseline`: `true` (record on first run, diff thereafter)

- `auto-open-report`: `true`

- `confirm-plan`: `always` (always / only-multi-step / never)

_Also load `~/.claude/skills/ui-test/feedback-journal.md` if present — surface the one-line `Signal:` from the latest 5 sessions to bias defaults (false-positive categories get pre-deselected, baselines flagged-as-flaky get re-recorded, etc.)._

## Context

_On startup, use Bash to detect: today's date (`date +%Y-%m-%d-%H%M`), the current working directory (`pwd`), whether `./tests/ui/` exists, whether the user is inside a git repo (`git rev-parse --is-inside-work-tree` — silently fail if not), and whether the configured `output-root` exists. Do NOT call any browser tool yet — preflight runs in Step 1._

## Command routing

Check `$ARGUMENTS`:

- **`help`** → display help, stop

- **`config`** → run config flow, stop

- **`reset`** → delete `preferences.md` + `feedback-journal.md` + `sessions/` + `resume-state.md`, confirm, stop

- **`feedback`** → collect ratings on the most recent run (see Feedback section), stop

- **`history`** → list recent run folders with title, verdict, timestamp, stop

- **`setup`** → walk through Claude-in-Chrome extension setup (see Setup section), stop

- **`record <name>`** → take the most recent inline run and persist it as `./tests/ui/<name>.md`, stop

- **`--debug <url|description>`** → enter interactive debug mode (see Debug section), stop

- **`--file <path>`** → load a single project test file and run it

- **`--suite <glob>`** → resolve the glob under `./tests/ui/`, run each match in order

- **anything else** → treat `$ARGUMENTS` as an inline description, run it (Step 1 onward)

## Help

```

ui-test — Drive real Chrome through plain-English UI tests

Usage:

/ui-test "<description>" Inline test, parsed and run

/ui-test --file <path> Run a single ./tests/ui/*.md file

/ui-test --suite "<glob>" Run a glob of project tests

/ui-test --debug "<url|description>" Interactive debug session

/ui-test record <name> Save the last inline run as a project file

/ui-test history List recent runs (verdict + timestamp)

/ui-test feedback Rate the last run (teaches the skill)

/ui-test setup Walk through Chrome extension setup

/ui-test config Set preferences

/ui-test reset Clear preferences + journal + sessions

/ui-test help This help

Per-run flags:

--env <url> --viewport <WxH[,WxH]> --only <csv> --skip <csv>

--baseline (force-record) --perf-budget "lcp<=2000,cls<=0.05"

--a11y-floor <minor|moderate|serious|critical>

--headful-pause (pause for keypress before each navigation)

--record-gif --verbose

--html-report (default on) | --no-html-report (skip the HTML report; print CLI only)

--open-report | --no-open-report (override auto-open-report preference)

Examples:

/ui-test "log in as demo@x.com on staging, expect Dashboard"

/ui-test "homepage <2s load + passes a11y" --env https://acme.com --only perf,a11y

/ui-test --suite "checkout/*.md" --viewport 375x812,1440x900

/ui-test --debug "sidebar disappears on resize at /dashboard"

/ui-test --file tests/ui/login.md --baseline

Output: {output-root}/{YYYY-MM-DD-HHMM}-{kebab-slug}/ contains

report.html, data.json, spec.md, steps/, a11y/, perf/, visual/, sources.md.

Current preferences:

(loaded from preferences.md)

```

## Config

Use AskUserQuestion to collect, in batches of ≤4 per call:

**Batch 1 — Output & viewport**

1. Output root path (default `./test-results/ui-test/`)

2. Default viewport(s) — comma-separated list

3. Auto-open report on completion (true/false)

**Batch 2 — Categories & strictness**

4. Default categories enabled (e2e / visual / a11y / perf — multiSelect)

5. Screenshot strategy (per-step / on-fail / never)

6. a11y severity floor (minor / moderate / serious / critical)

7. Perf budget (free text — `lcp<=2500,cls<=0.1,inp<=200`)

**Batch 3 — Workflow**

8. Spec priority (inline-first / project-first / both)

9. Confirm plan before run (always / only-multi-step / never)

10. Auto-record baseline on first visual run (true/false)

Save to `~/.claude/skills/ui-test/preferences.md`:

```markdown

# /ui-test preferences

Updated: {date}

## Defaults

- output-root: {path}

- viewport: {WxH[,WxH]}

- categories: {csv}

- screenshot-strategy: {per-step|on-fail|never}

- a11y-severity-floor: {minor|moderate|serious|critical}

- perf-budget: {lcp<=...,cls<=...,inp<=...}

- verbosity: {concise|detailed|verbose-on-failure}

- spec-priority: {inline-first|project-first|both}

- auto-baseline: {true|false}

- auto-open-report: {true|false}

- confirm-plan: {always|only-multi-step|never}

## Profile (optional — edit freely)

- Default base URLs by env: staging=, prod=, local=http://localhost:3000

- Standing exclusions (selectors / pages to ignore for visual diff):

- Standing a11y rule overrides (e.g., color-contrast: skip on /admin):

- Trusted slow third-parties (perf budget exclusions):

## Learned

<!-- Auto-appended from feedback over time -->

```

Confirm: "Saved. I'll use this as the baseline — and I'll keep sharpening as you rate runs."

## Reset

Delete `preferences.md`, `feedback-journal.md`, `sessions/`, `resume-state.md` (each via `Bash(test -f ... && rm)` style — graceful on missing). Confirm: "All cleared. Starting fresh on the next run."

## First-time detection

If no preferences file exists, show one warm non-blocking line:

> First time running `/ui-test` — describe a test in plain English, I drive real Chrome via the Claude-in-Chrome extension and produce a per-run folder + single-file HTML report. Run `/ui-test setup` if the extension isn't connected yet, or `/ui-test config` to set defaults — otherwise continue and I'll auto-check the connection.

Then proceed to Step 1 (preflight). After the first successful run, inline-prompt for 1-2 quick prefs (categories, screenshot strategy) — don't force the full config flow.

## Setup — Chrome extension onboarding

When invoked as `/ui-test setup` (or when Step 1 preflight fails and the user asks for help), load `~/.claude/skills/ui-test/reference/setup.md` via Read and walk through it: prerequisites checklist (browser / plan / Claude Code version / extension version), enable steps (`/chrome`, `/mcp`), and a troubleshooting table. Reference: `https://code.claude.com/docs/en/chrome` — fetch via WebFetch if a detail in the local guide looks stale.

After the user says they're set up, run preflight (Step 1). On pass: "Connection good. Paste a test description: `/ui-test \"<description>\"`."

## Workflow

### Step 0 — Load learning context

Read `~/.claude/skills/ui-test/preferences.md` and `~/.claude/skills/ui-test/feedback-journal.md`. Continue silently if either is missing. Extract the latest 5 `Signal:` lines and apply them as biases (e.g., "user keeps flagging color-contrast as false positive on /admin → pre-deselect that rule for this run").

### Step 1 — Preflight (Chrome extension check)

1. Call `tabs_context_mcp`.

2. **Pass** → continue silently to Step 2.

3. **Fail** (any error) → do NOT retry blindly. Stop and show:

```

Hmm — the Claude-in-Chrome extension isn't responding.

Common causes:

• Extension not installed → https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn

• Chrome integration not enabled → run /chrome → "Enable"

• Extension idle → run /chrome → "Reconnect extension"

• First time ever → restart Chrome once after enabling, then retry

Need the full walkthrough? Run: /ui-test setup

```

**One retry allowed**: if the user replies "retry", call `tabs_context_mcp` once more. If still failing, route to `/ui-test setup`.

### Step 2 — Resolve the spec

Decide what to run from `$ARGUMENTS`, honoring `spec-priority`:

- **Inline string** → parse it as the spec (Step 3).

- **`--file <path>`** → load that file, parse its frontmatter (env, viewport, categories) + body.

- **`--suite "<glob>"`** → resolve under `./tests/ui/`, queue each, run sequentially.

- **No argument** → if `./tests/ui/` exists and `spec-priority` is `project-first` or `both`, list project files via Glob and offer them via `AskUserQuestion`. Otherwise prompt: "Describe the test in one or two sentences."

Also extract per-run flags: `--env`, `--viewport`, `--only`, `--skip`, `--baseline`, `--perf-budget`, `--a11y-floor`, `--headful-pause`, `--record-gif`, `--verbose`.

### Step 3 — Build the run plan

Convert the spec into a structured plan:

```

{

title: kebab-slug,

base_url: env || inferred,

viewports: [{w, h}, ...],

categories: filtered by --only/--skip and preference defaults,

steps: [

{ id, kind: "navigate" | "click" | "fill" | "expect" | "wait" | "screenshot",

target: selector | text | role,

value: string | regex,

timeout_ms: 5000,

assertions: [{ type: "text" | "visible" | "url" | "console-clean" | "network-2xx", ... }] }

],

perf_budget: parsed,

a11y_floor: level,

screenshot_strategy: from prefs unless overridden,

}

```

Write it to `spec.md` inside the run folder once Step 5 has created it. The plan is the source of truth — every later step references step IDs.

### Step 4 — Confirm the plan

Honor `confirm-plan` preference:

- `always` → always show

- `only-multi-step` → skip if plan has 1 step + 0 assertions

- `never` → only echo a one-liner: "Running: {title} ({N} steps, {categories})"

Format:

```

ui-test plan — {title}

Base URL: {url}

Viewport: {WxH[, WxH...]}

Categories: e2e ✓ visual ✓ a11y ✓ perf ✓

Steps:

1. navigate → /login

2. fill #email = demo@x.com

3. fill #password = ••••

4. click button[type=submit]

5. expect h1 contains "Dashboard"

6. screenshot full-page

...

Estimated: {N} browser ops, {M} screenshots, ~{seconds}s

[Run] [Tweak] [Skip]

```

`AskUserQuestion`: "Run this plan?" — pre-select `Run` if `Learned` rules don't contradict.

### Step 5 — Create the run folder

Slug: `{YYYY-MM-DD-HHMM}-{kebab-title-max-60-chars}`. Title summarizes the *outcome being verified*, not the URL: `2026-05-08-1430-login-flow-staging`, `2026-05-08-1430-checkout-a11y-mobile`.

```

mkdir -p {output-root}/{slug}/{steps,a11y,perf,visual}

```

**Isolation rule**: only the per-run folder is created/written. Never touch sibling folders. Baselines live at `{output-root}/baselines/{title}/{viewport}/{step}.png` so they're shared across runs of the same test.

### Step 6 — Execute

For each viewport (matrix outer loop), for each step:

1. **Tabs**: call `tabs_context_mcp` once at the start of the run; create a fresh tab via `tabs_create_mcp`. Resize via `resize_window` to the current viewport. Never reuse tab IDs from a prior session.

2. **Navigate**: `mcp__claude-in-chrome__navigate` with the resolved URL.

3. **Action**:

- `click` / `fill` → prefer `find` to locate by role/text first, then `javascript_tool` for the actual interaction (more deterministic than relying on visual coordinates).

- `fill` on real form fields → `form_input` is fine for simple cases.

- `wait` → `javascript_tool` polling with timeout.

4. **Assertion**: `javascript_tool` returns a JSON `{ pass: bool, actual, expected, evidence }`. Auto-assertions every step:

- `read_console_messages` since last step → fail on `error` level unless allowlisted in `Profile`.

- `read_network_requests` since last step → fail on 5xx, optionally 4xx based on prefs.

5. **Screenshot** (per `screenshot-strategy`): use `javascript_tool` to call `html2canvas` (load via CDN if missing, single attempt; fall back to logging the gap) and write the PNG to `steps/{NN}-{stepId}.png`. If a step fails, screenshot regardless of strategy.

6. **Per-step JSON**: append to `data.json` — `{ id, status, duration_ms, screenshot, console, network, assertions }`.

7. **Stop conditions**: a hard-fail step (e.g., navigation failure) halts subsequent steps for that viewport and marks them `skipped`. Other viewports continue.

**Browser dialog rule** (from MCP server instructions): if any step would trigger an alert/confirm/prompt, refuse to run it and mark the step `blocked` with a clear note. Never click elements that may surface a modal — the extension becomes unresponsive.

**Batching**: when many similar reads are needed in a row (selectors, text), prefer `browser_batch` over a serial loop.

**Optional GIF**: if `--record-gif`, wrap the run with `gif_creator` start/stop calls and save to `run.gif`.

### Step 7 — Per-category extras

After the main step loop, run category-specific passes:

- **a11y** — inject axe-core via `javascript_tool`:

```js

const s = document.createElement('script');

s.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.0/axe.min.js';

document.head.appendChild(s);

```

Wait for `window.axe`, run `axe.run()`, write `a11y/violations.json`. Filter by `a11y-severity-floor`. If CDN load fails, log the gap and skip — don't fake-pass.

- **perf** — `javascript_tool` reading `performance.getEntriesByType('navigation')`, `PerformanceObserver` for LCP/CLS/INP, `performance.memory` for JS heap. Combine with `read_network_requests` for waterfall. Write `perf/metrics.json`. Compare against `perf_budget`; mark each metric pass/fail.

- **visual** — for each `screenshot` step: if `auto-baseline=true` and no baseline exists, save as baseline; else compute pixel diff (use `javascript_tool` with a tiny inline diff implementation, or skip diff and just save the new snapshot if diff lib unavailable). Write `visual/{step}.png` + `visual/{step}.diff.png`. Threshold from prefs (default 0.1% pixel delta).

Each category degrades gracefully — a CDN block, a browser quirk, or a missing API does NOT fail the run. It logs the gap in `sources.md` and shows up in the report's "Coverage gaps" panel so the verdict is honest about what was actually checked.

### Step 8 — Verdict and report

Compose verdict per run:

- All steps pass + all categories pass → `PASS — {title}`

- Any e2e step fail → `FAIL — {first-failing-step-summary}`

- Only category fails (a11y/visual/perf) → `PASS WITH ISSUES — {N} categories below bar`

- Coverage gaps prevented a verdict → `INCONCLUSIVE — {gap reason}`

Generate `report.html` (skip if `--no-html-report`). Single self-contained file: inline JS ≤200 lines, no external scripts, CSS variables only, dark + light via `prefers-color-scheme`, mobile-responsive, **bento-grid layout** (12-col grid with mixed-size cards) reflecting current 2026 dashboard trends. Verdict-forward: hero card with verdict pill + screenshot, perf bento row (4 metric cards with conic-gradient rings + sparklines), step timeline with filter chips, a11y panel with severity badges, visual diff strip, coverage panel, footer.

**Skeleton source** — copy the structure and styles from `~/.claude/skills/ui-test/examples/sample-report.html` (a fully-rendered reference with mock data). Replace its hardcoded data with the run's actual values. Load `~/.claude/skills/ui-test/reference/report.md` for the full layout spec and inline-JS responsibilities if more detail is needed.

### Step 9 — CLI summary

Print to terminal (verbosity-aware):

```

ui-test — {title}

{VERDICT} {one-line summary}

Steps: {pass}/{total} passed ({fail} failed, {skip} skipped)

a11y: {N} violations ≥ {floor} ({pass|fail})

perf: LCP {ms}ms · CLS {n} · INP {ms}ms ({pass|fail})

visual: {changed}/{total} snapshots over threshold

Folder: {output-root}/{slug}/

Report: {output-root}/{slug}/report.html

[Open report] [/ui-test feedback] [/ui-test record <name>]

```

If `auto-open-report=true`, run `open {report.html}`.

### Step 10 — Save session log + invite feedback

Append a one-page session log to `~/.claude/skills/ui-test/sessions/{slug}.md`:

```markdown

# {slug}

Date: {timestamp}

Spec: {one-line summary or path}

Verdict: {label}

Failures: {short list}

Categories run: {csv}

Coverage gaps: {csv if any}

```

End with one soft line:

> Run `/ui-test feedback` — even one rating sharpens future runs (esp. flagging false-positive a11y rules or flaky baselines).

## Feedback & learning

When invoked as `/ui-test feedback`:

1. Find the most recent file in `sessions/`. If none, say `No recent run found.` and stop.

2. Print a one-line summary of that session.

3. Ask via `AskUserQuestion` (3-4 questions, one batch — pre-select using `Learned`):

- **Was the verdict right?** (correct / false-positive / false-negative / inconclusive — needed more)

- **Which category misfired (if any)?** (none / e2e / visual / a11y / perf — multiSelect)

- **Screenshot strategy felt:** (just right / too many / too few)

- **Anything to flag for next time?** (free text — flaky selector, baseline regen, perf-budget tweak, env-specific override)

4. Append to `~/.claude/skills/ui-test/feedback-journal.md`:

```markdown

## {slug} — {date}

- Verdict: {label}

- Correctness: {answer}

- Misfiring categories: {csv}

- Screenshot strategy: {answer}

- Notes: {free text}

- Signal: {one-line generalization, e.g., "color-contrast on /admin keeps false-positive — exempt rule"}

```

5. **Promotion rule** — if 3+ sessions show the same `Signal:` (substring match on the key phrase), promote it to `## Learned` in `preferences.md` and mention once: "Noticed {pattern} across recent runs — saving as a standing default."

6. **Drift correction** — if 2 newer sessions contradict a Learned rule, demote it (move to journal with a `Demoted: <reason>` line). Never leave stale rules in Learned.

The journal is human-editable — respect anything the user writes there directly.

## Debug mode (`--debug`)

Invoked as `/ui-test --debug "<url-or-description>"`. Skips the assertion-driven flow; instead, runs an investigative session:

1. Preflight (same as Step 1). If the input is a description without URL, infer or ask once for the URL.

2. Open a fresh tab at the URL. Resize to the configured viewport.

3. Capture a baseline of: full-page screenshot, console (last 100 messages), network (all requests since navigation), DOM stats (node count, deep nesting, common a11y issues spot-check).

4. Loop: ask the user **one** AskUserQuestion at a time — `[Reproduce now]` (waits for the user to act in the browser, then re-snapshots), `[Resize {viewport}]`, `[Run a11y]`, `[Run perf]`, `[Inspect selector]`, `[Tail console for 5s]`, `[Done — write report]`.

5. Each iteration writes deltas to `debug/iter-NN.{png,console.json,network.json}`.

6. On `[Done]`, generate `report.html` (same template, "Debug" verdict variant — focuses on findings, not pass/fail) and a `findings.md` with prioritized issues (Critical / Medium / Low).

7. End with: "Want to convert this into a regression test? Run `/ui-test record <name>`."

Debug mode never asserts and never fails — it surfaces.

## Record mode (`record <name>`)

Invoked as `/ui-test record <name>`:

1. Locate the most recent inline run (or debug session). If none, say so and stop.

2. Generate `./tests/ui/<name>.md` (creating the directory if missing) with:

```markdown

---

title: <Human Title>

env: {base url}

viewport: 1440x900

categories: e2e,a11y

---

# <Human Title>

> Recorded from run {slug} on {date}.

## Steps

1. Navigate to /login

2. Fill #email = demo@x.com

3. ...

## Assertions

- Page contains heading "Dashboard"

- No console errors

- All network requests 2xx-3xx

```

3. Confirm path. Suggest: "Run with `/ui-test --file tests/ui/<name>.md` or include in a suite."

## Filename / folder rules

- Run folder: `{YYYY-MM-DD-HHMM}-{kebab-title}` — title ≤ 60 chars, summarizes the *verification*, not just the URL

- Step file: `{NN}-{kebab-step}.png` — NN zero-padded order

- Baseline: `{output-root}/baselines/{title}/{viewport}/{step}.png` — shared across runs of the same test

- Project test: `./tests/ui/<kebab-name>.md` — never `.test.md` suffix

- Never append `-2`, `-3` for collisions; differentiate by viewport or env

## Principles

1. **Plain English in, structured plan out** — every run materializes a `spec.md` so the user can see exactly what was parsed before anything moves.

2. **Real Chrome, explicit tabs** — always `tabs_context_mcp` first; always create a new tab; never reuse a tab ID from a prior session.

3. **Honest about gaps** — if axe-core's CDN was blocked or a screenshot library failed, the report says so. No fake passes.

4. **Verdict-forward report** — the HTML hero is the verdict, not the data grid.

5. **Per-run isolation** — only the run folder is mutated; baselines live in their own shared folder. Never delete sibling runs.

6. **Stop on dialogs** — refuse to interact with elements that surface alert/confirm/prompt; mark the step blocked rather than freezing the extension.

7. **Graceful degradation** — missing preferences, missing journal, blocked CDN, missing baseline all degrade with a logged gap, not a failure.

8. **Destructive actions need confirmation** — `reset` and `--baseline` (overwrites baselines) print what they'll touch and require a yes.

9. **Learn quietly** — promote a rule to Learned only after 3+ matching signals; demote on 2 contradictions; mention promotions and demotions once.

10. **Stop means stop** — when the user halts mid-run, save `resume-state.md` with the next step ID and invite `/ui-test resume` (future enhancement; not yet a subcommand).

11. **Skill orchestrates, doesn't re-judge** — preserve the user's spec verbatim in `spec.md`; never silently rewrite assertions.