Test‑Kit Documentation

Overview

The test‑kit package centralises the testing utilities used across the Chimiverse monorepo. It provides a small, opinionated set of conventions and helpers for three primary test categories:

| Test Type | Tooling | When to Use | What It Covers | |-----------|---------|-------------|----------------| | Unit Tests | Vitest (via vitest.config.ts) | Isolate a single module or function. Ideal for pure‑logic, data‑structures, and pure‑component functions. | Fast, in‑process execution. No external services. | | Integration / API Tests | Vitest with real or mocked dependencies | Verify interaction between modules, API routes, and services (e.g., the @chimi/web-app-kit adapters, font‑serving endpoints). | May spin up an in‑memory server or use MSW mocks. | | Visual Regression Tests | Playwright (@playwright/test) | Detect UI regressions after UI‑related changes (layout, theme, component rendering). | Takes screenshots of rendered pages, compares against stored snapshots. | | End‑to‑End (E2E) Tests | Playwright scripts in tests/ | Validate full user flows across the entire app (navigation, state persistence, hash‑based routing). | Runs against a real dev server (npm run dev). |

How to Add a New Test

1. Create the test file in the appropriate folder:
   • Unit / Integration – packages/<package>/src/__tests__/.
   • Visual – packages/<package>/tests/visual.spec.ts.
   • E2E – packages/<package>/tests/e2e/*.spec.ts.
2. Import the shared utilities from test-kit when necessary (e.g., render, mockApi, screenshot).
3. Run the suite locally:

   # Unit & integration
   npm run test
   # Visual regression (updates snapshots)
   npm run test:visual:update
   # E2E (full app)
   npm run test:e2e

4. Commit the new test and ensure the CI pipeline runs the corresponding command.

Test‑Kit Helpers

• render(component, options): wraps a Preact component with the design‑system theme.
• mockApi(route, response): simple MSW‑style mocking for API endpoints.
• screenshot(page, name): thin wrapper around Playwright's toHaveScreenshot for consistent masking.

When a Test Is Missing

• If you add a new feature (e.g., a new UI control, API endpoint, or domain logic), add a unit or integration test first.
• For any visual change (layout, theme, component redesign), add or update a visual regression test.
• For full‑flow changes (routing, navigation, state persistence), add an E2E test that exercises the user path.

This README lives in packages/test-kit to give contributors a single source of truth for the testing strategy across Chimiverse.