fastapi-qa

QA the current change and capture evidence a reviewer can trust. The point is to run the QA that's valid for this change — a UI tweak needs screenshots, a backend fix needs the endpoint exercised and the suite run, a CLI change needs its commands run. Don't screenshot a database migration; don't run the full browser e2e suite for a one-line helper.

Steps

1. Read CLAUDE.md for how this project builds, runs, and tests, plus any e2e/screenshot tooling it already has. Read any .claude/rules/*.md whose paths: glob covers the changed files — they often name the ports, fixtures, or QA conventions for that layer.

2. See what changed. git diff master...HEAD for the branch's work, plus git diff / git diff --cached for uncommitted edits. Classify each surface the diff touches (a change can span more than one — QA each with its own method):

   • UI / frontend — components, styles, templates, pages, client-side behavior.
   • Backend / API / service — routes, handlers, business logic, jobs, DB.
   • CLI / tool — command entrypoints, flags, output.
   • Library / SDK — importable code with no runtime surface of its own.
   • Docs / config / infra only — no runtime behavior to observe.

3. Run the QA that fits each surface (use fastapi-run whenever you need to bring the app or service up):

   • UI / frontend → capture screenshots. Prefer the repo's own tooling (Playwright, Cypress, Storybook, a visual-test harness) — it already knows how to reach each screen. Otherwise launch the app via fastapi-run and drive a headless browser (Playwright/Puppeteer) if one is installed. Capture the states the change actually affects: the default view, the changed interaction, and empty/error or responsive breakpoints when layout or state handling changed. Grab a before shot from master too when the branch point is cheap to check out, so the diff is visible. Note what changed visually.
   • Backend / API / service → run the test suite and any integration/e2e that covers the area, then exercise the changed path for real: bring the service up, hit the endpoint (curl/httpie/the project's client), and capture the request → response and any relevant log lines.
   • CLI / tool → run the representative commands that exercise the change (not just --help); capture stdout, stderr, and exit codes.
   • Library / SDK → run the unit tests plus a small usage snippet that calls the changed API.
   • Docs / config / infra only → there's nothing to observe at runtime. Say so and stop — don't manufacture QA.

4. Save the artifacts where the user can actually open them — a subfolder named <repo>-<branch> inside their Downloads folder (e.g. myapp-feature-login/), so screenshots land somewhere they'll look. Resolve the destination for the OS you're on:

   • macOS / Linux: ~/Downloads/<repo>-<branch>/
   • Windows: %USERPROFILE%\Downloads\<repo>-<branch>\ (PowerShell: $env:USERPROFILE\Downloads\...)

   Derive <repo> from the repo root's folder name and <branch> from the current branch (git rev-parse --show-toplevel and git rev-parse --abbrev-ref HEAD), replacing any / in the branch with - so it's one valid folder name. Create the folder if it doesn't exist, then write screenshots as PNGs and captured command/HTTP output as text into it — keep artifacts out of the repo tree; they're evidence for a human, not source to commit. If there's no Downloads folder (a headless CI box), fall back to the user's home directory. Report the absolute folder path so the user can find it.

5. Write a QA summary suited to drop into a PR's Test Plan / QA section: which surfaces changed, what QA ran for each, the evidence (screenshot paths, captured output, test results), pass/fail, and anything you could NOT cover and why. Lead with the result, keep it tight.