@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/content/guidance/storefront-next/sfnext-testing/SKILL.md

@@ -1,184 +1,151 @@
 ---
 name: sfnext-testing
-description: Write tests for Storefront Next using Vitest unit tests, Storybook stories, interaction tests, snapshot tests, and accessibility tests. Use when writing component tests, creating Storybook stories, running test coverage, or setting up test utilities. Covers testing-library patterns, play functions, and coverage thresholds.
+description: >-
+  Write and run tests for a Storefront Next project: Vitest + React Testing Library unit tests, route loader/action tests (createLoaderArgs, createTestContext), Storybook stories with snapshot, interaction (play) and a11y runs, and a pointer to the CodeceptJS/Playwright e2e suite. Use for "write a test for this component/loader", "add a story", pnpm test, pnpm storybook:test --type=snapshot|interaction|a11y, coverage thresholds, routeLoaderData / scapiMock / mockRoutes story parameters, MSW mocking, fixtures in @/components/__mocks__, failing snapshot updates, or pnpm e2e. Do not use for lint, typecheck, format, bundle-size or Lighthouse gates (use `storefront-next:sfnext-quality-gates`), accessibility rules and fixes (use `storefront-next:sfnext-accessibility`), or translations (use `storefront-next:sfnext-i18n`).
 ---
 
-# Testing Skill
+# Testing Storefront Next
 
-This skill covers testing patterns in Storefront Next — Vitest for unit tests and Storybook for component stories, interaction tests, and accessibility validation.
+Three layers, all shipped in your project (see `docs/README-TESTS.md`, `docs/README-STORYBOOK.md`, `AGENTS.md`):
 
-## Unit Tests (Vitest)
+| Layer | Tool | Files | Command |
+|-------|------|-------|---------|
+| Unit and route tests | Vitest, jsdom, Testing Library, MSW | `*.test.ts(x)` next to source | `pnpm test` |
+| Component stories | Storybook: snapshot (Vitest), interaction and a11y (Playwright/Chromium) | `<component>/stories/*.stories.tsx` | `pnpm storybook:test --type=...` |
+| End to end | CodeceptJS + Playwright | `e2e/` | `pnpm e2e` |
 
-Test files live alongside source files with `.test.ts` or `.test.tsx` extension:
+Prefer the cheapest layer that proves the behavior: pure logic and loaders in Vitest, rendered states and interactions in stories, cross-page shopper flows in e2e.
 
-```typescript
-// src/components/product-card/product-card.test.tsx
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import { ProductCard } from './product-card';
-import { mockProduct } from '@/test-utils/mocks';
+## Commands
 
-describe('ProductCard', () => {
-    it('renders product name', () => {
-        render(<ProductCard product={mockProduct} />);
-        expect(screen.getByText(mockProduct.productName)).toBeInTheDocument();
-    });
-});
+```bash
+pnpm test                         # all unit tests (vitest run); does NOT collect coverage
+pnpm test src/components/footer   # one file or directory
+pnpm test:watch                   # watch mode
+pnpm test --coverage              # coverage report (thresholds enforced)
+pnpm test --ui                    # Vitest UI
+
+pnpm storybook                                        # dev server on :6006
+pnpm exec playwright install chromium                 # once, for interaction/a11y runs
+pnpm storybook:test --type=snapshot                   # add --update to rewrite snapshots
+pnpm storybook:test --type=interaction                # play() functions in real Chromium
+pnpm storybook:test --type=a11y                       # axe checks
+pnpm storybook:test --type=snapshot --stories=footer  # narrow to matching story paths
 ```
 
-### Test Utilities
+Add `--static` (optionally `--reuse-build` after `pnpm storybook:build`) to run interaction or a11y against a static build. `--coverage` with snapshot generates story tests and reports story coverage.
 
-Shared utilities in `src/test-utils/`:
+Coverage thresholds live inline in `vitest.config.ts` (`thresholds`), and `src/components/ui/**`, stories, snapshot fixtures and `__mocks__` are excluded from coverage. Do not chase 100%.
 
-- `config.ts` — Mock configuration objects and ConfigProvider wrappers
-- `context-provider-utils.ts` — Context provider helpers for testing
-- `context-provider.tsx` — Test context providers
+## Unit test
 
-### Running Tests
-
-```bash
-pnpm test                # Run all tests with coverage
-pnpm test:ui             # Open interactive Vitest UI
-pnpm test:watch          # Watch mode (re-run on changes)
+```tsx
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { AllProvidersWrapper } from '@/test-utils/context-provider';
+import MyThing from './index';
+
+describe('MyThing', () => {
+    it('renders the label', () => {
+        render(<MyThing label="Hello" />, { wrapper: AllProvidersWrapper });
+        expect(screen.getByText('Hello')).toBeInTheDocument();
+    });
+});
 ```
 
-### Coverage Requirements
+`vitest.setup.ts` already provides jest-dom matchers, i18next (`en-GB`), `window.__APP_CONFIG__`, a global mock of `@/hooks/use-analytics`, and a 10s async-util timeout; do not re-add them. Helpers, wrappers and the analytics caveat: [references/UNIT-AND-ROUTE-TESTS.md](references/UNIT-AND-ROUTE-TESTS.md).
+
+## Route loader / action test
 
-Thresholds enforced in `vitest.thresholds.ts`:
+```ts
+import { describe, expect, it, vi } from 'vitest';
+import { createLoaderArgs, createTestContext } from '@/lib/test-utils';
+import { loader } from './resource.basket-products';
 
-| Metric | Minimum |
-|--------|---------|
-| Lines | 73% |
-| Statements | 73% |
-| Functions | 72% |
-| Branches | 67% |
+vi.mock('@/lib/api-clients.server', () => ({ createApiClients: vi.fn() }));
 
-### Testing Libraries
+it('returns data', async () => {
+    const context = createTestContext({ authSession: { userType: 'guest' } });
+    const args = createLoaderArgs(new Request('http://localhost/x'), context, {
+        params: {},
+        pattern: '/' as never,
+    });
+    const result = await loader(args);
+    expect(result).toBeDefined();
+});
+```
 
-- `@testing-library/react` — Component rendering and queries
-- `@testing-library/jest-dom` — Custom DOM matchers (`toBeInTheDocument`, etc.)
-- `@testing-library/user-event` — User interaction simulation
-- `@vitest/coverage-v8` — Code coverage
-- `@vitest/ui` — Interactive test UI
+`createActionArgs` is the action twin and `expectStatus(result, 400)` asserts `data()` statuses. Mock `@/lib/api-clients.server` (SCAPI) at the module boundary, or use MSW for HTTP-level tests. See `storefront-next:sfnext-data-fetching` for the loader patterns under test.
 
-## Storybook
+## Stories
 
-Every reusable component should have a `.stories.tsx` file.
+Stories live in a `stories/` subfolder next to the component (required; coverage tooling only matches there):
 
-### Story Structure
+```
+src/components/footer/
+├── index.tsx
+├── index.test.tsx
+└── stories/
+    ├── index.stories.tsx
+    ├── footer-snapshot.tsx      # snapshot fixture, only where a snapshot test exists
+    └── __snapshots__/
+```
 
-```typescript
-// src/components/product-card/product-card.stories.tsx
+```tsx
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { within, expect } from 'storybook/test';
+import { expect, within } from 'storybook/test';
 import { waitForStorybookReady } from '@storybook/test-utils';
-import { ProductCard } from './product-card';
-import { ConfigProvider } from '@/config/context';
-import { mockConfig } from '@/test-utils/config';
-import { mockProduct } from '@/test-utils/mocks';
-
-const meta: Meta<typeof ProductCard> = {
-    title: 'Components/ProductCard',
-    component: ProductCard,
+import { mockProductSearchItem } from '@/components/__mocks__/product-search-hit-data';
+import ProductTile from '../index';
+
+const meta: Meta<typeof ProductTile> = {
+    title: 'Products/Product Tile', // Domain/Component from the fixed sidebar groups
+    component: ProductTile,
     tags: ['autodocs', 'interaction'],
-    decorators: [
-        (Story) => (
-            <ConfigProvider config={mockConfig}>
-                <Story />
-            </ConfigProvider>
-        ),
-    ],
 };
-
 export default meta;
-type Story = StoryObj<typeof ProductCard>;
+type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-    args: {
-        product: mockProduct,
-    },
+    args: { product: mockProductSearchItem },
     play: async ({ canvasElement }) => {
         await waitForStorybookReady(canvasElement);
-        const canvas = within(canvasElement);
-        await expect(canvas.getByText(mockProduct.productName)).toBeInTheDocument();
+        await expect(within(canvasElement).getAllByRole('link')[0]).toBeInTheDocument();
     },
 };
 ```
 
-See [Storybook Patterns Reference](references/STORYBOOK-PATTERNS.md) for advanced patterns.
-
-### Storybook Commands
-
-```bash
-pnpm storybook                              # Dev server (port 6006)
-pnpm build-storybook                        # Build static Storybook
-pnpm test-storybook:snapshot                # Snapshot tests
-pnpm test-storybook:snapshot:update         # Update snapshots
-pnpm test-storybook:interaction             # Interaction tests
-pnpm test-storybook:a11y                    # Accessibility tests
-pnpm generate:story-tests:coverage          # Story coverage report
-```
-
-### Story Tags
+Rules of thumb:
 
-| Tag | Purpose |
-|-----|---------|
-| `autodocs` | Enable automatic documentation |
-| `interaction` | Include in interaction test runs |
-| `skip-a11y` | Exclude from a11y tests (use sparingly) |
+- Every story is already wrapped by a global decorator (memory router + config, site, i18n, auth, basket providers). Do not add your own `ConfigProvider`. If you truly need one, import it from `@salesforce/storefront-next-runtime/config`.
+- Import test helpers from `storybook/test` (not `@storybook/test`).
+- Props first; mock at the route boundary with `parameters` (`routeLoaderData`, `scapiMock`, `miniCartData`, `mockRoutes`), never `vi.mock` of hooks inside a story. Args must be JSON-serializable.
+- Tags: `autodocs` (docs page), `interaction` (included in interaction runs), `skip-a11y` (excluded from a11y runs; use sparingly and comment why).
+- Use Storybook's viewport toolbar instead of separate mobile/desktop stories.
+- Fixtures: `@/components/__mocks__` (barrel of curated fixtures) or `@/components/__mocks__/<file>` for ones not re-exported; shared with unit tests.
 
-## Route Testing
+Full reference, including parameters, mock routes, taxonomy and argTypes: [references/STORYBOOK-PATTERNS.md](references/STORYBOOK-PATTERNS.md).
 
-Mock loaders, actions, and React Router context:
+## End to end
 
-```typescript
-// src/routes/_app.product.$productId.test.tsx
-import { describe, test, expect, vi } from 'vitest';
-import { render } from '@testing-library/react';
+`e2e/` is a separate CodeceptJS + Playwright project with its own `AGENTS.md`. Run `pnpm e2e` (add `--mode=local` to start the dev server, `--grep "@checkout"`, `--headed`). To author tests, use the skills shipped in your project at `e2e/.claude/skills/generate-storefront-e2e-test` and `e2e/.claude/skills/checkout-test-development`. Setup, env vars and the `pnpm a11y` scan: [references/E2E.md](references/E2E.md).
 
-vi.mock('@/components/product-view', () => ({
-    default: ({ product }: any) => (
-        <div data-testid="product-view">
-            <div data-testid="product-name">{product?.name}</div>
-        </div>
-    ),
-}));
-```
+## Pitfalls
 
-## Test Organization
-
-```
-src/
-├── components/
-│   ├── product-card/
-│   │   ├── index.tsx              # Component
-│   │   ├── index.test.tsx         # Unit tests
-│   │   └── stories/
-│   │       └── index.stories.tsx  # Stories
-├── routes/
-│   ├── _app.product.$productId.tsx
-│   └── _app.product.$productId.test.tsx
-└── test-utils/                    # Shared utilities
-    ├── config.ts
-    └── context-provider-utils.ts
-```
-
-## Best Practices
-
-1. **Colocate tests** — Keep test files next to source files
-2. **Use test utilities** — Leverage `@/test-utils` for mocks and providers
-3. **Mock external dependencies** — Use `vi.mock()` for API clients and context
-4. **Test interactions** — Use `@testing-library/user-event` and Storybook play functions
-5. **Test accessibility** — Use Storybook a11y addon
-6. **Multiple story variants** — Create stories for Default, Loading, Error states
-7. **Use viewport toolbar** — Test responsive layouts via Storybook's built-in viewport toolbar
+| Pitfall | Fix |
+|---------|-----|
+| Story outside `stories/` | Move it; coverage and generated snapshot tests only find `stories/*.stories.tsx`. |
+| Interaction/a11y run fails to launch a browser | `pnpm exec playwright install chromium`. |
+| Snapshot diff after an intentional DOM change | Review it, then `pnpm storybook:test --type=snapshot --update`. |
+| Test passes but analytics never fires | `@/hooks/use-analytics` is mocked globally; `vi.unmock` it in the test to assert on track calls. |
+| Portalled dialog/toast not found in a play function | Query `within(canvasElement.ownerDocument.body)`. |
+| Mocking too deep | If an internal refactor forces story edits, push the mock to the route/fixture layer. |
 
 ## Related Skills
 
-- `storefront-next:sfnext-components` - Component patterns that need testing
-- `storefront-next:sfnext-data-fetching` - Mocking loaders and actions in tests
-- `storefront-next:sfnext-page-designer` - Testing Page Designer components
-
-## Reference Documentation
-
-- [Storybook Patterns Reference](references/STORYBOOK-PATTERNS.md) - Advanced story patterns and testing
+- `storefront-next:sfnext-quality-gates` - lint, typecheck, format and the pre-PR checklist
+- `storefront-next:sfnext-accessibility` - a11y assertions in stories and the e2e axe scan
+- `storefront-next:sfnext-components` - component conventions under test
+- `storefront-next:sfnext-data-fetching` - loaders and actions
+- `storefront-next:sfnext-page-designer` - testing Page Designer components
+- `storefront-next:sfnext-i18n` - translations in tests

package/content/guidance/storefront-next/sfnext-testing/references/E2E.md

@@ -0,0 +1,38 @@
+# End-to-end tests
+
+`e2e/` is a standalone CodeceptJS + Playwright project shipped with your storefront, with its own `e2e/AGENTS.md`, `e2e/README.md`, `e2e/docs/`, and in-project skills:
+
+- `e2e/.claude/skills/generate-storefront-e2e-test/SKILL.md`: structured workflow for new specs, page objects, flows and self-healing recipes.
+- `e2e/.claude/skills/checkout-test-development/`: checkout-specific E2E, debugging and performance guidance.
+
+Use those skills when authoring or debugging e2e tests; this page only orients you.
+
+## Setup
+
+```bash
+cp e2e/.env.sample e2e/.env     # BASE_URL, SITE_ID, SITE_ALIAS, LOCALE, HEADLESS, ...
+pnpm install                    # per e2e/README.md this also installs Playwright browsers; if not, pnpm exec playwright install chromium
+```
+
+The storefront itself needs its own `.env` (see `storefront-next:sfnext-configuration`).
+
+## Run
+
+```bash
+pnpm e2e                        # against a running storefront (BASE_URL, default http://localhost:5173)
+pnpm e2e --mode=local           # start the dev server automatically
+pnpm e2e --mode=remote          # BASE_URL must point at the deployed storefront
+pnpm e2e --grep "@checkout"     # filter by tag or name
+pnpm e2e --headed               # show the browser
+pnpm e2e --debug                # Playwright Inspector
+pnpm e2e:turnstile              # Turnstile-specific suite
+pnpm a11y                       # axe scans of key pages, desktop + mobile (see sfnext-accessibility)
+```
+
+The root scripts above delegate to `e2e/`; you do not need to run them from inside it.
+
+## Keep in mind
+
+- E2E runs against real backend data; prefer unit tests and stories for logic and visual states, and keep e2e for shopper journeys (search, PDP to cart, checkout, login).
+- Optional AI healing is off unless you pass `--ai` and set `ANTHROPIC_API_KEY` in `e2e/.env`.
+- `e2e/` is excluded from the root OxLint/Vitest runs and has its own `lint`, `format:check`, `typecheck` and `test` scripts (run from `e2e/`).

package/content/guidance/storefront-next/sfnext-testing/references/STORYBOOK-PATTERNS.md

@@ -1,118 +1,97 @@
-# Storybook Patterns Reference
+# Storybook patterns
 
-## Story File Structure
+Source of truth in your project: `docs/README-STORYBOOK.md`, `.storybook/`, and the existing `stories/` folders. Copy a neighbor story before inventing structure.
 
-```typescript
-// src/components/my-component/stories/index.stories.tsx
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { within, expect, userEvent } from 'storybook/test';
-import { waitForStorybookReady } from '@storybook/test-utils';
-import { MyComponent } from '../my-component';
-import { ConfigProvider } from '@/config/context';
-import { mockConfig } from '@/test-utils/config';
-
-const meta: Meta<typeof MyComponent> = {
-    title: 'Components/MyComponent',
-    component: MyComponent,
-    tags: ['autodocs', 'interaction'],
-    decorators: [
-        (Story) => (
-            <ConfigProvider config={mockConfig}>
-                <Story />
-            </ConfigProvider>
-        ),
-    ],
-};
-
-export default meta;
-type Story = StoryObj<typeof MyComponent>;
+## Principles
+
+1. Props first. Reach for the global provider/router stack only when the component reads global context (auth, basket, site, locale).
+2. Mock at the boundary. Prefer `parameters.routeLoaderData`, `parameters.scapiMock`, `parameters.mockRoutes` over `vi.mock` of hooks.
+3. Args are JSON-serializable. Promises, class instances and functions returning promises break the Controls panel and snapshot serialization; put them in `parameters`.
+4. One reason to update a mock. If an internal refactor forces story edits, the mock is too deep.
+
+## Decorator stack
+
+`.storybook/preview.tsx` applies `decorators: [withRouter(StoryShell)]` to every story:
+
+```
+withRouter(StoryShell)        in-memory React Router with default mock routes
+  StoryShell
+    StorybookWrapper          config + site + i18n + auth + basket + storeLocator + checkoutOneClick
+      UITargetProviders
+        <Story />
 ```
 
-## Story Variants
+Files: `.storybook/decorators/{with-router,with-providers,with-ui-targets,mock-routes}.tsx|ts`. Because of this, a story usually needs no per-story `ConfigProvider` or `SiteProvider`. If you do need to override config for one story, wrap with `ConfigProvider` from `@salesforce/storefront-next-runtime/config` and `SiteProvider` from `@salesforce/storefront-next-runtime/site-context`, using `mockConfig`, `mockLocale`, `mockSiteObject` from `@/test-utils/config` (see `src/components/footer/stories/index.stories.tsx`).
 
-Create stories for different component states:
+## Story parameters
 
-```typescript
-export const Default: Story = {
-    args: { title: 'Default Title' },
-};
+| Parameter | Use |
+|-----------|-----|
+| `routeLoaderData: Record<string, unknown>` | Wrap the story in ancestor routes so `useRouteLoaderData(routeId)` resolves. Required for components that read a parent route's loader data. |
+| `scapiMock: { data?: unknown }` | Override the default `/resource/api/client/:resource` response, for stories whose `play()` asserts specific product data. |
+| `miniCartData: { basket, productsById }` | Override what `/resource/basket-products` returns (for example an empty cart). |
+| `mockRoutes: RouteObject[]` | Add story-specific `/resource/*` or `/action/*` routes. Must not shadow `/`, `*` or a default mock path; `withRouter` throws on conflicts. |
 
-export const Loading: Story = {
-    args: { isLoading: true },
-};
+`buildDefaultMockRoutes` (in `.storybook/decorators/mock-routes.ts`) lists the default routes: basket enrichment, cart mutations, wishlist, OTP, product/bundle/set adds, site-context updates, tracking consent, place-order.
 
-export const Error: Story = {
-    args: { error: 'Something went wrong' },
-};
+## Titles and sidebar
 
-export const Empty: Story = {
-    args: { items: [] },
-};
-```
+`meta.title` is `Domain/Component` or `Domain/Subgroup/Component`, Title Case With Spaces. Top-level groups: Account, Authentication, Cart, Category, Checkout, Content, Core, Design System, Extensions, Home, Layout, Products, Search. Pick the closest existing group by purpose, not by folder. This is a convention, not lint-enforced, and you may restructure it for your brand.
+
+## Naming and layout
 
-## Interaction Tests (Play Functions)
+| Thing | Convention |
+|-------|-----------|
+| Story file | `*.stories.tsx` in `stories/` next to the component (required) |
+| Story export | PascalCase state name: `Default`, `Loading`, `InvalidEmailError` |
+| Snapshot fixture | `<name>-snapshot.tsx` next to the story, with `__snapshots__/` beside it |
+| shadcn primitives in `src/components/ui/` | No stories or coverage requirement |
 
-```typescript
-export const WithInteraction: Story = {
-    args: { title: 'Interactive' },
-    play: async ({ canvasElement }) => {
-        await waitForStorybookReady(canvasElement);
-        const canvas = within(canvasElement);
+Default to one component per folder. Snapshot fixtures use `StoryTestWrapper` from `@storybook/test-utils`; copy an existing `*-snapshot.tsx` pair (for example under `src/components/footer/stories/`).
 
-        // Assert initial state
-        await expect(canvas.getByText('Interactive')).toBeInTheDocument();
+## argTypes
 
-        // Simulate user interaction
-        const button = canvas.getByRole('button');
-        await userEvent.click(button);
+Expose only what visibly drives the canvas:
 
-        // Assert result
-        await expect(canvas.getByText('Clicked!')).toBeInTheDocument();
-    },
-};
+```tsx
+argTypes: {
+    label: { control: 'text', description: 'Label in the summary row' },
+    className: { control: false, table: { disable: true } },
+    onCancel: { action: 'cancel' },
+}
 ```
 
-## Decorators
-
-Wrap stories with required providers:
-
-```typescript
-// Single provider
-decorators: [
-    (Story) => (
-        <ConfigProvider config={mockConfig}>
-            <Story />
-        </ConfigProvider>
-    ),
-],
-
-// Multiple providers
-decorators: [
-    (Story) => (
-        <ConfigProvider config={mockConfig}>
-            <AuthProvider auth={mockAuth}>
-                <Story />
-            </AuthProvider>
-        </ConfigProvider>
-    ),
-],
+## play() functions
+
+```tsx
+import { expect, userEvent, within } from 'storybook/test';
+import { waitForStorybookReady } from '@storybook/test-utils';
+
+play: async ({ canvasElement }) => {
+    await waitForStorybookReady(canvasElement);
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole('button', { name: /add to cart/i }));
+    await expect(canvas.getByRole('status')).toHaveTextContent(/added/i);
+},
 ```
 
-## Responsive Testing
+- Tag the story `interaction` so it runs in `--type=interaction`.
+- Dialogs, popovers and toasts render into `document.body`; use `within(canvasElement.ownerDocument.body)`.
+- Assert outcomes (role, accessible name, focus, text), not CSS classes.
+- To re-render a story when an arg changes (keyed state), key the component on that prop.
 
-Use Storybook's built-in viewport toolbar instead of creating separate Mobile/Tablet/Desktop stories. The viewport selector in the toolbar lets you test components at different screen sizes interactively.
+## Accessibility in stories
 
-## Accessibility Testing
+The a11y addon mode is `todo` (reports, does not fail) by default. `pnpm storybook:test --type=a11y` runs with `STORYBOOK_A11Y_TEST_MODE=error`. `STORYBOOK_DISABLE_A11Y=true` turns it off. Tag `skip-a11y` excludes a story from a11y runs. To make one file strict regardless, spread `{ a11y: { test: 'error' } }` into its `parameters` (see `src/components/checkout/storybook/checkout-strict-a11y-parameters.ts`). See `storefront-next:sfnext-accessibility`.
 
-Stories with the `autodocs` tag are automatically included in a11y test runs. Use `skip-a11y` only for stories that intentionally violate a11y rules (e.g., testing error states):
+## Story coverage
 
-```typescript
-export const ErrorState: Story = {
-    tags: ['skip-a11y'],
-    args: { error: 'Missing required field' },
-};
-```
+Stories count toward component coverage when they match the component path (`cart/cart-content.tsx` maps to `cart/stories/cart-content.stories.tsx`; `index.tsx` maps to `stories/index.stories.tsx`). `pnpm storybook:test --type=snapshot --coverage` generates story tests and reports; details in `docs/README-STORY-COVERAGE.md`.
 
-## Story Coverage
+## Anti-patterns
 
-Run `pnpm generate:story-tests:coverage` to check which components have stories and which need them. Every reusable component in `src/components/` should have a corresponding `.stories.tsx` file.
+- Recreating the component's data shape as a giant literal instead of passing a fixture.
+- Promises in `args`.
+- `vi.mock` of hooks inside a story.
+- Separate Mobile/Tablet/Desktop stories (use the viewport toolbar).
+- Novel top-level title groups.

package/content/guidance/storefront-next/sfnext-testing/references/UNIT-AND-ROUTE-TESTS.md

@@ -0,0 +1,60 @@
+# Unit and route tests
+
+## Environment (`vitest.config.ts`, `vitest.setup.ts`)
+
+- jsdom, `globals: true`, `@/` alias, `testTimeout` 15s, Testing Library `asyncUtilTimeout` 10s, `pool: 'forks'` on Windows.
+- Setup already: jest-dom matchers, `window.__APP_CONFIG__ = mockConfig`, i18next initialized with all locales (language `en-GB`), `vitest-localstorage-mock`, and a global mock of `@/hooks/use-analytics`.
+- The global analytics mock means a missing `track*` call will not fail an ordinary test. To assert on tracking, call `vi.unmock('@/hooks/use-analytics')` in a `beforeEach` and provide your own spy implementation.
+- Static assets and `virtual:action-hooks` are aliased to mocks.
+
+## Helper inventory
+
+`@/test-utils/*` (src/test-utils):
+
+| Import | Provides |
+|--------|----------|
+| `@/test-utils/config` | `mockConfig`, `mockBuildConfig`, `mockSiteObject`, `mockAltSiteObject`, `mockLocale`, `getSitePrefix`, `ConfigWrapper`, `createConfigWrapper(overrides)` |
+| `@/test-utils/context-provider` | `ConfigWrapper`, `AllProvidersWrapper` (config + site + store locator + UI targets; props `config`, `currency`) |
+| `@/test-utils/auth` | `buildMockAccessToken`, `buildMockTokenResponse` |
+| `@/test-utils/request-helpers` | `createFormDataRequest(url, method, data)` |
+| `@/test-utils/wishlist` | `resetWishlistStore`, `seedWishlistStore` |
+| `@/test-utils/page-designer-host-provider` | `PageDesignerHostProvider` |
+
+`@/lib/test-utils` (src/lib/test-utils):
+
+| Export | Use |
+|--------|-----|
+| `createTestContext(opts)` | A `RouterContextProvider` with auth, app config, i18n, site (locale/currency), maintenance and performance-timer contexts. Options: `authSession` (`null` for no session), `rejectAuth`/`authError`, `appConfig`, `locale` (default `en-GB`), `currency` (default `GBP`), `skipI18next`. |
+| `createLoaderArgs(request, context, { params, pattern })` | Full `LoaderFunctionArgs`; pass `<Route.LoaderArgs>` as type parameter for typed loaders. |
+| `createActionArgs(...)` | Same for actions. |
+| `ROUTE_PATTERN` | Safe placeholder for `pattern`. |
+| `expectStatus(result, 400)` | Assert status of a `data()` response (missing status counts as 200). |
+
+Fixtures: `@/components/__mocks__` (and `@/components/__mocks__/<file>`), for example `basketWithOneItem`, `emptyBasket`, `masterProduct`, `mockStandardProductOrderable`, `mockCategories`.
+
+## Loader/action pattern
+
+Model new tests on `src/routes/resource.basket-products.test.ts` and the `_app.p.$.loader.test.ts` / `_app.cart.test.tsx` route tests:
+
+1. `vi.mock('@/lib/api-clients.server', () => ({ createApiClients: vi.fn() }))` and return fake SCAPI clients per test.
+2. Mock `@/middlewares/basket.server` (`getBasket`) or auth helpers if the route reads them.
+3. Build context with `createTestContext`, args with `createLoaderArgs`/`createActionArgs`, call the exported `loader`/`action`.
+4. Assert the returned object, thrown `Response`, or `expectStatus`.
+5. For routes exporting `shouldRevalidate`, call it directly (see `docs/README-REVALIDATION.md`).
+
+Use `createFormDataRequest` for action input.
+
+## MSW
+
+`msw` is a dev dependency. For HTTP-level tests use `setupServer` from `msw/node` and `http`/`HttpResponse` from `msw` (example: `src/components/checkout/checkout-flow.test.tsx`). Start the server in `beforeAll`, `resetHandlers` in `afterEach`, `close` in `afterAll`.
+
+## Hooks and components
+
+- Hooks: `renderHook(() => useX(), { wrapper: ConfigWrapper })` with the wrapper from `@/test-utils/config`.
+- Components needing site/config/UI targets: `render(ui, { wrapper: AllProvidersWrapper })`.
+- Component tests that mock `react-router` must provide every export the component tree uses.
+- Prefer `userEvent` from `@testing-library/user-event` over `fireEvent`, and role-based queries.
+
+## i18n in tests
+
+See `storefront-next:sfnext-i18n`: i18next is initialized globally; use `createTestContext({ locale })` for loaders.