Testing
| Layer | Current implementation | Execution |
|---|---|---|
| Unit/integration | Colocated Vitest tests in apps/shared packages; Testing Library and Happy DOM for DOM tests | Workspace test scripts through pnpm run test:all |
| Component/browser | Storybook stories rendered in real Chromium, play functions and axe scans | Also included in Turbo test:all; explicit pnpm --filter @kartuli/storybook test available |
| E2E | Playwright target suites, axe helper, and orchestration unit tests in tools/e2e | Browser suites via pnpm e2e <target>; orchestration tests via the package test script. See E2E Runner |
| Production smoke | Target-specific tests/<target>/production suites | Production workflows against deployed URLs |
| Coverage | Root Vitest project aggregation with V8 and text/HTML/JSON reports | pnpm run test:all:coverage |
Unit and integration are purposes, not separately enforced directory structures. Add tests alongside the behavior they verify; choose browser/E2E tests when actual layout, navigation or integration matters.
Coverage and browser distinction
vitest.config.mts excludes tools/storybook and tools/e2e from root coverage projects. This exclusion does not exclude Storybook from Turbo's test:all, and it does not skip the E2E package's orchestration unit tests: those run through @kartuli/e2e's test script. Root coverage still does not collect Playwright specs. turbo.json gives Storybook tests a dependency on the UI build. Browser binaries/system libraries are needed for full validation.
The CI all-monorepo composite action runs root lint, then typecheck, lint, root coverage and Storybook tests in parallel and reports coverage. It does not replace app production smoke or E2E workflows. No repository-wide coverage percentage gate is asserted here; consult the current configs before introducing one.
Execution matrix
| Entry point | Tests it currently executes | Important omission |
|---|---|---|
pnpm run validate:all | Turbo workspace test tasks, including app/UI Vitest, E2E orchestration tests, Storybook Chromium and Web Docs metadata/link/index checks and Node navigation tests | Builds and Playwright browser E2E are separate |
pnpm run test:all:coverage | Root Vitest projects with V8 coverage; apps/UI tests discovered by Vitest | Storybook, Playwright specs, E2E orchestration unit tests and Web Docs .node-test.js are excluded or not discovered |
PR ci-validate-all-monorepo | Explicit Web Docs validation/navigation tests, root coverage and Storybook browser tests | Builds and E2E belong to target workflows |
| PR Web Docs reusable workflow | Build enforces docs validation/navigation and built-index checks; preview runs Playwright smoke | Remote links, fragment anchors and visual layout require separate inspection |
| Production Web Docs workflow | Package lint/test, build/deploy and post-deploy Playwright | Full monorepo validation belongs to the earlier PR gate |
Web Docs source contracts are enforced by both normal validation and the build. Browser smoke tests check rendered delivery separately. Update this matrix with the owning scripts/workflows when changing the execution path.
Use pnpm run validate:all as the local completion gate. Docs also require a Web Docs build and index check.
Choosing the right layer
Start with the failure you want to prevent. Pure transformations and branching decisions fit unit tests. Collaboration between modules or React/provider behavior fits integration tests. Focus, real CSS, portals and animation require browser/component tests. Navigation across the assembled surface belongs in E2E; deployed availability belongs in production smoke tests.
A change can require more than one layer, but repeating the same assertion everywhere adds maintenance without necessarily adding confidence. Each test should explain which boundary it verifies. Mocks should expose a boundary, not hide the behavior under review.
- Unit and integration: environments, setup, assertions and mocks.
- Component/browser: stories, play functions and Chromium.
- E2E and production smoke: servers, targets, retries and artifacts.
- Coverage: reports, exclusions and interpretation.
- Accessibility: automated scans and manual interaction checks.
- Web Quality and Lighthouse: mobile audit profile, score enforcement and public reports.
For documentation tooling, the Web Docs workspace also runs Node's built-in tests for navigation contracts. These do not require Chromium and do not replace rendered-site verification.