Create Manual Test Guide

Create Manual Test Guide

Produce one self-contained HTML file that walks a human tester through verifying an implementation: how to set up, what to do, what to expect, and a checklist that exports its results back as Markdown.

1. Resolve the output directory

The output directory is per-installer configuration, resolved in this order:

1. ${CLAUDE_PLUGIN_ROOT}/config.json → outputDir (shared across this plugin's skills)
2. config.json next to this SKILL.md → outputDir (skill-level override)
3. Neither exists → read config.example.json for the expected shape, ask the user for a real absolute path, then write it to the skill-level config.json (git-ignored) so the question is never asked again.

Honor openAfterGenerate (default true) from the same file.

2. Determine what to test

• The user named a feature, branch, PR, or commit range → use exactly that.
• Otherwise default to the current implementation: git diff $(git merge-base main HEAD)...HEAD on a feature branch, or git diff HEAD for uncommitted work. Confirm with the user if ambiguous.

3. Understand the behavior — derive scenarios from real code

• Read the changed files and trace user-facing entry points (UI routes, API endpoints, CLI commands, config flags) with Grep/Glob.
• Find out how the app is actually launched and configured (README, package scripts, docker-compose, .env examples) — setup instructions must be real commands, not guesses.
• Derive scenarios covering: the happy path per user-visible behavior, edge cases visible in the code (validation limits, empty states, permissions), error handling (invalid input, failures the code explicitly handles), and regression checks for adjacent behavior the change could have broken.
• If prerequisites exist you cannot verify (accounts, external services, seed data), list them explicitly as assumptions rather than inventing steps.

4. Generate the HTML guide

One self-contained .html file: inline <style>, <script>, and SVG — no CDN, no external assets. Write prose in the language the user is conversing in; keep commands, identifiers, and code as-is. Required sections, in order:

1. Header — repo, branch/scope, date, and the feature under test in one sentence.
2. What was implemented — a short overview so the tester knows what the change is supposed to do before testing it.
3. Environment setup — prerequisites, exact launch/build commands in copyable code blocks, required config/seed data, and how to reset state between runs if relevant.
4. Test flow diagram — inline SVG showing the order scenarios should run in and their dependencies (e.g. "create → edit → delete"), so the tester sees the whole session at a glance.
5. Test scenarios — one card/table per scenario: ID, purpose, precondition, numbered steps, expected result per step (side-by-side), and severity if it fails. Include the edge-case and regression scenarios from step 3.
6. Results tracking (interactive) — pass/fail/skip toggle and a free-text notes field per scenario, a progress bar for overall completion, and a "Copy results as Markdown" button that serializes scenario IDs, verdicts, and notes into a Markdown table ready to paste into a PR or chat. Persist state to localStorage so an accidental reload doesn't lose a half-finished session.

5. Save, open, report

• Filename: <repo>-<branch-or-feature-slug>-manual-test-<yyyyMMdd-HHmm>.html in the resolved output directory (create it if missing).
• If openAfterGenerate, open it: start <path> (fall back to explorer.exe <path>).
• Report the saved path, the number of scenarios by category (happy path / edge / error / regression), and any assumptions the tester must satisfy first.

Failure modes

• No user-facing behavior in the scope (pure refactor, docs-only) → say so and ask whether a regression-only guide is still wanted instead of generating filler scenarios.
• Launch method genuinely undiscoverable from the repo → ask the user rather than fabricating setup commands.
• Not in a git repository and no feature named → stop and ask what to test.