f-labs-io/agent-html-skills/html-testing-checklist

HTML Testing Checklist

"Please verify this works" usually arrives as a vague worry and leaves as a vague "looks fine". This skill turns it into an artifact: a thorough, walkable test plan — organized into the end-to-end flows a tester actually performs, each step carrying the exact command to run or input to type, what passing looks like, and a tick that advances a real progress bar. When the tester finishes (or gives up for the day), one Submit sends every step's pass/fail/blocked state and notes back to you, so failures become your next work queue instead of a Slack paragraph.

<!-- block:preflight -->

Pre-flight — run BEFORE writing the artifact

Invoke html-skills:html-skills-listen (Skill tool) first; it is idempotent. If it returns a URL, inject it verbatim as window.__CLAUDE_SUBMIT_URL__ in the HTML you are about to write, ?t= query string included (a local, single-session loopback handshake — not a credential). If it reported web/sandbox mode, leave that line out; submitToClaude then falls back to clipboard mode. <!-- /block:preflight -->

When to use this skill

• "Help me test / QA / verify this change (feature, PR, release, migration, bug-fix batch)"
• "What should I check before shipping?"
• "Write me a test plan / verification checklist / regression checklist"
• "I fixed these N bugs — how do I confirm they're all really fixed?"
• Handing work to a tester, reviewer, or teammate who needs to verify results without reverse-engineering the diff

If the user wants to edit or triage data rather than verify software, use html-throwaway-editor. If they want automated tests written, write tests — this skill is for the human verification pass that automated tests don't cover.

Tracker-backed checklists — bug lists are a natural input

A QA queue in an issue tracker is this skill at its best: "test the bugs marked check-QA on the board" should become a smart, two-way HTML checklist rendered from the tracker's real items, not a markdown dump of titles. The round trip runs through the same html-skills-listen receiver as everything else — the page never touches the tracker's API; you hold the credentials and do the writes.

• Pull the real records via the tracker's MCP/tool (Monday, Linear, Jira, GitHub, Asana…) with their stable ids — never make the user retype what you can fetch. Read each item's body and comment thread; that's where the repro steps and expected post-fix behavior live.
• Keep the ticket id on every row — a data-ticket attribute plus a small visible id chip linking back to the tracker — and carry the ids through the submit envelope (results[].tickets).
• Close the loop after Submit. For tracker-backed rows, offer to write each verdict back — mark passed items Done, comment failures with the tester's note — via the tracker's own tool. Confirm before the first outward write, report every write with a link, and never update a ticket for a step the human didn't resolve.
• The board moves — regenerate, don't hand-patch. When the user asks to refresh, re-pull the same view, rebuild the file under the same name, and say what changed (N new, M gone, K still open).

Ground every step in evidence — never invent from titles

A checklist step written from a ticket title or a vague memory of the change is a guess wearing a checkbox. Before emitting rows, read the actual material:

• The diff / PR / commits — what actually changed decides what can actually break. Walk the changed files and derive checks from real behavior changes, not the PR description.
• Ticket bodies and comment threads — for bug-fix batches, the thread usually contains the repro steps, the root cause, and the expected post-fix behavior. That's the test, verbatim; use it.
• The code around the change — callers, feature flags, config, error paths. The best checklist items are the indirect breakages a naive plan misses.
• Exact inputs — collect the real commands, URLs, sample payloads, test accounts, and expected outputs while you read. These become the embedded snippets; a step that says "call the endpoint" is a chore, a step with the curl line ready to copy is a 10-second check.

If you genuinely can't ground a step (no access to the ticket, ambiguous behavior), still emit it but flag it visibly as unverified-by-agent ("derived from the title only — confirm the intent") rather than dressing a guess up as a fact.

Organize into FLOWS — the default, not a flat list

A flat list of N checks makes the tester context-switch on every row. Instead, group steps into end-to-end flows — the coherent journeys a tester walks once, verifying many things in passing. The shape is Flow → Phase → Step:

• Flow — one end-to-end journey ("New user signs up and checks out", "Admin bulk-imports and exports", "Upgrade path from v1 data"). Give each a short title, an estimated time, and a "covers N checks" count. Order flows so the biggest end-to-end run is Flow 1.
• Phase — an ordered stage within a flow ("Setup", "Happy path", "Error handling", "Cleanup"), in the sequence a tester performs them.
• Step — ONE action with ONE verifiable outcome. A step may verify several distinct concerns at once — show them as numbered chips ("verifies #4, #7, #12") that match the appendix indices, so coverage is visible per action.

Rules:

• Every check lands in exactly one primary step. Run a coverage pass before writing the file: anything you couldn't place goes in a visible "unplaced" callout, never silently dropped.
• Prefer fewer, fuller steps — one action verifying three concerns beats three near-identical walks through the same screen. Don't force unrelated checks together.
• Put checks needing special setup (a fresh deploy, a feature flag, seeded data) in a flow-level callout at the top of the flow, not buried in step 7.
• Doc-only / static-eyeball checks (copy, docs, config values) go in a tiny "Flow 0" that needs no running app.
• End with an "All checks" appendix: a table of every check — index, one-line description, flow it lives in, live state — so nothing is hidden inside a step and the tester can audit completeness at a glance.

Step anatomy

Each step renders three labeled lines (style them consistently — Pass green, Watch amber):

• Action — the concrete thing the tester does, with the exact input embedded as a copyable snippet ("run make seed-demo", "paste this payload into the request body"). Fold in the one-line why when the step exists because of a specific fix.
• Pass — exactly what they should see, with an expected-output snippet when output is the evidence.
• Watch (optional) — the known fail signal or caveat ("if the spinner never resolves, the migration didn't run"). Omit when there's nothing real to say.

Each step carries a state control, not a bare checkbox: pending → pass / fail / blocked / skipped. Selecting fail or blocked reveals an inline notes field — the note is the most valuable byte in the whole artifact, since it comes back to you in the submission. Keep the widget one click (segmented buttons beat a dropdown).

Code snippets — syntax-highlighted at build time

Commands, payloads, config fragments, and expected outputs are first-class content here, and they must be readable:

• Highlight at generation time, not runtime. Emit <pre><code> whose tokens are already wrapped in spans (tok-kw, tok-str, tok-num, tok-com, tok-fn, tok-var) that you produce while writing the file. No CDN highlighter (the artifact is self-contained), no runtime regex-highlighting of embedded content (a script pass over untrusted text is an injection surface). You are the tokenizer; HTML-escape first, then wrap spans.
• Theme token colors with CSS variables so both light and dark themes stay readable (WCAG AA in each).
• Every snippet the tester must type or paste gets a copy button wired to the shared copyToClipboard(text, opts) helper — never a hand-rolled navigator.clipboard.writeText.
• Keep snippets to the lines that matter. Ten relevant lines with the changed line visually marked beat an 80-line dump.

Chrome and navigation — a long checklist must stay walkable

• Utilitarian aesthetic: dense, legible, engineering-toned. The foundation's generic-look ban still applies.
• Prominent global progress bar in a sticky header: full-width, live resolved / total count and percentage, role="progressbar" + aria-live="polite". It counts steps in any final state (pass/fail/blocked/skipped), with the pass/fail split visible in the bar's coloring — "how far through am I" and "how bad is it" in one glance.
• Per-flow sub-bars in each flow header, updating together with the global bar.
• Filter/search + "hide resolved" toggle in the sticky header: free-text filter over step and flow titles, live counts, keyboard-reachable with visible focus. / focuses the search box.
• Flow jump-nav (a compact TOC of flows with their sub-progress) and floating up/down arrows for long documents; hide both on print.
• Build every progress bar block-level — track and fill both. The classic failure: an inline <span> used as the track has no box height, so a height:100% fill escapes it and paints as a detached rectangle floating over the page (and empty tracks collapse invisible). Set display: block on the track, use block-level fills, and clip with overflow: hidden. This has bitten a real run; check it before shipping.
• Anchor targets must clear the sticky header. The header (progress bar + filter + flow nav) is tall; without scroll-margin-top on flows and steps, every jump-nav click and j/k scroll lands the target hidden underneath it. Set scroll-margin-top to at least the header's rendered height.
• Keyboard path for heavy use: j/k next/previous step, p/f/b/s set the focused step's state, with a small "?" shortcuts panel.
• Dark/light toggle defaulting to the OS theme. A small celebration when everything passes is welcome — keep it theme-safe and suppressed under prefers-reduced-motion.
• Print must produce a usable paper checklist: states render as symbols (✓ ✗ ⊘ —), snippets don't clip, nav chrome hidden.

Submit envelope

{
  "skill": "html-testing-checklist",
  "kind": "test-results",
  "data": {
    "title": "Checkout revamp — release verification",
    "summary": { "total": 24, "pass": 19, "fail": 2, "blocked": 1, "skipped": 1, "pending": 1 },
    "results": [
      { "id": "f1-p2-s3", "flow": "New user checkout", "step": "Pay with an expired card",
        "status": "fail", "checks": [7, 12], "tickets": ["PROJ-1423"],
        "notes": "error toast never appears; console shows 402 unhandled" }
    ]
  },
  "version": 1
}

results[] carries every step with a non-pending state (partial submits mid-session are normal — the user can Submit as often as they like; treat the latest submission as the current truth). checks are the appendix indices the step covers; tickets (only on tracker-backed rows) are the source ticket ids, so verdicts can flow back to the tracker; notes is the tester's free text on fail/blocked.

When results come back