---
name: fullstack-functional-qa
description: Functional QA of a whole full-stack app — seed a local database, sweep every API endpoint checking status AND body type, drive the domain engine with scenarios, run the purchase/cart/coupon E2E, then prove persistence with a direct DB read and file an evidence-backed report. Use when Sohail asks for "QA وظيفي حقيقي" / functional QA / API testing / engine + cart E2E, or when a project has no test suite and you must verify behaviour end-to-end yourself. Visual/browser defects belong to web-visual-qa; this skill is the data and logic side.
---

# Full-Stack Functional QA

Class: verify an app's **behaviour**, not its appearance — routes, persistence, domain rules, and
authorisation. The deliverable is a report where every claim carries raw evidence (status code, body
type, DB row, scenario output) plus a numbered bug list. "Everything returned 200" is not a result.

## Order of work

1. **Read before you run.** Route table, schema/seed, and the domain-engine source. Derive the
   endpoint list and the scenario list from the code — never from memory or from the README.
2. **Seed the local DB**, then *verify row counts* with a `select count(*)` per table. A seed that
   "ran with no errors" proves nothing about what landed.
3. **Build and serve the real thing** (`npm run build`, then the local runtime with the DB bound).
   QA the production bundle, not a dev server with different wiring.
4. **Endpoint sweep** recording status **and** the runtime type/shape of every body.
5. **Domain scenarios** fed by rows fetched from the live API (not hand-typed fixtures) — the
   fixtures are exactly where a type bug hides.
6. **E2E** for the money path: cart → coupon → order. Then confirm with a direct `SELECT`.
7. **Closeout:** file one issue per confirmed defect, *then* write the report with the real issue
   URLs, *then* tear down what you started (probe files, dev server). Details below.

## Pitfalls found on real runs — each one costs an hour if you don't know it

- **The DB you seed is not the DB the dev server reads.** Local DB commands and the dev server can
  resolve to *different* content-hashed sqlite files, so your seed succeeds while every query
  returns `no such table`. Diagnose by diffing which file each command touches, then seed the file
  the server actually opens and **re-assert row counts through a live `/api/...` call**, never
  through the seeding CLI.
- **SPA fallback masks unimplemented API routes.** A `/*  /index.html  200` rule answers
  `GET /api/products/<slug>` with HTTP 200 and an HTML body; a status-only sweep scores it green.
  Check `Content-Type` (or `isinstance(body, dict)`) on every JSON route.
- **`JSON.parse` coerces digit-only strings into numbers.** A settings reader that parses stored
  values returns `whatsappNumber` as an `int`; the frontend's `.replace()` then throws and the whole
  SPA renders blank while every endpoint still 200s. **Audit types, not status codes**:
  ```bash
  curl -s localhost:8788/api/settings | python3 -c \
    "import sys,json;d=json.load(sys.stdin);[print(f'{k:18}{type(v).__name__:8}{str(v)[:40]}') for k,v in d.items()]"
  ```
  A blank SPA with green endpoints is this bug until proven otherwise — the browser-side recipe
  (probe page, empty console message, `fetch` interception to prove causality) is in `web-visual-qa`
  → "Blank SPA".
- **Server-authority checks are separate tests from happy-path E2E.** POST an order with a
  client-supplied `total` of 1 for a 1,450-EGP item, and a coupon code that does not exist — both
  were accepted and persisted as-is. Re-read them from the DB; the API's own success response is
  self-serving evidence.
- **Fields the engine never reads.** A coupon object carrying `expiresAt` and `usageLimit` still
  yielded the discount. For every field in a type, either find its reader or report it as
  unenforced — a contract field that nothing checks is a bug, not a fixture.
- **An explainable recommender must actually explain.** A filter engine scored correctly on 8/9
  scenarios while its `reasons` array was always empty, contradicting its own interface doc. Assert
  on the *explanation* output, not just the chosen item.
- **Auth matrix, cheap and non-negotiable:** every `POST /api/admin-*` route with no token (401),
  with a forged token (401), and with a token obtained from a real login (200). One wrong-answer
  login plus one right-answer login proves both branches.
- **GitHub issue numbers are never yours to pick.** I predicted `#9–#15` and pasted those links into
  the report; an earlier audit had already taken `#9` and the real range came back `#10–#16`, so the
  delivered report shipped wrong URLs until I patched it. Create first, read the URLs the CLI prints,
  then write them into the report.
- **Stop only processes you started.** Identify and verify the PID and ownership before stopping it; obtain permission before stopping another process. Check the port in a separate call.
- **A probe file you drop into the served directory ships with the next deploy.** Anything written
  into `dist/` / the build output for testing must be on the teardown checklist, not left to memory.

## Report shape that gets accepted

Endpoint table (method · path · expected · status · body type) · domain-scenario table (input →
chosen id → score → explanation) · E2E with the DB `SELECT` as proof · then a **numbered bug list
ordered by severity**, each with reproduction, observed, expected, and evidence path. State
explicitly what passed and what went untested rather than implying full coverage — an honest
partial report beats an overclaimed complete one.

## Closeout: issues → report → teardown

The bug list is only delivered when it is *filed* and the session is *clean*. Order matters:

1. **Body files, not inline `--body`.** One `/tmp/qa-issue-<n>.md` per bug, then
   `gh issue create --repo <r> --label agent --title "…" --body-file /tmp/qa-issue-<n>.md`.
   Long bodies with backticks, JSON and Arabic make inline `--body "…"` quoting hell. Wrap the
   creates in a shell function with an `echo "--- <n> ---"` marker before each one so the URL each
   call prints maps back to the right bug.
2. **Verify the filing, don't assume it:**
   `gh issue list --repo <r> --label agent --state all` — the count must equal security + functional.
3. **Write the report last.** Paste the URLs the CLI actually returned (see the issue-number pitfall
   above). The report's own issue table should double as the index a fixer reads.
4. **Teardown, and check it in a separate call:**
   ```bash
   rm -f dist/qa-probe*.html            # probe pages in the build output ship next deploy
   kill <verified-own-pid>               # only a process you started
   ```
   Then a *fresh* call: `ss -ltn | grep <port>` and `pgrep -af wrangler`. Confirm the verified process has stopped.

**Evidence from real runs:** `references/elfiky-store-run.md` (sweep + scenario + server-authority
templates and results) · `references/closeout.md` (issue filing loop, bug→issue map, report shape,
teardown transcript and the pkill trap).

## Scope boundary

Screenshots, viewport/RTL audits, layout and console-error forensics for the same app →
`web-visual-qa`. Whole-stack behaviour, types, authorisation and persistence → here.
