# React Testable Storybookable

> Scaffolds React components that are jointly unit-testable and Storybook-ready with MSW and clear seams. Use this skill when creating new components that need tests and stories from day one. Do not use when/for end-to-end browser automation (use agent-browser) or journey-level Storybook docs without scaffolding (use storybook-journeys).

- Skill: `jagreehal/react-testable-storybookable` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add jagreehal/react-testable-storybookable`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/react-testable-storybookable/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/react-testable-storybookable

---


# React Testable & Storybookable

## Critical rules

- A component may depend on **props** and **injectable context** only — never network, router, or an unoverridable global store.
- Testability and storybookability are the same property: shared fixtures, shared MSW, shared providers.
- Leaf/presentational stays props-only; push fetching into a thin container.
- Hooks surface explicit `idle` / `loading` / `success` / `error`; React Query uses a key factory.
- One MSW handler/fixture set backs Vitest, Storybook, and optional local mocks.
- Ship the trio: `Component.tsx` + `Component.stories.tsx` + `Component.test.tsx`.
- Export props types; type stories from them. `QueryClient` in tests has `retry: false`.
- Before scaffolding harness files or WRONG/CORRECT samples, read the matching resource below.

## Workflow

1. Classify tier: leaf (props), container (hooks + providers), or provider/boundary.
2. Keep API/router out of the leaf; pass data and callbacks as props.
3. Before writing harness or MSW boilerplate, read [references/scaffold.md](references/scaffold.md).
4. Add `renderWithProviders` (theme, router, QueryClient with retries off) and shared fixtures/handlers with failure injection + store reset.
5. For containers that read context, add a test-only provider implementing the same `state` / `actions` / `meta` contract.
6. Scaffold the file trio: `scripts/scaffold-component.sh <ComponentName> [target-dir]` (see `--help`).
7. Stories: Default, Empty, Loading, Error; handlers via `fn()`. Import shared fixtures.
8. Wire Storybook `preview` with MSW + providers + a11y addon.
9. For WRONG/CORRECT prop, hook, and story patterns, read [references/examples.md](references/examples.md).

## Resources

- [references/examples.md](references/examples.md) — prop-driven, keys/hooks, MSW, trio, test provider. Read when implementing.
- [references/scaffold.md](references/scaffold.md) — copy-paste harness: utils, MSW, providers, decorators. Read when setting up a project.
- [scripts/scaffold-component.sh](scripts/scaffold-component.sh) — generates the component/stories/test trio. Run with `--help` for usage; refuse overwrite.

## Validation

- [ ] Leaf depends only on props + injectable context
- [ ] Explicit status / key factory for hooks
- [ ] Trio present; stories cover Default, Empty, Loading, Error with `fn()`
- [ ] Stories and tests share fixtures; containers use `renderWithProviders` + MSW
- [ ] `QueryClient` retry off; store reset between tests
- [ ] Storybook preview wires MSW + providers + a11y

## Constraints

- Page-level flows belong in `storybook-journeys`. Visual tokens in `ui-design-principles`. Architecture baseline in `react-development`.
- Adjacent: `result-types`, `testing-strategy`, `validation-boundary`. Prefer composition patterns over boolean-prop sprawl.