Common errors & fixes

Quick reference for the most common problems you'll hit when setting up or running the PACE E2E suite.

Symptom	Likely cause	Fix
"browser not found" / chrome-channel error on startup	Playwright's chrome channel requires system Google Chrome, which isn't installed or hasn't been registered with Playwright.	Run pnpm exec playwright install chrome. On Linux/CI where the branded chrome channel isn't published, set PW_CHANNEL=chromium and run pnpm exec playwright install chromium instead. The official Playwright CI image already includes the browser, so no install step is needed there.
Agents can't find app form fields, component names, or routes	The pace-ui-application sibling checkout is missing or in a non-default location. Agents need it to look up field: names, colId: values, button labels, and route paths.	Make sure the pace-ui-application repo is checked out next to this repo (i.e. ../pace-ui-application). If it's elsewhere, set PACE_APP_REPO=/path/to/pace-ui-application in your .env. Never guess field names from memory — always read from source.
Login fails / auth fixture throws immediately	TEST_USERNAME or TEST_PASSWORD is missing or wrong in .env.	Copy .env.sample to .env and fill in valid credentials. The auth fixture reads these via {{env:TEST_USERNAME}} and {{env:TEST_PASSWORD}} placeholders in tests/data/common.jsonc.
pnpm run test:validate-spec exits with errors	One or more spec files under tests/specs/ have invalid frontmatter (missing required fields) or malformed section structure.	Open the file named in the error output and fix the flagged issue. The Authoring section explains the required frontmatter keys.
pnpm run test:validate-data exits with errors	A tests/data/*.jsonc file fails Zod validation — usually a typo, wrong type, or a field that no longer exists in the schema.	Read the validation error message — it gives a dotted path to the broken key. Fix the value in the named .jsonc file. The schema lives in tests/data/schemas.ts.
Tests pass but hit the wrong environment or unexpected data	TEST_ENV is unset (defaults to dev2) or is set to the wrong environment.	Set TEST_ENV to the environment you want: TEST_ENV=qa2 pnpm run test. See the Running & debugging section for the full environment map.

Still stuck?

If none of the above resolves your issue:

1. Run pnpm run validate — it chains checkTs, lint, format:check, validate-data, and validate-spec and will surface any config problem.
2. Run with HEADLESS=false pnpm run test to watch the browser and see where it stalls.
3. Check playwright-report/ and test-results/ for the HTML report, screenshots, and traces captured on failure.