# Regression test plan

Mechanica’s regression strategy combines unit tests, component tests, browser automation, visual/manual review, and performance profiling. The goal is to protect the core learning path: find a machine, open it, manipulate the 3D view, understand parts, animate motion, and share the result.

## Test pyramid

| Layer | Tooling | Purpose |
| --- | --- | --- |
| Unit | Vitest | Pure utilities: URL state, registry validation, state migrations, clamps. |
| Component | Vitest + Testing Library | Catalogue controls, panels, buttons, drawers, error fallbacks. |
| E2E | Playwright | Route smoke tests and critical user flows. |
| Manual QA | Checklist | WebGL visual accuracy, mobile gestures, guided tour clarity. |
| Performance | DevTools + bundle report | FPS, memory, chunk size, asset budgets. |

## Unit test coverage

Required utility tests:

- URL state serialization is deterministic.
- URL parser clamps numeric values.
- URL parser ignores unknown params.
- Invalid part IDs are removed.
- Camera vectors round-trip within precision tolerance.
- Opacity overrides clamp `0` to `1`.
- RPM clamps to active machine range.
- Reduced-motion preference precedence is correct.
- Machine registry validates unique slugs.
- Machine registry validates unique part IDs per machine.
- Related machines reference valid slugs.
- Guided tour highlights reference valid part IDs.
- Persistence migrations upgrade older payloads.
- Reset actions restore defaults.

## Component test coverage

Required component tests:

- Catalogue search input filters visible cards.
- Category filter toggles update results.
- Difficulty filter toggles update results.
- Sort control orders results correctly.
- Favourite button updates local persisted state.
- Machine card is keyboard-activatable.
- Error boundary renders fallback and retry action.
- Loading skeleton has `role="status"` when announcing.
- Copy-link button announces success.
- Copy-link button shows error when clipboard fails.
- Playback controls call play/pause/restart actions.
- RPM and time-scale sliders expose accessible names.
- Part row visibility and opacity controls call the correct actions.
- Drawer close returns focus to the triggering control.

## E2E smoke coverage

Minimum Playwright flows:

### Catalogue flow

1. Open `/`.
2. Confirm app shell and catalogue are visible.
3. Search for `engine`.
4. Open a machine card.
5. Confirm viewer route loads.

### Viewer flow

1. Open `/machine/four-stroke-petrol-engine`.
2. Wait for viewer ready state.
3. Use camera preset.
4. Toggle exploded view.
5. Toggle wireframe.
6. Select a part through the part list.
7. Open and close detail drawer.
8. Copy share link.

### Share link flow

1. Open a machine.
2. Apply non-default state.
3. Copy or read generated share URL.
4. Open the URL in a fresh page.
5. Confirm restored state.

### Responsive flow

1. Set mobile viewport.
2. Open catalogue.
3. Open viewer.
4. Confirm side panels are available as drawers.
5. Confirm no horizontal overflow.

### Accessibility flow

1. Navigate primary controls with keyboard.
2. Open shortcut help.
3. Close overlays with Escape.
4. Confirm selected machine route has meaningful document title.

## Visual regression areas

Full screenshot automation for WebGL can be noisy across GPUs. Prefer targeted manual visual review unless a stable software-rendered CI environment is available.

Manual visual checkpoints:

- dark shell has no white flash
- catalogue card spacing
- viewer panel layout
- selected-part highlight
- exploded view separation
- wireframe contrast
- cross-section clipping
- annotation label placement
- reduced-motion transitions
- mobile drawer layout

## Performance regression tests

Run before production releases:

```bash
npm run build
npm run preview
npm run analyze
```

Capture:

- JS transfer size
- largest chunks
- route chunk composition
- FPS during orbit
- FPS during animation
- memory before/after switching five machines
- network waterfall for the largest machine asset

Performance failures requiring investigation:

- all machine modules in initial route
- duplicate Three.js copies
- repeated material/geometry allocations after route changes
- large non-hashed assets without cache headers
- mobile frame rate below release gate

## CI recommendation

A practical CI workflow:

```bash
npm install
npm run typecheck
npm run lint
npm run test:coverage
npm run build
```

Run Playwright in CI when browser installation is available:

```bash
npx playwright install --with-deps chromium
npm run test:e2e
```

For pull requests touching 3D scene code or machine definitions, require a preview deployment and manual QA sign-off for at least the affected machine plus one unrelated machine.

## Release acceptance

A release candidate is acceptable when:

- automated QA commands pass
- preview deployment passes the QA checklist
- no critical console errors appear
- share links round-trip
- reduced-motion behavior is verified
- at least one desktop and one mobile profile meet performance targets
- rollback path is known