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

JobCommandFails on
Format, lint and typespnpm check, then regenerates the auth schema and migrationsFormatting, 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 testspnpm test:unit, pnpm test:smokeA failing Vitest test, or a pinned CLI (Void, Stripe, Wrangler) whose output the kit's tools no longer understand
Buildpnpm buildA package or app that doesn't build
E2Epnpm test:e2eA 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 it
pnpm --filter e2e exec playwright install chromium # once per machine
pnpm test:e2e

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

  1. The main suite, in hybrid account mode.
  2. A rebuild with ACCOUNT_MODE=organizations-only for the specs tagged @organizations-only (apps/e2e/playwright.organizations-only.config.ts; alone: pnpm --filter e2e test:organizations-only).
  3. 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.

DatabaseWhen
Your running dev databaseSomething 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 PGliteNothing 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 spec
pnpm --filter e2e exec playwright test --ui # UI mode
pnpm --filter e2e report # last HTML report
pnpm --filter e2e exec playwright show-trace test-results/<test>/trace.zip # path relative to apps/e2e

On 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-testid and add the attribute to the component when it's missing.
  • Use web-first assertions (await expect(…)), never waitForTimeout.
  • Use clickWhenHydrated() / fillWhenHydrated() from tests/utils/hydration.ts for 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:

  1. Writes apps/web/.env with pnpm kit:setup --step env --yes (from env.example, with a generated BETTER_AUTH_SECRET).
  2. Restores the Playwright browsers from a cache keyed by the Playwright version, or installs Chromium with its system dependencies.
  3. Runs pnpm test:e2e against an in-memory PGlite. Playwright retries a failed test once, and test.only fails the run.
  4. On failure, uploads playwright-report/ and test-results/ as the playwright-report artifact, 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 preview

This 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/.env stops the suite before it starts. Run pnpm kit:setup --step env --yes; e2e never creates the file for you. Don't copy env.example by hand: its BETTER_AUTH_SECRET is 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:start is 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. Run pnpm db:reset.
  • Only env.ts defaults apply under preview for optional keys. The required keys (SITE_URL, PRODUCT_NAME, BETTER_AUTH_SECRET) and DATABASE_URL come from apps/web/.env; others, like ACCOUNT_MODE, use their defaults.
  • Vitest doesn't run e2e specs, and Playwright doesn't run *.test.ts. Name e2e files *.spec.ts under apps/e2e.

Next: Production Deploys →