# HTML Testing Checklist
> Generate thorough, interactive HTML testing checklists — a real test plan organized into end-to-end flows, with pass/fail/blocked step states, a progress bar, filter and search, and copyable, syntax-highlighted command snippets. Always ends with a Submit button that returns every step's state and notes for failure triage and fixes. Use whenever the user wants to test, QA, verify, or validate a change, feature, release, PR, or bug-fix batch. Embedded snippets pass a redaction step so credential-shaped values never land in the artifact.
- Skill: `f-labs-io/html-testing-checklist` (Agent Skill)
- Install (CLI): `npx skillmds@latest add f-labs-io/html-testing-checklist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/f-labs-io/html-testing-checklist/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: f-labs-io (https://skillmd.com/u/f-labs-io)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/f-labs-io/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.
## 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.
## 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 `
` 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 `` 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
```json
{
"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
1. **Lead with the failures.** Summarize pass/fail/blocked in one line, then walk each failure: quote the step, the tester's note, and what you can already infer from the code. Offer to investigate and fix — that's the payoff of the round trip.
2. **Blocked ≠ failed.** Blocked steps usually mean an environment or sequencing problem; unblock those first, they often gate several checks.
3. **After fixing, emit a delta re-check**: regenerate the checklist (same filename, overwrite) with the fixed steps marked "re-verify" and everything already passed collapsed — don't make the tester walk 24 steps to re-check 2.
4. **Tracker-backed rows write back.** Follow the loop in "Tracker-backed checklists" above: offer to push each verdict to its ticket, confirm the first outward write, and never mark a ticket done for a step the human didn't pass.
## Secrets and escaping
Snippets come from repos, configs, tickets, and logs — exactly where credentials leak from:
- **Redact before embedding.** Scan every snippet for credential-shaped values: key-ish names (`/(key|secret|token|passw|credential|auth|dsn)/i`), known prefixes (`AKIA`, `ghp_`, `sk-`, `xox`, `AIza`, `eyJ`-JWTs, PEM blocks), URLs with userinfo. Replace the value with a placeholder (``) or an env-var reference (`-H "Authorization: Bearer $API_TOKEN"`), and prefer the env-var form in commands so the step stays runnable. The real value must never appear in the HTML source or the submit payload.
- **HTML-escape every source-derived value** placed into markup or attributes — ticket titles, code, log lines, notes. Escape `& < > " '`; then apply highlight spans. Never place a source value in an HTML comment.
## Anti-patterns
- **A flat 40-row list.** Flows are the point — a flat list makes the tester reverse-engineer the plan you were supposed to write. Flat is acceptable only for a handful of unrelated checks.
- **Steps invented from titles.** "Verify the fix for PROJ-1423" is not a test. Read the diff/thread and write the action, input, and expected result — or flag the step as unverified-by-agent.
- **Auto-ticking or pre-passing steps.** This is a *human* verification pass; the human ticks what they actually observed. Never mark a step passed on their behalf, and never report a fix verified because the artifact was generated.
- **A runtime highlighter or CDN script.** The artifact is self-contained; highlighting happens when you write the file. Escape first, then span.
- **Commands with live credentials.** `curl -H "Authorization: Bearer eyJ…"` in a shareable file is a leak. Redact or use env-var references.
- **A bare checkbox with no fail path.** Pass-only checkboxes throw away the most valuable data. Every step needs fail/blocked states and a notes field that round-trips in the submission.
- **Progress by scroll position or section count.** The bar counts resolved steps, and per-flow sub-bars must agree with the global bar.
- Inventing a third submit mode, inline-rendering instead of writing a real `.html` file, two competing clipboard buttons, or hand-rolling the receiver — see `## Submit pipeline` below.
## Example prompt
> I just merged the checkout revamp (PR #412) and fixed the 9 bugs from the QA board. Build me a testing checklist so I can verify everything before the release goes out.
Output: `checkout-revamp-testing-checklist.html` — three flows ("New user checkout" ~15 min, "Returning user + saved cards" ~10 min, "Flow 0: config & copy checks" ~3 min), 24 steps with copyable commands and expected-output snippets, chips linking steps to the 9 bug indices, sticky progress bar with per-flow sub-bars, search + hide-resolved, and a Submit button that returns every step's state and notes:
```js
submitToClaude({
skill: 'html-testing-checklist',
kind: 'test-results',
data: { title: 'Checkout revamp — release verification', summary: {...}, results: [...] },
version: 1,
});
```
## HTML output foundation
These defaults apply to every artifact this skill produces. A rule above wins on conflict; otherwise they are non-negotiable.
- **Write a real `.html` file to disk** (`-.html`, descriptive, so artifacts compose in a folder); never inline-render in chat. Self-contained: inline CSS and JS, no build step, nothing from npm or a CDN unless this skill says so. Google Fonts via `` is fine; always declare a real fallback stack so the page reads offline.
- **Mobile-responsive**: collapse to a single column under ~700px.
- **Browser storage is for in-progress state only.** `localStorage` is allowed under a per-artifact key prefix (`html-skills:::`) so pages never read each other's state, and masked or secret values are never stored. Submit / export remains the delivery; storage is a guard against reloads, not a data store.
- **Semantic, copyable HTML**: `