@pnx-mixtape/mxds 0.1.0-rc.3 → 0.1.0-rc.5

package/docs/Testing.md

@@ -0,0 +1,739 @@
+# Testing Guide
+
+Testing strategies and best practices for the Mixtape Design System.
+
+## Table of Contents
+
+- [Testing Philosophy](#testing-philosophy)
+- [Storybook Stories](#storybook-stories)
+- [Snapshot Testing](#snapshot-testing)
+- [Accessibility Testing](#accessibility-testing)
+- [Running Tests](#running-tests)
+- [Writing Tests](#writing-tests)
+
+---
+
+## Testing Philosophy
+
+The design system uses **visual regression testing** through Storybook instead of traditional unit tests.
+
+### Why Visual Testing?
+
+- ✅ **Tests actual UI** - Not just logic
+- ✅ **Catches visual regressions** - Breaking changes visible immediately
+- ✅ **Living documentation** - Stories serve as docs and tests
+- ✅ **Faster to write** - No complex test setup
+- ✅ **Accessible testing** - Built-in a11y checks
+
+### Test Stack
+
+- **Storybook** - Interactive component development
+- **Vitest** - Test runner (browser mode with Playwright)
+- **@storybook/addon-vitest** - Snapshot testing from stories
+- **@storybook/addon-a11y** - Accessibility testing (axe-core rule violations)
+- **@guidepup/virtual-screen-reader** - Automated screen reader announcement testing
+
+---
+
+## Storybook Stories
+
+Every component must have Storybook stories.
+
+### Basic Story Structure
+
+```typescript
+// Component.stories.ts (Twig/HTML)
+import type { Meta, StoryObj } from "@storybook/html"
+
+const meta: Meta = {
+  title: "Component/ComponentName",
+  tags: ["autodocs"],
+  render: args => {
+    return `
+      <mx-component class="${args.className}">
+        ${args.content}
+      </mx-component>
+    `
+  },
+  argTypes: {
+    content: { control: "text" },
+    className: { control: "text" },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+export const Default: Story = {
+  args: {
+    content: "Default content",
+    className: "",
+  },
+}
+
+export const WithModifier: Story = {
+  args: {
+    content: "Modified content",
+    className: "mx-component--reversed",
+  },
+}
+```
+
+### React Story Structure
+
+```typescript
+// Component.stories.tsx (React)
+import type { Meta, StoryObj } from "@storybook/react"
+import Component from "./Component"
+
+const meta: Meta<typeof Component> = {
+  title: "Component/ComponentName",
+  component: Component,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof Component>
+
+export const Default: Story = {
+  args: {
+    children: "Default content",
+  },
+}
+
+export const Reversed: Story = {
+  args: {
+    children: "Reversed content",
+    reversed: true,
+  },
+}
+```
+
+### Story Best Practices
+
+1. **Name stories descriptively**
+
+   ```typescript
+   export const Default: Story = {}
+   export const WithIcon: Story = {}
+   export const DisabledState: Story = {}
+   export const LongContent: Story = {}
+   export const MobileView: Story = {}
+   ```
+
+2. **Use argTypes for controls**
+
+   ```typescript
+   argTypes: {
+     variant: {
+       control: "select",
+       options: ["primary", "secondary", "tertiary"],
+     },
+     size: {
+       control: "radio",
+       options: ["small", "medium", "large"],
+     },
+     disabled: {
+       control: "boolean",
+     },
+     content: {
+       control: "text",
+     },
+   }
+   ```
+
+3. **Add play functions for interactions**
+
+   ```typescript
+   import { userEvent, within } from "@storybook/test"
+
+   export const InteractiveExample: Story = {
+     play: async ({ canvasElement }) => {
+       const canvas = within(canvasElement)
+       const button = canvas.getByRole("button")
+       await userEvent.click(button)
+     },
+   }
+   ```
+
+4. **Tag stories appropriately**
+   ```typescript
+   export const NoSnapshot: Story = {
+     tags: ["no-snapshot"],  // Skip snapshot testing
+     args: { ... },
+   }
+   ```
+
+---
+
+## Snapshot Testing
+
+Snapshots are automatically generated from Storybook stories.
+
+### How It Works
+
+1. Write Storybook story
+2. Run tests: `pnpm test`
+3. Snapshot created in `__snapshots__/` directory
+4. Future tests compare against snapshot
+5. Visual changes detected automatically
+
+### Snapshot Files
+
+```
+Component/
+├── Component.stories.ts
+├── Component.stories.tsx
+└── __snapshots__/
+    ├── Component.stories.ts.snap
+    └── Component.stories.tsx.snap
+```
+
+### Updating Snapshots
+
+```bash
+# Run tests (fails if snapshots don't match)
+pnpm test
+
+# Update snapshots after intentional changes
+pnpm test -- -u
+
+# Run tests for specific project
+pnpm test-html   # HTML/Twig components
+pnpm test-react  # React components
+```
+
+### When to Update Snapshots
+
+✅ **Update when:**
+
+- Intentional visual changes
+- Component refactored (same appearance)
+- Design tokens updated
+- CSS improvements
+
+❌ **Don't update for:**
+
+- Failing tests you haven't reviewed
+- Unknown changes
+- Regressions you haven't investigated
+
+### Skip Snapshot for Specific Stories
+
+```typescript
+// For stories that shouldn't be snapshot tested
+export const AnimatedExample: Story = {
+  tags: ["no-snapshot"],
+  args: {
+    animated: true,
+  },
+}
+```
+
+---
+
+## Accessibility Testing
+
+### Storybook A11y Addon
+
+The a11y addon runs automatically in Storybook:
+
+1. Open any story in Storybook
+2. Check "Accessibility" tab at bottom
+3. Review violations, passes, and incomplete checks
+4. Fix violations before shipping
+
+### Common A11y Issues
+
+```typescript
+// ❌ BAD - Missing ARIA label
+<button onclick="toggle()">
+  <span class="mx-icon--menu"></span>
+</button>
+
+// ✅ GOOD - Has ARIA label
+<button onclick="toggle()" aria-label="Toggle menu">
+  <span class="mx-icon--menu"></span>
+</button>
+
+// ❌ BAD - Low contrast
+color: #999;
+background: #fff;  // Fails WCAG AA
+
+// ✅ GOOD - Sufficient contrast
+color: #666;
+background: #fff;  // Passes WCAG AA
+
+// ❌ BAD - Missing alt text
+<img src="photo.jpg">
+
+// ✅ GOOD - Has alt text
+<img src="photo.jpg" alt="Description">
+```
+
+### Automated Screen Reader Testing
+
+The a11y addon (above) catches static rule violations - missing labels, contrast, etc. - but can't tell you what a screen reader actually *announces* when navigating a component. [`@guidepup/virtual-screen-reader`](https://guidepup.dev) simulates that: it walks the accessible tree and produces the sequence of roles/states/text a screen reader would speak.
+
+This is opt-in, not required for every component - it earns its keep on components with complex ARIA behavior (disclosure, roving tabindex, live regions, focus management), not on simple atoms that get nothing meaningful out of a walkthrough.
+
+Use the shared helper in `tools/test-utils/screen-reader.ts` inside a dedicated `ScreenReaderAnnouncements` story, kept separate from any keyboard-interaction `play:` function so the two stay independently readable:
+
+```typescript
+import { expect } from "storybook/test"
+import { runScreenReaderWalkthrough } from "../../../tools/test-utils/screen-reader"
+
+export const ScreenReaderAnnouncements: Story = {
+  play: async ({ canvas, userEvent }) => {
+    // Open/expand whatever the component needs to reach its interesting state.
+    const log = await runScreenReaderWalkthrough()
+    await expect(log).toEqual([
+      "document",
+      // ...the rest of the expected spoken-phrase sequence.
+      "end of document",
+    ])
+    // Then restore original state (close/deselect), same as any other play function.
+  },
+}
+```
+
+**Important: don't use `vitest`'s `expect`/`toMatchSnapshot` here, even though the DOM `innerHTML` snapshot in `vitest.setup.ts` does.** Story files are loaded by two different runtimes: the Vitest test runner (`pnpm test-html`/`test-react`) *and* Storybook's own dev server/build/Chromatic, which execute `play:` functions directly in the browser with no Vitest runtime present. `vitest`'s `expect` reaches for a matchers-object global that only exists inside an active Vitest run - importing and calling it from a story file works under `pnpm test-*` but throws (`Cannot access property "customEqualityTesters"`, `globalThis[JEST_MATCHERS_OBJECT]` undefined) the moment Storybook tries to render the same story, breaking it there. `vitest.setup.ts` is safe because it's only ever loaded by Vitest's `setupFiles`, never by Storybook. Use `storybook/test`'s `expect` instead (safe in both contexts, and what every other assertion in this codebase already uses) with a hard-coded `.toEqual([...])` array rather than a snapshot - `storybook/test`'s `expect` doesn't support `.toMatchSnapshot()` at all.
+
+The helper scopes the walkthrough to `document.body` (Storybook renders one story per page, so that's exactly the story under test) and steps through until "end of document" is announced.
+
+See `src/Component/Tabs/Tabs.stories.ts`, `src/Component/Dialog/Dialog.stories.ts`, and `src/Component/DropMenu/DropMenu.stories.ts` for worked examples.
+
+In a React (`.stories.tsx`) file, add the story **last**. React's `useId()` counters (`id="_r_N_"`) are global per test-file run, so inserting a new story earlier in the file shifts the counters - and therefore the DOM snapshots - of every story that renders after it.
+
+**Known limitation: a link with an icon next to its text announces the text twice.** A link whose only child is a bare text node (`<a>Read more</a>`) is announced once, atomically. The moment that link also has a sibling element - most commonly a decorative icon rendered alongside the title (e.g. `Pagination`'s Previous/Next, `InPageNavigation`'s items with `iconStart`) - the walker treats the link as a container and re-announces the text on the way in, even though the icon itself contributes nothing. This is a raw-DOM-structure check, not an accessibility-tree one: `aria-hidden="true"` on the icon does not fix it (verified). The only real fix would be rendering such icons as CSS pseudo-elements instead of real DOM nodes, which this codebase deliberately doesn't do. Buttons are unaffected (they're always announced atomically regardless of internal structure - only links behave this way). Treat this as a known tool limitation when reviewing a `ScreenReaderAnnouncements` snapshot for an icon+text link - don't spend time trying to "fix" the duplicate.
+
+**If the component has `chromatic.modes` (mobile/desktop), check whether the walkthrough needs to branch too.** Chromatic renders every story - including `ScreenReaderAnnouncements` - at each configured mode's viewport width. If anything is hidden/shown or added/removed from the DOM between those widths (a CSS container query swapping content, a `matchMedia`-driven breakpoint, a JS-driven observer that hides off-screen items), the accessibility tree differs between modes and a single hardcoded `.toEqual([...])` will fail under whichever mode it wasn't written against. Branch the same way the [matchMedia pattern above](#testing-mobile--matchmedia-driven-behavior-in-play-functions) does - on the component's own real rendered state - and assert the correct array for each shape:
+
+```typescript
+export const ScreenReaderAnnouncements: Story = {
+  play: async ({ canvasElement }) => {
+    const isMobile = matchMedia("(max-width: 767px)").matches // real matchMedia breakpoint
+    // ...or, for a CSS *container* query (no matchMedia equivalent exists),
+    // check the actually-rendered state directly, e.g.:
+    // const label = canvasElement.querySelector(".mx-pagination__label")
+    // const isNarrow = label !== null && getComputedStyle(label).display !== "none"
+
+    const log = await runScreenReaderWalkthrough()
+
+    if (isMobile) {
+      await expect(log).toEqual([/* ...mobile shape... */])
+    } else {
+      await expect(log).toEqual([/* ...desktop shape... */])
+    }
+  },
+}
+```
+
+As with the matchMedia pattern, a local run only meaningfully exercises one branch (whichever width it happens to render at); Chromatic's other mode exercises the other in CI. See `src/Component/Pagination/Pagination.stories.ts` (container-query-driven), `src/Component/Carousel/Carousel.stories.ts` (IntersectionObserver-driven), and `src/Component/Tabs/Tabs.stories.ts`/`src/Layout/Header/Header.stories.ts` (`matchMedia`-driven, via a custom element's `Elements/*.ts`) for worked examples. Components without `chromatic.modes` on their `meta` don't need this; for ones that do, check **both** the component's CSS (`@media`/`@container` rules toggling `display`/`visibility`) **and** its `Elements/*.ts` custom element(s) for a `matchMedia`/`mq` breakpoint - CSS-only checking isn't enough: `Tabs` collapses its tab list into a `DropMenu` purely via JS (`Elements/Tabs.ts`'s `handleBreakpoint`), with nothing in `tabs.css` suggesting a difference. Confirm with the real rendered DOM, not just a reading of the source - temporarily set `parameters: { viewport: { defaultViewport: "xs" } }` on the story (this is a local-only override `@storybook/addon-vitest` reads; it doesn't affect Chromatic) to force the actual narrow-viewport render and see what the walkthrough really produces, then remove the override once the branches are written. `Accordion`/`AccordionItem` were checked this way and don't need branching - their default render has no breakpoint logic (the separate `mx-accordionmobile` variant is a distinct, explicitly-chosen template, not something the default item switches to).
+
+### Manual A11y Testing
+
+1. **Keyboard navigation**
+   - Tab through all interactive elements
+   - Enter/Space activates buttons
+   - Escape closes modals/menus
+   - Arrow keys navigate menus
+
+2. **Screen reader testing**
+   - Automated coverage exists for components with a `ScreenReaderAnnouncements` story (see [Automated Screen Reader Testing](#automated-screen-reader-testing) above)
+   - For everything else, or for release-critical flows, spot-check manually:
+     - MacOS: VoiceOver (Cmd+F5)
+     - Windows: NVDA or JAWS
+     - Mobile: TalkBack (Android) / VoiceOver (iOS)
+
+3. **Color contrast**
+   - Use browser DevTools color picker
+   - Check contrast ratio ≥ 4.5:1 for text
+   - Check contrast ratio ≥ 3:1 for UI components
+
+---
+
+## Running Tests
+
+### All Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run with coverage
+pnpm test -- --coverage
+
+# Run in watch mode (development)
+pnpm test -- --watch
+```
+
+### Specific Projects
+
+```bash
+# HTML/Twig components only
+pnpm test-html
+
+# React components only
+pnpm test-react
+
+# Run specific story
+pnpm test -- Component.stories.ts
+```
+
+### CI/CD Testing
+
+```bash
+# Lint and test (used in CI)
+pnpm lint-ci
+pnpm test
+
+# Build and test
+pnpm build-ci
+```
+
+### Development Workflow
+
+```bash
+# 1. Start Storybook
+pnpm dev
+
+# 2. Develop component with live reload
+# Visit http://localhost:6006 (HTML)
+# Visit http://localhost:6008 (React)
+
+# 3. Run tests when ready
+pnpm test
+
+# 4. Update snapshots if needed
+pnpm test -- -u
+```
+
+---
+
+## Writing Tests
+
+### Test Checklist
+
+Before submitting a component:
+
+- [ ] Storybook story created
+- [ ] Default story exists
+- [ ] Variant stories created
+- [ ] Edge cases covered (long content, empty state)
+- [ ] Responsive variants shown
+- [ ] Interactive states tested (hover, focus, active)
+- [ ] Snapshots generated and reviewed
+- [ ] A11y violations = 0
+- [ ] Keyboard navigation works
+- [ ] Screen reader tested (automated `ScreenReaderAnnouncements` story for complex ARIA components, manual spot-check otherwise)
+- [ ] Color contrast checked
+
+### Testing Mobile / `matchMedia`-Driven Behavior in Play Functions
+
+Some components (`Filters`, `Header`) switch behavior based on `window.matchMedia` rather than (only) a `viewport` story parameter. Don't reach for `vitest/browser`'s `page.viewport()` (or the deprecated `@vitest/browser/context`) to force this from a play function. That module **only exists inside Vitest's browser-mode test runner** - importing it anywhere in a `.stories.tsx` file throws `"vitest/browser can be imported only inside the Browser Mode. Instead, it was imported outside of Vitest."` the moment Storybook loads the story directly (`pnpm dev-react`, `pnpm build-react`). Storybook imports story files outside of Vitest entirely, so this breaks the live story for everyone viewing it, not just the test run.
+
+Instead, write **one** play function per story that branches on the **real** `matchMedia(...).matches` and asserts something meaningful on both sides, rather than a mobile-only story or a mock. Pair it with a `chromatic.modes` entry (desktop + mobile) on the component's `meta` - Chromatic renders the story at a real viewport width for each mode in CI, so across the mobile and desktop CI runs both branches of the play function get exercised against a real, correctly-sized viewport. No in-test viewport mocking or forcing is needed, and there's no separate "mobile" story to maintain:
+
+```typescript
+// Component.stories.tsx
+import { modes } from "../../../.storybook/modes"
+
+const meta: Meta<typeof Component> = {
+  // ...
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
+}
+
+export const CollapsibleRight: StoryObj<typeof meta> = {
+  play: async ({ canvasElement, canvas, userEvent, step }) => {
+    const details = canvasElement.querySelector("details")
+    const isMobile = matchMedia("(max-width: 767px)").matches
+
+    if (!isMobile) {
+      await step("Is open on desktop", async () => {
+        await waitFor(() => expect(details).toHaveAttribute("open"))
+      })
+    } else {
+      await step("Starts closed on mobile", async () => {
+        await waitFor(() => expect(details).not.toHaveAttribute("open"))
+      })
+      // ...mobile-only interaction assertions...
+    }
+  },
+}
+```
+
+Whichever mode a given local run (`pnpm dev-react`, `vitest --project=storybook-react`) happens to render at, only one branch runs meaningfully for that run - the other is a no-op. That's expected: Chromatic's CI job covers the branch a given local run skips, by rendering the same story again under the other mode.
+
+### Story Coverage
+
+Ensure stories cover:
+
+1. **Default state**
+
+   ```typescript
+   export const Default: Story = {
+     args: {},
+   }
+   ```
+
+2. **All modifiers**
+
+   ```typescript
+   export const Primary: Story = {
+     args: { variant: "primary" },
+   }
+
+   export const Secondary: Story = {
+     args: { variant: "secondary" },
+   }
+   ```
+
+3. **Different sizes**
+
+   ```typescript
+   export const Small: Story = {
+     args: { size: "small" },
+   }
+
+   export const Large: Story = {
+     args: { size: "large" },
+   }
+   ```
+
+4. **Interactive states**
+
+   ```typescript
+   export const Disabled: Story = {
+     args: { disabled: true },
+   }
+
+   export const Loading: Story = {
+     args: { loading: true },
+   }
+   ```
+
+5. **Edge cases**
+
+   ```typescript
+   export const EmptyState: Story = {
+     args: { children: "" },
+   }
+
+   export const LongContent: Story = {
+     args: {
+       children: "Very long content that wraps multiple lines...",
+     },
+   }
+   ```
+
+---
+
+## Vitest Configuration
+
+The test setup uses browser mode with Playwright:
+
+```javascript
+// vitest.config.js
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      provider: playwright({}),
+      headless: true,
+      instances: [{ browser: "chromium" }],
+    },
+    projects: [
+      {
+        name: "storybook",
+        plugins: [
+          storybookTest({
+            configDir: ".storybook",
+            storybookScript: "pnpm dev-html --no-open",
+          }),
+        ],
+        setupFiles: ["./.storybook/vitest.setup.ts"],
+      },
+      {
+        name: "storybook-react",
+        plugins: [
+          storybookTest({
+            configDir: ".storybook-react",
+            storybookScript: "pnpm dev-react --no-open",
+          }),
+        ],
+        setupFiles: ["./.storybook-react/vitest.setup.ts"],
+      },
+    ],
+  },
+})
+```
+
+---
+
+## Troubleshooting Tests
+
+### Snapshots Failing
+
+```bash
+# 1. Review changes
+pnpm test
+
+# 2. Check what changed
+git diff src/Component/__snapshots__/
+
+# 3. If intentional, update snapshots
+pnpm test -- -u
+
+# 4. Commit updated snapshots
+git add src/Component/__snapshots__/
+git commit -m "test: update snapshots for Component"
+```
+
+### Storybook Not Starting
+
+```bash
+# Clear cache
+rm -rf node_modules/.cache
+
+# Reinstall dependencies
+pnpm install
+
+# Try again
+pnpm dev
+```
+
+### A11y Violations
+
+1. Open story in Storybook
+2. Click "Accessibility" tab
+3. Review violations
+4. Click violation for remediation guidance
+5. Fix issue in component
+6. Verify violation cleared
+
+### Tests Timing Out
+
+```bash
+# Increase timeout
+pnpm test -- --testTimeout=30000
+
+# Run single test
+pnpm test -- Component.stories.ts
+
+# Check Storybook is accessible
+curl http://localhost:6006
+```
+
+---
+
+## Best Practices
+
+### Do's ✅
+
+1. **Write stories for every component**
+2. **Cover all variants and states**
+3. **Review snapshots before updating**
+4. **Fix a11y violations immediately**
+5. **Test keyboard navigation manually**
+6. **Use semantic HTML**
+7. **Add ARIA labels where needed**
+8. **Test with actual screen readers**
+9. **Check color contrast**
+10. **Document complex interactions**
+
+### Don'ts ❌
+
+1. **Don't skip snapshot review**
+2. **Don't ignore a11y violations**
+3. **Don't update snapshots without reviewing**
+4. **Don't test implementation details**
+5. **Don't create stories that aren't tested**
+6. **Don't forget mobile viewports**
+7. **Don't skip keyboard testing**
+8. **Don't use poor color contrast**
+9. **Don't forget alt text**
+10. **Don't ship with failing tests**
+11. **Don't mock or force a viewport from inside a play function** - branch the same play function on the real `matchMedia(...).matches` and pair it with `chromatic.modes` instead; see [Testing Mobile / matchMedia-Driven Behavior in Play Functions](#testing-mobile--matchmedia-driven-behavior-in-play-functions)
+
+---
+
+## Examples from Codebase
+
+### Accordion Stories
+
+```typescript
+// src/Component/Accordion/Accordion.stories.ts
+export const Default: Story = {
+  args: {
+    content: `
+      <details>
+        <summary>Toggle content</summary>
+        <p>Hidden content</p>
+      </details>
+    `,
+  },
+}
+
+export const Open: Story = {
+  args: {
+    content: `
+      <details open>
+        <summary>Already open</summary>
+        <p>Visible content</p>
+      </details>
+    `,
+  },
+}
+```
+
+### Button Stories
+
+```typescript
+// src/Atom/Button/Button.stories.tsx
+export const Primary: Story = {
+  args: {
+    children: "Primary Button",
+    modifiers: [ButtonModifiers.PRIMARY],
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    children: "Disabled Button",
+    disabled: true,
+  },
+}
+
+export const WithIcon: Story = {
+  args: {
+    children: "Icon Button",
+    icon: Icons.ARROW_RIGHT,
+  },
+}
+```
+
+---
+
+## Resources
+
+- [Storybook Documentation](https://storybook.js.org/docs)
+- [Vitest Documentation](https://vitest.dev/)
+- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [axe DevTools](https://www.deque.com/axe/devtools/)
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+
+---
+
+## Related Documentation
+
+- [Code Quality Guidelines](./CodeQuality.md)
+- [Component Architecture](./ComponentArchitecture.md)
+- [Contributing Guide](./Contributing.md)