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.
Kinds of tests
Section titled “Kinds of tests”| 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 |
Which test do I write?
Section titled “Which test do I write?”| 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 |
Commands
Section titled “Commands”Pick the smallest command that covers your change.
pnpm test # every Vitest project in one processpnpm test:node # the Node projectpnpm test:ui # packages/uipnpm test:web-browser # apps/web, ui, api, core browser testspnpm test:e2e # both end-to-end groups (needs Docker and Chromium)pnpm test:e2e:api # server, worker and CLI image, no browserpnpm test:e2e:browser # also the dashboard and the design systemWith 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.tsxrun in Chromium (vitest-browser-react,page.getByRole,userEventfromvitest/browser). Logic goes inapi.tsorlib/so it's testable in Node. Page tests render throughapps/web/test/support/render.tsx. - Never import another package's
test/folder. - Server route tests build the app with
buildServer, useapp.inject, and sign in through the real/api/authendpoints (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 bye2e/test/fakes/e2e-groups.test.ts).
See e2e/README.md for the stack, debugging (E2E_KEEP, E2E_HEADED), sharding and the image build lock.
Quality gates
Section titled “Quality gates”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.