test-layer-selection

name	test-layer-selection
description	How to pick the nearest test layer in the whiteboard repo (mcp-node / mcp-jsdom / mcp-browser / web-browser / E2E) and the commands to run each. Use when writing the red test for a change, or deciding where a regression belongs.

Test Layer Selection

Start with the smallest failing test at the nearest layer. Do not jump to broad E2E if a smaller failing test can isolate the bug.

Layer	Use for	Command
mcp-node	pure functions, stores, routes, server behavior, persistence logic	pnpm test --project mcp-node
mcp-jsdom	React components/hooks when browser layout & pointer behavior are NOT the core risk	pnpm test --project mcp-jsdom
mcp-browser	popovers, dialogs, scroll, focus, keyboard, pointer, restore flows (real browser) in packages/mcp-server	pnpm test --project mcp-browser
web-browser	apps/web tests needing real browser APIs jsdom lacks: IndexedDB, OPFS, window.showOpenFilePicker. File suffix .browser.test.tsx	part of pnpm test:browser
E2E	real routes, server composition, websocket timing, persistence order, multi-step page flows	promote only when needed

Notes:

• apps/web unit/jsdom: pnpm --filter @kamiazya/whiteboard-web test.
• Browser suites together: pnpm run test:browser (mcp-browser + web-browser); pnpm run test:browser:trace for trace artifacts on failure (under <package>/tmp/vitest-traces).
• After the targeted test passes, run the broader suite covering the touched area, then pnpm test.
• Runtime is the source of truth: if behavior disagrees with a test, fix the test or implementation to match real behavior.
• Passing tests alone are not sufficient — manually verify the real behavior (Playwright/Chrome MCP) before locking the scenario into regression coverage.