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

*Canonical: https://makerkit.dev/docs/void-cloudflare/deployment/checks-and-e2e*

---

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](./overview).

## 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](./production#protect-main)).

| 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](./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

```bash
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](../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:

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

```bash
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 →](./production)
