Checks and E2E
The checks every pull request and push to main runs, how to run the Playwright e2e suite locally and in CI, and how to add a test.
Every pull request runs the same commands you run locally. They need no secrets, so they also run for pull requests from forks.
This page is part of the Deployment documentation.
The Checks
.github/workflows/checks.yml runs four parallel jobs on every pull request and on pushes to main. Deploys run in Workers Builds and don't wait for them, so make all four required in branch protection (Production Deploys).
| Job | Command | Fails on |
|---|---|---|
| Format, lint and types | pnpm check, then regenerates the auth schema and migrations | Formatting, lint errors or warnings, type errors, or apps/web/db out of date with the Better Auth options or db/schema.ts (Database Migrations) |
| Unit tests | pnpm test:unit, pnpm test:smoke | A failing Vitest test, or a pinned CLI (Void, Stripe, Wrangler) whose output the kit's tools no longer understand |
| Build | pnpm build | A package or app that doesn't build |
| E2E | pnpm test:e2e | A failing Playwright spec |
Each job installs with pnpm install --frozen-lockfile on the Node version in .nvmrc (.github/actions/setup), so commit pnpm-lock.yaml with any dependency change. Run pnpm healthcheck before pushing: it fixes what pnpm check would reject.
Unit Tests Locally
pnpm test:unit runs one isolated fork at a time. Each test file exits its process, releasing PGlite's WASM memory and module mocks. Shared workers retain that memory across files. Increase concurrency explicitly with VITEST_MAX_WORKERS=2 pnpm test:unit if your machine has room.
Test observable behavior and failure paths. Avoid assertions on documentation wording, source text or copies of configuration values; those break on harmless edits without proving the feature works. Permission settings and generated output still need checks when they enforce a real contract.
UI unit tests cover submitted fields, allowed actions, validation, error recovery and state-dependent controls. Use fixture messages for conditional copy. Skip static cards, skeleton markup, CSS classes, exact date styles and nested HTML assertions; routine copy and design edits should not require test updates. Keep routing, accessibility and escaping checks tied to meaningful behavior.
Keep one authoritative test for a rule at the layer that owns it. Browser specs exercise docs navigation, invitations, member tables and account switching; unit tests focus on the services and state transitions behind them. Customer-editable demo navigation, billing copy, collection schemas and journey titles do not need snapshot-like unit tests. Real content-file validation and cross-package contracts remain checked.
Dependency updates
Shared package versions live in the pnpm-workspace.yaml catalog. Keep void, @void/react and @void/md on the same release, and match the app's Vite alias with the workspace override. When updating Void or Wrangler, update tooling/mcp-server/src/services/cli-versions.ts and run pnpm test:smoke to verify the CLI output the kit reads.
E2E Locally
pnpm kit:setup --step env --yes # once: apps/web/.env; e2e never writes itpnpm --filter e2e exec playwright install chromium # once per machinepnpm test:e2epnpm test:e2e builds the app and serves the production build on http://localhost:4180, so the CSP and production headers apply. Then it migrates the database and runs apps/e2e/tests/**/*.spec.ts in Chromium.
It runs three configurations, one after the other:
- The main suite, in
hybridaccount mode. - A rebuild with
ACCOUNT_MODE=organizations-onlyfor the specs tagged@organizations-only(apps/e2e/playwright.organizations-only.config.ts; alone:pnpm --filter e2e test:organizations-only). - The billing specs against Stripe test mode (
apps/e2e/playwright.billing.config.ts; alone:pnpm --filter e2e test:billing). They are skipped, with the reason, unless a Stripe test key is set (Billing Troubleshooting).
Each run skips the others' specs. Never run two at once: they all build into apps/web/dist. Each run rebuilds the app, and each replaces playwright-report/. UI mode for those specs: pnpm --filter e2e exec playwright test --ui -c playwright.organizations-only.config.ts.
| Database | When |
|---|---|
| Your running dev database | Something already listens on the port in apps/web/.env's DATABASE_URL (54323 with pnpm db:start). The suite migrates it and writes test data into it. |
| A throwaway in-memory PGlite | Nothing listens there. It starts one on that port and drops it when the run ends. CI always uses this. |
Useful commands:
pnpm --filter e2e exec playwright test theme --workers=1 # one specpnpm --filter e2e exec playwright test --ui # UI modepnpm --filter e2e report # last HTML reportpnpm --filter e2e exec playwright show-trace test-results/<test>/trace.zip # path relative to apps/e2eOn failure, the list reporter prints the failing locator. Screenshots, error-context.md and trace.zip land in apps/e2e/test-results/<test>/, and the HTML report in apps/e2e/playwright-report/. App errors print as [WebServer] lines.
Adding a Test
Put specs in apps/e2e/tests/<area>/<name>.spec.ts, next to a page object <area>.po.ts that owns selectors and waits. The conventions are in apps/e2e/AGENTS.md; the main ones:
- Select by
data-testidand add the attribute to the component when it's missing. - Use web-first assertions (
await expect(…)), neverwaitForTimeout. - Use
clickWhenHydrated()/fillWhenHydrated()fromtests/utils/hydration.tsfor the first interaction on a page. - Give each test fresh state; never depend on test order.
The kit's smoke specs live in apps/e2e/tests/smoke/. Put yours in your own folders, so kit updates don't touch them.
E2E in CI
The E2E job in checks.yml:
- Writes
apps/web/.envwithpnpm kit:setup --step env --yes(fromenv.example, with a generatedBETTER_AUTH_SECRET). - Restores the Playwright browsers from a cache keyed by the Playwright version, or installs Chromium with its system dependencies.
- Runs
pnpm test:e2eagainst an in-memory PGlite. Playwright retries a failed test once, andtest.onlyfails the run. - On failure, uploads
playwright-report/andtest-results/as theplaywright-reportartifact, kept 7 days.
Download the artifact from the failed run's summary page, unzip it, and open a trace with pnpm --filter e2e exec playwright show-trace <path>/trace.zip.
Production Preview
pnpm previewThis builds the app and serves the production Worker locally (vp run preview in apps/web). It passes DATABASE_URL from apps/web/.env (the database void db migrate uses), else from the shell, to the Worker (tooling/scripts/src/preview-env.mjs), so pages that query the database work. It also sets SITE_URL to the preview's own address, http://localhost:4173, unless your shell sets one, so sign-in works (Better Auth only accepts requests from SITE_URL). Extra arguments go to vp preview: pnpm preview --port 4180. Use this rather than a bare vp preview, which never passes DATABASE_URL.
Common Pitfalls
Missing apps/web/.envstops the suite before it starts. Runpnpm kit:setup --step env --yes; e2e never creates the file for you. Don't copyenv.exampleby hand: itsBETTER_AUTH_SECRETis empty on purpose.- Port 4180 is busy (another preview or a previous run): the run fails with "is already used" rather than testing another app. Stop the other process.
- Your dev database gets test data when
pnpm db:startis running. Stop it first (pnpm db:stop) to test against a clean in-memory database. - "relation already exists" during migrate means the dev database was made with
void db push. Runpnpm db:reset. - Only
env.tsdefaults apply under preview for optional keys. The required keys (SITE_URL,PRODUCT_NAME,BETTER_AUTH_SECRET) andDATABASE_URLcome fromapps/web/.env; others, likeACCOUNT_MODE, use their defaults. - Vitest doesn't run e2e specs, and Playwright doesn't run
*.test.ts. Name e2e files*.spec.tsunderapps/e2e.
Next: Production Deploys →