ProjexCloud — API QA Test Plan

Test environment setup

Bring up the full stack, then exercise the layers in order. The api-gateway auto-runs every SDK migration on first boot — no manual SQL. Only the analytics path (Kafka + ClickHouse) needs --full; the SDK-discovery embedding model runs in-process (no container).

# 1. Full stack up (Postgres + Redis + Kafka + ClickHouse) + seed
./scripts/setup/dev-setup.sh --full --seed        # Windows: ./scripts/setup/dev-setup.ps1 -Full -Seed

# 2. Run all services (gateway, projectors, collectors, discovery, apps)
pnpm dev

# 3. Unit / integration suites (separate terminal) — 97 vitest packages
pnpm test

# 4. API contract tests (gateway must be up) — 691 tests/api_definitions/*.json
#    driven by the ProjexLight runner, wave by wave (W0 -> W8):
#    projexlight_start_api_tests / projexlight_run_api_tests / projexlight_get_api_test_status

# 5. Smoke: every service health endpoint
curl http://localhost:3500/health      # api-gateway
curl http://localhost:3600/healthz     # registry-mcp (discovery)
curl http://localhost:8081/health      # lineage-projector
curl http://localhost:8082/health      # semantic-service
curl http://localhost:8083/health      # pool-federation-runtime

Testing layers: (1) unit/integration pnpm test · (2) service smoke/health · (3) API contract tests over the 691 api_definitions in the wave order below · (4) path checks — discovery, and usage event → ClickHouse rollup + Postgres ledger (needs --full) · (5) deploy artifacts helm lint/template, terraform fmt.

Expected-output contract (all APIs)

Every endpoint returns the standard envelope. QA asserts on this shape plus the HTTP status documented per API:

Success:  { "success": true,  "data": { ... } | [ ... ] }
Error:    { "success": false, "error": "<human-readable reason>" }

Wave order at a glance

Regenerate: python scripts/qa-matrix/enrich_qa_apis.py && python scripts/qa-matrix/build_test_plan.py && python scripts/qa-matrix/build_api_docs.py