LS-SIEM-LLP/qa-probe

**Find out exactly why your pages are blank - in under 5 minutes.**
qa-probe is a Node.js command-line tool that reads your React frontend, maps every
API call to its backend route, probes those endpoints live with real auth, and tells
you the **root cause** when something is wrong - not just a status code.
It works best on React apps backed by **FastAPI, Express, Next.js, GraphQL, or tRPC**
with an OpenAPI spec available. Built by the LightShield SIEM team and battle-tested
against a production SIEM.
---
The problem it solves
Your dashboard loads. Nothing crashes. But every table is empty, every chart shows
zero, and you have no idea why. The cause is almost always one of:
- The frontend calls /api/users/ but the backend route is /api/users (trailing slash)
- A feature flag (HAS_BILLING=false) silently disabled an entire router
- The database is connected but the table has no rows
- A backend refactor renamed a field and the frontend still reads the old name
- An endpoint is missing its auth guard, or leaks data without a token
qa-probe builds a source-aware map from frontend calls to live backend responses, then
explains each failure in one line with a fix hint. It complements Playwright (user
journeys) and Schemathesis (contract fuzzing) - it is the layer that answers
"why is this page blank?" first.
---
Quick start
1. Install
2. Create a config
qa-probe.config.js in your project root:
3. Run it
qa-probe will parse your frontend, fetch /openapi.json, probe every endpoint with
real auth, and write a full report to .qaprobe/ (report.md, report.json,
ai-context.md, report.html). A summary table prints to the terminal.
---
Understanding the report
**Route status**
| Status | Meaning |
|----------|---------|
| healthy | endpoints respond, data present, schema valid |
| degraded | works but has an issue (empty data, slow response) |
| broken | unreachable, 404, 5xx, or a security/logic failure |
**Common root causes**
| Root cause | What happened | What to do |
|-------------------------|---------------|------------|
| feature_flag_disabled | router not registered (a HAS_* flag is false) | enable the flag and restart |
| contract_mismatch | a similar route exists (slash/casing) | align the frontend path |
| missing_route | 404, not in the OpenAPI spec | fix the typo or include_router() |
| empty_db | 200 OK but empty array | seed the database |
| precondition_required | 428 - terms/onboarding/MFA gate not satisfied | clear the gate for the probe account |
| auth_scope_mismatch | 401/403 - wrong role/scope | use a user with the required permissions |
| schema_mismatch | a field was renamed/removed vs the spec | align frontend, backend, and spec |
| auth_bypass | endpoint returns 200 without auth | add the missing auth guard |
| assertion_failed | response violated a declared invariant | fix the response or the assertion |
| server_error | 5xx | check backend logs |
**Every result is verifiable.** Each diagnosis carries its **evidence** (the request,
a snapshot of the response, timing) and a **confidence** level - high, medium, or
none. A confidence: none / unknown result is explicitly **not** a confirmed pass.
**Score:** each route is 0-100; the overall score is the average. Use
--fail-under 80 to make CI fail when the score drops.
---
Use cases
- **"Why is this page blank?"** - the everyday case. Get a root cause and a fix hint
in one run instead of digging through network tabs and logs.
- **CI gate** - qa-probe run --fail-under 80 blocks a deploy when pages regress.
- **Demo / staging sign-off** - confirm an environment actually works before a customer
call, not just that it returns 200s.
- **Catch contract drift** - a backend refactor renames a field or moves a route;
qa-probe flags the exact endpoint and frontend call affected.