🧪 QA Playbook

TrueBalance × TrueCredits Hackathon · June 11–12, 2026 · all teams · deploy playbook · design playbook

Your app demos fine on your laptop — then a judge opens the URL and it spins forever, shows a blank screen, or 500s on the second click. You don't need more features — you need a 20-minute QA pass.

Prime directive — test the user journey through the live app, not just your API. A 200 OK doesn't mean the screen rendered, the button fired, the result is correct, or the page survives a refresh.

Feed it to your Claude session:
Read https://hackathon.afinit.dev/playbooks/qa.md and run a self-QA pass on my app at <my-url> — start with the Quick pass. Find what breaks before the judge does.

Machine-readable original: /playbooks/qa.md · two tiers — quick pass below, full 9-card handbook collapsed at the bottom.

§A · Quick pass — the 20-minute version

The one rule: a green curl is necessary, not sufficient. Open your real deployed URL (https://<your-slug>.hackathon.afinit.dev) in a fresh browser and walk the demo flow end to end. If you only tested in Postman / curl, you have not tested your app.

If the URL shows the "warming up" page, your app isn't on port 8080 yet — fix that via the deploy playbook first.

The 6 checks (~3 min each — each is something a judge will do to you)

  1. Cold-start as a stranger — open your URL in an incognito window: no cached login, no localStorage, no warm backend. First screen loads fast, or hangs / blanks / throws? Judges arrive cold; your laptop is warm. The #1 way live demos die.
  2. Walk the golden path twice — run your headline flow, then do it again without reloading. Stateful bugs (double-submit, "already exists", stale cache, a counter that never resets) surface on run #2 — exactly when you're demoing live.
  3. Happy + one ugly input per step — for every field/button try the happy value and one bad one: empty, huge, emoji, wrong type, the Back button, a double-click. Reject gracefully, never white-screen or 500.
  4. Every screen has empty / loading / error — no spinner-of-death, no blank where data failed, no raw stack trace. Show a loading state, an empty state, and a human error message. (Design playbook move #6 — --tb-text-sub for placeholders, --tb-error for failures.)
  5. Mobile + desktop — judges open links on a phone. Resize to ~390px wide (or use your phone): layout holds, buttons tappable, nothing off-screen? Your demo path must survive both.
  6. Refresh & deeplink survival — hit F5 mid-flow, and paste your "share this" URL into a new tab. Does state survive, or does the user land on a broken / empty screen? Cold-loadable URLs are what judges click.

Got real data wired in? Re-run the golden path against a fresh record, not the one row you've hand-tested all day. The demo always uses a new user.

60-second pre-demo check ✅

Five out of five = demo-proof. Nothing loses a room faster than a blank screen on the judge's first click.

§B · Full handbook — the 9-card engineering self-QA (open when a check needs depth)

Engineer-grade version (modeled on the TFS Deployment & Change cards). At the hackathon you are the QA — the gate is "before a judge clicks it." Use the cards your build touches; a static web demo can skip the adb / prod-ticket bits. Full card detail, AI prompts, and the adb/emulator commands live in the raw /playbooks/qa.md.

Card 1 — API smoke (happy + 1 error)

Goal: happy + one error path of every touched endpoint return the right status + body shape. Trap: a 200 with data.result: "FAIL" / code: 50001 is NOT a pass — read the wrapped body.

Card 2 — E2E on the app (critical — do not skip)

Goal: drive the user journey through the actual app/browser, screenshotting each affected screen. API-only passes don't count. Web app? Your "device" is a browser — cold-load your URL in incognito and walk it (the adb/emulator how-tos in the raw md are for the real TB/TC Android build).

Card 3 — Cross-platform coverage

Goal: for each surface (Android / iOS / Web) that hits the change, decide: test here, inherits, or out of scope. Pass if: every required platform has Card 2 done.

Card 4 — Impact on other features

Goal: list every feature that depends on the touched code/endpoint/shared resource and spot-check each. Pass if: no new failures in any dependent feature.

Card 5 — Backward compatibility

Goal: old clients / API consumers / DB rows keep working — additive API + schema, graceful degrade, tolerant deserializers. Hackathon: mostly N/A for a throwaway; matters only if you extend the real stage backend.

Card 6 — Regression sanity (5-min golden path)

Goal: the 3-5 most critical journeys still work end to end. Pass: zero new failures, known flakes documented.

Card 7 — PR review (gate, shared repo)

Goal: ≥1 human approval + AI review (/ultrareview), no open CRITICAL, CI green — before it's relied on. Hackathon: skip on a throwaway repo; keep it for a real TechSquad/* PR.

Card 8 — Production-hot-path readiness

Goal: flag default OFF, rollback documented, on-call paged, dashboard linked, BCM/TCM/SIM attached. Hackathon: not part of the event — here for when this playbook is reused for real work.

Card 9 — QA / demo handover note

Goal: one note of what you covered, what you tested on, and what you did NOT cover. At the hackathon this is your demo run-sheet — the exact happy path you'll click on stage.

Why Card 2 is the hardest non-negotiable: most change-induced incidents pass API testing but fail app testing — 200 + blank screen from a shape change, a silent backend success behind a UI error, a deeplink to the wrong screen, validation that breaks on a real device. Walking the actual app catches all of these in ~10 minutes.