> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgtex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing

> How to run and write tests in Corgtex.

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`](https://github.com/corgtex/corgtex/blob/main/AGENTS.md)
— this page documents the "why" and the E2E setup.

## Running Tests

```bash theme={null}
# 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.

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>`.

<Warning>
  `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.
</Warning>

## 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:

```bash theme={null}
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.