Skip to content

Contributing

Tests

The test projects, which command runs which, and the rules for writing new tests.

CirCI's tests run in four kinds of project, each with its own command. This page lists them and the rules new tests follow.

Kind Where Runs in
Node logic and server tests apps/{server,worker}/test, packages/*/test, apps/web/test (*.test.ts) Node, with real migrations on PGlite (no Docker)
Component tests *.browser.test.tsx Headless Chromium through Vitest browser mode
Design system visual tests packages/ui/visual pnpm test:visual, uploaded to a CirCI instance if configured
End to end e2e/ The real Docker stack: Postgres, LocalStack S3, Mailpit, the built image
You changed Write
A rule in packages/core, a helper in lib/ or an api.ts A *.test.ts in the package's test/ folder
A route A server route test with buildServer and app.inject
A service or repository A test under packages/services/test/ or packages/db/test/, on PGlite
A component or a page A *.browser.test.tsx
A bug only the real stack finds A regression test in its owning package, and an end-to-end test if it needs the stack

Pick the smallest command that covers your change.

Terminal window
pnpm test # every Vitest project in one process
pnpm test:node # the Node project
pnpm test:ui # packages/ui
pnpm test:web-browser # apps/web, ui, api, core browser tests
pnpm test:e2e # both end-to-end groups (needs Docker and Chromium)
pnpm test:e2e:api # server, worker and CLI image, no browser
pnpm test:e2e:browser # also the dashboard and the design system

With Turborepo, each test project is its own cached root task (//#test:node, //#test:ui, //#test:web-browser, //#e2e:api, //#e2e:browser), so pnpm gate only reruns what its inputs changed. The two browser tasks each take a quarter of the cores, and a browser test gets one retry for the runner's own lost-frame errors; a retried test still shows in the report.

  • No @testing-library/*. Components get *.browser.test.tsx run in Chromium (vitest-browser-react, page.getByRole, userEvent from vitest/browser). Logic goes in api.ts or lib/ so it's testable in Node. Page tests render through apps/web/test/support/render.tsx.
  • Never import another package's test/ folder.
  • Server route tests build the app with buildServer, use app.inject, and sign in through the real /api/auth endpoints (apps/server/test/support/helpers.ts).
  • External services (GitHub, SMTP, OIDC) are faked at their edge. Say so when something has only been tested against a fake.
  • A bug only the real stack finds gets a regression test in its owning package.
  • A main page test calls expectOnePrimaryPerArea(): at most one primary button per area.
  • End-to-end files that drive Chromium are named *.browser.e2e.test.ts (checked by e2e/test/fakes/e2e-groups.test.ts).

See e2e/README.md for the stack, debugging (E2E_KEEP, E2E_HEADED), sharding and the image build lock.

pnpm gate is the check before a commit; it runs the Node, UI and web browser projects and skips the end-to-end groups, which need Docker (pnpm gate:full adds them). Visual runs are never cached. See Local development.