App reorganization

docs/testing-guide.md

@@ -0,0 +1,68 @@
+# Testing guide
+
+This is the **why** of testing in CommunityRule. For file layout, helper
+APIs, and required imports see `.cursor/rules/testing.mdc`.
+
+## Philosophy
+
+- **Test behaviour, not implementation.** Assert on what a user can see and
+  do (visible text, roles, labels, keyboard paths). Avoid leaning on
+  internal class names, hook internals, or memoization details.
+- **One consolidated file per component.** A component's standard suite,
+  variant assertions, and behaviour-specific cases all live in
+  `tests/components/<Name>.test.tsx`.
+- **Accessibility is non-negotiable.** Every component suite runs
+  `jest-axe`; full-page WCAG runs in Playwright. A failing axe check is a
+  failing build.
+- **E2E is sparse and high-signal.** Playwright covers critical journeys,
+  visual regression of major pages, and a handful of edge cases — not
+  per-component clicks. Component coverage is the job of Vitest.
+
+## Layered coverage
+
+| Layer | Tool | Scope |
+| --- | --- | --- |
+| Unit | Vitest | Pure logic, reducers, utilities (`tests/unit/`). |
+| Component | Vitest + RTL | DS components in isolation (`tests/components/`). |
+| Page / context | Vitest + RTL | Screens and provider wiring (`tests/pages/`, `tests/contexts/`). |
+| Accessibility (page) | Playwright + axe | WCAG 2.1 AA on key pages (`tests/accessibility/e2e/`). |
+| E2E | Playwright | Critical journeys, visual regression, edge cases (`tests/e2e/`). |
+
+## What to test vs. skip
+
+**Test:**
+
+- Public behaviour — visible text, roles, ARIA, keyboard activation.
+- State transitions users observe (error → success, disabled → enabled).
+- Interaction contracts (click handlers, form submission, dropdown
+  selection).
+- Accessibility invariants.
+
+**Skip:**
+
+- Pure styling that changes with the design system (exact shadow radius,
+  minor spacing).
+- Hook internals or memoization specifics.
+- Responsive visibility in JSDOM — use Playwright instead.
+
+## Running tests
+
+```bash
+npm test                  # vitest run with coverage
+npm run test:component    # vitest, components only (faster inner loop)
+npm run e2e               # playwright (alias: test:e2e)
+npm run visual:update     # refresh playwright screenshots after UI changes
+```
+
+## Adding tests for a new component
+
+1. Create `app/components/<Name>/`.
+2. Create `tests/components/<Name>.test.tsx` and call `componentTestSuite`
+   (see `.cursor/rules/testing.mdc`).
+3. Add behaviour-specific `describe` blocks for any unique interactions.
+4. Run `npm run test:component -- --run tests/components/<Name>.test.tsx`.
+
+## Storybook is documentation, not tests
+
+Stories are visual examples for design review and Code Connect — they do
+not replace component tests. Run `npm run storybook` locally to browse.