frontend verification tooling gotchas

---

title: "Gotcha — Frontend Verification and Tooling" type: fix-guide domain: frontend framework: react tags: [tooling, typecheck, eslint, playwright, vitest, zsh, gotcha] created: 2026-10-19 updated: 2026-10-19

Gotcha — Frontend Verification and Tooling

Four tooling traps from the frontend types consolidation on branch chore/tech-debt-types (2026-10). Each cost real debugging time. Check this list before treating a verification failure as a code problem.

Vitest Does Not Typecheck

Symptom

vitest and npm run test:unit pass while the code has type errors. Or the reverse: tsc -p tsconfig.app.json passes while tests are broken.

Root Cause

Vitest runs on esbuild, which strips types without checking them. tsconfig.app.json also excludes test files, so the app-config typecheck never sees test code.

Fix

Run both configs; together they cover production and test code:

npx tsc -p tsconfig.app.json --noEmit
npx tsc -p tsconfig.test.json --noEmit

Known accepted pre-existing failures: two toContainText type errors in UnderConstructionTag.unit.test.tsx under tsconfig.test.json. Anything else is new.

zsh Does Not Word-Split Unquoted Variables

Symptom

npx eslint $FILES exits with an "unmatched pattern" fatal and lints nothing, even though every listed file exists.

Root Cause

The session shell is zsh. Unlike bash, zsh does not word-split an unquoted $FILES, so every path arrives at ESLint joined into one giant pattern. ESLint 10 fatals on any unmatched pattern, so the mega-pattern never matches and ESLint silently checks zero files.

Fix

Pipe the list through xargs instead of interpolating a variable:

printf '%s\n' $FILES | xargs npx eslint

Build the file list from git, excluding deletions (unmatched patterns are fatal) and including untracked files (git diff misses them):

{ git diff --name-only --diff-filter=ACMR HEAD; git ls-files --others --exclude-standard; } | xargs npx eslint

Playwright Reuses a Stale Dev Server

Symptom

Every e2e test fails at the login page, and failure snapshots show the login screen even for tests that stub authentication.

Root Cause

reuseExistingServer attaches Playwright to a vite process already listening on port 3000. If that server was started without VITE_MOCK_AUTH, no test gets past login regardless of its own setup.

Fix

Check port 3000 for stale vite processes before debugging any e2e failure whose snapshot shows the login screen. Kill them and re-run.

Lombok "Method Undefined" Errors in Java Files

Symptom

LSP reports method undefined for Lombok-generated getters, setters, and builders in backend/** files.

Root Cause

Pre-existing JDT/Lombok language-server noise in this workspace, unrelated to frontend changes.

Fix

Ignore it. Do not edit backend files while working on frontend tasks.

Related

• Frontend Type Boundary — the move protocol that runs these verification gates