Skip to main content
We use Vitest for unit and integration tests and the Agent API for broader end-to-end coverage. The canonical list of commands lives in AGENTS.md — this page documents the “why” and the E2E setup.

​
Running Tests

# Static checks (lint + typecheck + prisma validate)
npm run check

# Unit tests
npm run test:unit

# Integration tests (spins up docker-compose.test.yml, runs, tears down)
npm run test:integration

# Everything (unit + integration)
npm run test:all

# A single test file
npx vitest run packages/domain/src/runtime.test.ts
Unit tests live next to source (packages/**/*.test.ts, apps/**/*.test.ts). Integration tests live under the Vitest integration project and require the test Postgres container.

​
What the Reviewer expects

The Reviewer (Codex) rejects a PR if:
  • Domain code under packages/domain/** changed without a corresponding test update.
  • A frontend path changes without actual visual proof linked from the PR body’s Visual Proof section.
  • The plan’s “Test plan” section lists commands that were neither run locally nor covered by CI.
Write tests for new domain logic. Write them alongside the code, not as a follow-up PR.

​
Agent API (E2E)

We do not maintain heavy Cypress / Playwright frontend suites. For backend end-to-end coverage we expose a dedicated Agent API that an external script or the pipeline itself can hit. Setup and credentials are documented in AGENTS.md. Summary:
  1. Set AGENT_API_KEY in .env.
  2. Run npm run prisma:seed to create the production bootstrap workspace/admin baseline.
  3. Run npm run seed:e2e to create the E2E UI user from AGENT_E2E_EMAIL / AGENT_E2E_PASSWORD.
  4. Start the server (npm run dev).
  5. Call /api/... with Authorization: Bearer agent-<AGENT_API_KEY>.
AGENT_API_KEY is runtime authentication configuration for the Agent API, not seed data. The bootstrap agent has ADMIN-equivalent access to allowed workspaces. Wallet-dependent flows (e.g. optimistic finance) require additional setup.

​
Frontend E2E via browser agent

When a PR touches apps/web/app/**, apps/web/components/**, or apps/web/lib/components/**, the Executor logs into the UI using seeded credentials and links a screen recording, screenshot, or CI artifact from the PR body’s Visual Proof section. Preferred proof storage is Corgtex Build Artifacts: capture browser output under ignored .artifacts/, upload it with node scripts/upload-build-artifacts.mjs, and paste the emitted markdown links into the PR. Generated browser artifacts belong under .artifacts/ or in CI artifacts, not under docs/assets/. Credentials live in .env (AGENT_E2E_EMAIL, AGENT_E2E_PASSWORD) — never hardcoded, never in PR descriptions. See the secrets section of AGENTS.md.

​
Production UI smoke

Local seeded E2E credentials and production-safe smoke credentials are separate. If a local browser smoke against https://app.corgtex.com returns a login 401, do not treat that alone as a failed production gate. Check the GitHub Production Smoke Test on main; it uses repo-managed production secrets and is the credential-backed production gate. If a post-deploy health check fails during a deploy window, verify https://app.corgtex.com/api/health against the expected release and rerun the GitHub production smoke. When production has recovered on the failed SHA, use a fix-forward window of up to one hour for smoke-script, deploy timing, or configuration recovery. If production is still red, or the gate is not green or clearly explained within that window, roll back through the auto-revert path. For CRM / Relationships UI proof, use a focused readiness smoke instead of the full route sweep: 
CLIENT_READINESS_ROUTE_NAMES=leads node scripts/client-readiness-smoke.mjs https://app.corgtex.com .artifacts/client-readiness/<slug>
If the focused smoke fails at login, verify the GitHub production smoke before requesting a Chrome-session fallback. Chrome can be used for visual proof only when the credential-backed smoke path is unavailable or explicitly approved.