Skip to main content

docs/testing.md

Imported Content​

Final Testing Guide

Prerequisites​

  • Node.js 22+
  • pnpm 9+
  • Docker
  • PostgreSQL client (psql) available for migration scripts

Boot local stack​

pnpm install
pnpm dev:stack

This starts:

  • PostgreSQL/Redis/NATS/OpenSearch (docker compose)
  • AgentField mock on :8081 (local profile only)
  • Status mock on :8090 (local profile only)
  • Gateway API on :8080
  • Outbox and job workers
  • Web app on :3000

Set STOP_INFRA_ON_EXIT=1 when running pnpm dev:stack if you want Docker infra to be stopped automatically on Ctrl+C.

Execute smoke suite​

In another terminal:

pnpm test:smoke

Manual validation checklist​

  • Open http://localhost:3000?workspaceId=<uuid> and verify dashboard/ops/portal views load from API data.
  • Confirm GET http://localhost:8080/health returns dependencies.database = ok.
  • Confirm GET http://localhost:8080/.well-known/engine-status returns a healthy state.
  • Execute one agent run and verify callback updates execution status.
  • Queue import/export jobs and verify status transitions in GET /api/v1/jobs.
  • Verify telemetry ingest appears in GET /api/v1/events/ingest-batches.
  • Verify aggregation endpoints:
    • GET /api/v1/dashboard/summary
    • GET /api/v1/portal/summary
    • GET /api/v1/ops/summary

JWT mode validation​

  1. Generate token:
pnpm jwt:dev
  1. Start gateway with AUTH_MODE=jwt and either JWT_SIGNING_SECRET (HS256) or AUTH_JWKS_URL + issuer/audience (OIDC).
  2. Re-run smoke test with auth header:
AUTH_HEADER="Bearer <token>" pnpm test:smoke

CI release gates​

  • scripts/ci/no-placeholders.sh blocks placeholder/fallback data in production paths.
  • scripts/ci/docs-verify.sh enforces generated docs sync.
  • scripts/ci/security.sh fails on high-severity dependency vulnerabilities.