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
npm test is an alias of npm run test:unit.
Unit tests live next to source (packages/**/*.test.ts,
apps/**/*.test.ts, plus scripts/**/*.test.mjs). Integration tests
are *.integration.test.ts under the Vitest integration project.
npm run test:integration starts docker-compose.test.yml (service
postgres, image pgvector/pgvector:pg16, host port 5433, database
corgtex_test) and tears it down afterward. Do not point integration
tests at the local-dev db service on port 5432.
An exported DATABASE_URL overrides the integration-test default. Unset it before
using the local test commands, or explicitly point it to the disposable test
database on port 5433. Never run these tests against a shared or production database.
Do not use prisma db push / npm run prisma:push to prepare a test or
dev database; apply migrations with npm run prisma:migrate:deploy.
What QA expects
A separate agent assesses the integrated outcome against acceptance criteria.
Run relevant checks and reuse sufficient existing coverage and CI results. Add tests
for meaningful uncovered behavior or regressions; source changes do not require a
new test-file edit. Ordinary copy and nonvisual refactors need proportionate checks.
QA blocks concrete behavioral defects or meaningful gaps in evidence. It does not
require repeated suites, speculative edge-case tests, or screenshot proof for APIs.
After fixes, rerun affected checks and reuse the evidence that remains valid.
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:
- Set
AGENT_API_KEY in .env.
- Run
npm run prisma:seed to create the production bootstrap workspace/admin baseline.
- Run
npm run seed:e2e to create the E2E UI user from AGENT_E2E_EMAIL / AGENT_E2E_PASSWORD.
- Start web and worker with
npm run dev (or npm run dev:web if you only need the HTTP API).
- 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 changes visible UI behavior, the delivery owner or QA agent uses
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.