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

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. 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 delivery owner 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 and never included in PR descriptions. For workspace UI spine changes, visual proof must show the affected shared patterns in context: page header hierarchy, subnav or segmented controls, tables or empty states, mobile layout when relevant, and keyboard focus visibility. The proof should demonstrate that reuse improved or preserved task clarity and density, not merely that screens look more alike.

​
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:
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.