[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7FBVMY8DV3B5SC20VWYAJVH":3,"skill-same:01M7FBVMY8DV3B5SC20VWYAJVH":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":28,"install":29,"resources":42},"01M7FBVMY8DV3B5SC20VWYAJVH","react-testing-library",null,"General-purpose React Testing Library guide with Vitest. Use when writing, reviewing, or setting up React component and hook tests. Covers project setup from scratch, RTL query priority, userEvent, async patterns, mocking strategies, and common anti-patterns. Applicable to any Vite + React project.","marynabieliaieva\u002Fdev-ai-harness-marketplace","marynabieliaieva","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F7878548?v=4","01M7FBT0ZD7GRRYKNENTZ5EH2T","01M7FBT101PH91MN21MJ7XTKMY",0,"MIT","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fengineering-paved-path\u002Fskills\u002Freact-testing-library\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: react-testing-library\ndescription: \"General-purpose React Testing Library guide with Vitest. Use when writing, reviewing, or setting up React component and hook tests. Covers project setup from scratch, RTL query priority, userEvent, async patterns, mocking strategies, and common anti-patterns. Applicable to any Vite + React project.\"\n---\n\n# React Testing Library\n\nGeneral-purpose guide for testing React components and hooks with React Testing Library (RTL) and Vitest. Project-agnostic — works with any Vite + React setup.\n\n## Philosophy: Fewer Tests, Real Scenarios\n\n> \"Write tests. Not too many. Mostly integration.\" — Kent C. Dodds\n\n1. **Use-case coverage > code coverage** — aim for 100% use-case coverage, not 100% line coverage. Think about what the user can DO, not what the code does internally.\n2. **Write fewer, longer tests** — one test that walks through a full user flow beats six isolated assertions. Combine related steps (render → interact → verify) into a single test.\n3. **Test behavior, not implementation** — assert on what the user sees and can do. Never assert on internal state, hook calls, or DOM structure.\n4. **Mock at boundaries only** — mock API calls and external services. Never mock your own components, hooks, or context internals.\n5. **Each test must justify its existence** — if removing a test wouldn't reduce your confidence that the app works, delete it.\n\n### The Testing Trophy (what to invest in)\n\n```\n    E2E        ← Few: critical user journeys only (Playwright\u002FCypress)\n  Integration  ← MOST tests: components with real providers, MSW for APIs\n  Unit         ← Some: complex pure logic, utilities, formatters\nStatic Analysis ← Always: TypeScript, ESLint\n```\n\n---\n\n## Setup from Scratch\n\n### 1. Install Dependencies\n\n```bash\nnpm install -D vitest @testing-library\u002Freact @testing-library\u002Fjest-dom @testing-library\u002Fuser-event jsdom\n```\n\nOptional but recommended:\n```bash\nnpm install -D msw                     # Network-level API mocking\nnpm install -D @vitest\u002Fcoverage-v8     # Code coverage\n```\n\n### 2. Vitest Config\n\nCreate `vitest.config.js` at the client root (or extend `vite.config.js`):\n\n```js\nimport { defineConfig, mergeConfig } from 'vitest\u002Fconfig';\nimport viteConfig from '.\u002Fvite.config.js';\n\nexport default mergeConfig(viteConfig, defineConfig({\n  test: {\n    globals: true,\n    environment: 'jsdom',\n    setupFiles: ['.\u002Fsrc\u002Ftest\u002Fsetup.js'],\n    css: true,\n    include: ['src\u002F**\u002F*.test.{js,jsx,ts,tsx}'],\n  },\n}));\n```\n\n### 3. Setup File\n\nCreate `src\u002Ftest\u002Fsetup.js`:\n\n```js\nimport '@testing-library\u002Fjest-dom\u002Fvitest';\n```\n\nThis registers matchers like `toBeInTheDocument()`, `toBeVisible()`, `toHaveTextContent()`.\n\n### 4. Package Scripts\n\nAdd to `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"test:coverage\": \"vitest run --coverage\"\n  }\n}\n```\n\n---\n\n## Test Scenarios by Component Type\n\nBefore writing tests, identify the component type and pick scenarios from this matrix. Write **1-3 tests per component** — each test covers a full user flow, not a single assertion.\n\n### Form Component (e.g., BlogEditor, LoginForm, CommentForm)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Happy path: fill all fields → submit → success feedback** | Rendering, typing, validation passing, API call, success state |\n| 2 | **Validation: submit empty\u002Finvalid → error messages appear** | Required fields, validation rules, error rendering |\n| 3 | **API failure: fill valid → submit → server error shown** | Error handling, error UI, form stays filled |\n\n### List\u002FTable Component (e.g., BlogList, CommentList, Dashboard)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Happy path: data loads → items render → user interacts** | Loading state, data rendering, click\u002Fnavigation |\n| 2 | **Empty state: no data → empty message shown** | Zero-data handling |\n| 3 | **Error state: API fails → error message shown** | Network failure handling |\n\n### Detail\u002FView Component (e.g., BlogDetail, UserProfile)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Happy path: data loads → full content renders → user actions work** | Data fetching, rendering, interactions (edit\u002Fdelete\u002Fcomment) |\n| 2 | **Not found \u002F error: invalid ID → appropriate message** | 404 handling, error boundaries |\n\n### Auth-Gated Component (e.g., AdminPanel, ProtectedRoute)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Authenticated: user sees protected content and can interact** | Auth context, content rendering, user actions |\n| 2 | **Unauthenticated: redirects or shows login prompt** | Guard behavior, redirect |\n\n### Shared\u002FPresentational Component (e.g., BlogCard, Button, Modal)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Renders with props and handles user interaction** | Props → UI mapping, click\u002Fhover callbacks |\n| 2 | **Conditional rendering: different props → different output** | Only if the component has meaningful branching |\n\n---\n\n## Complete Spec Template\n\nThis is what a well-structured test file looks like. Each test walks through a real user flow.\n\n```jsx\n\u002F\u002F BlogList.test.jsx\nimport { describe, it, expect, vi, beforeEach } from 'vitest';\nimport { render, screen, within } from '@testing-library\u002Freact';\nimport userEvent from '@testing-library\u002Fuser-event';\nimport { MemoryRouter } from 'react-router';\nimport { http, HttpResponse } from 'msw';\nimport { setupServer } from 'msw\u002Fnode';\nimport BlogList from '.\u002FBlogList';\n\n\u002F\u002F --- MSW setup: mock the API at the network level ---\nconst blogs = [\n  { _id: '1', title: 'First Post', category: 'Technology', excerpt: 'About tech' },\n  { _id: '2', title: 'Second Post', category: 'Startup', excerpt: 'About startups' },\n];\n\nconst server = setupServer(\n  http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json({ success: true, blogs })),\n);\n\nbeforeAll(() => server.listen());\nafterEach(() => server.resetHandlers());\nafterAll(() => server.close());\n\n\u002F\u002F --- Render helper (keeps tests DRY) ---\nconst renderBlogList = () =>\n  render(\u003CMemoryRouter>\u003CBlogList \u002F>\u003C\u002FMemoryRouter>);\n\n\u002F\u002F --- Tests: 3 tests covering ALL real scenarios ---\ndescribe('BlogList', () => {\n  it('loads blogs and lets user navigate to a post', async () => {\n    const user = userEvent.setup();\n    renderBlogList();\n\n    \u002F\u002F Loading state appears first\n    expect(screen.getByText(\u002Floading\u002Fi)).toBeInTheDocument();\n\n    \u002F\u002F Blogs appear after fetch\n    expect(await screen.findByText('First Post')).toBeInTheDocument();\n    expect(screen.getByText('Second Post')).toBeInTheDocument();\n\n    \u002F\u002F User clicks a blog card\n    await user.click(screen.getByRole('link', { name: \u002Ffirst post\u002Fi }));\n    \u002F\u002F Assert navigation happened (or verify detail view renders)\n  });\n\n  it('shows empty state when no blogs exist', async () => {\n    server.use(\n      http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json({ success: true, blogs: [] })),\n    );\n    renderBlogList();\n\n    expect(await screen.findByText(\u002Fno blogs\u002Fi)).toBeInTheDocument();\n    expect(screen.queryByRole('article')).not.toBeInTheDocument();\n  });\n\n  it('shows error message when API fails', async () => {\n    server.use(\n      http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json(\n        { success: false, message: 'Server error' },\n        { status: 500 },\n      )),\n    );\n    renderBlogList();\n\n    expect(await screen.findByRole('alert')).toBeInTheDocument();\n    expect(screen.queryByRole('article')).not.toBeInTheDocument();\n  });\n});\n```\n\n### Form Spec Template\n\n```jsx\n\u002F\u002F LoginForm.test.jsx\ndescribe('LoginForm', () => {\n  it('logs in with valid credentials and shows dashboard', async () => {\n    const user = userEvent.setup();\n    render(\u003CMemoryRouter>\u003CLoginForm \u002F>\u003C\u002FMemoryRouter>);\n\n    \u002F\u002F Fill form\n    await user.type(screen.getByLabelText(\u002Femail\u002Fi), 'admin@test.com');\n    await user.type(screen.getByLabelText(\u002Fpassword\u002Fi), 'password123');\n    await user.click(screen.getByRole('button', { name: \u002Fsign in\u002Fi }));\n\n    \u002F\u002F Success: redirected or success message\n    expect(await screen.findByText(\u002Fwelcome\u002Fi)).toBeInTheDocument();\n  });\n\n  it('shows validation errors when submitted empty', async () => {\n    const user = userEvent.setup();\n    render(\u003CMemoryRouter>\u003CLoginForm \u002F>\u003C\u002FMemoryRouter>);\n\n    await user.click(screen.getByRole('button', { name: \u002Fsign in\u002Fi }));\n\n    \u002F\u002F Both fields show errors\n    expect(await screen.findByText(\u002Femail is required\u002Fi)).toBeInTheDocument();\n    expect(screen.getByText(\u002Fpassword is required\u002Fi)).toBeInTheDocument();\n\n    \u002F\u002F Form is still visible (not redirected)\n    expect(screen.getByRole('button', { name: \u002Fsign in\u002Fi })).toBeInTheDocument();\n  });\n\n  it('shows server error when API returns 401', async () => {\n    server.use(\n      http.post('\u002Fapi\u002Fadmin\u002Flogin', () =>\n        HttpResponse.json({ success: false, message: 'Invalid credentials' }, { status: 401 }),\n      ),\n    );\n    const user = userEvent.setup();\n    render(\u003CMemoryRouter>\u003CLoginForm \u002F>\u003C\u002FMemoryRouter>);\n\n    await user.type(screen.getByLabelText(\u002Femail\u002Fi), 'admin@test.com');\n    await user.type(screen.getByLabelText(\u002Fpassword\u002Fi), 'wrongpassword');\n    await user.click(screen.getByRole('button', { name: \u002Fsign in\u002Fi }));\n\n    expect(await screen.findByText(\u002Finvalid credentials\u002Fi)).toBeInTheDocument();\n  });\n});\n```\n\n---\n\n## Import Rules\n\n```js\n\u002F\u002F Test runner — ALWAYS from vitest\nimport { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';\n\n\u002F\u002F RTL — render, screen, waitFor\nimport { render, screen, waitFor, within } from '@testing-library\u002Freact';\n\n\u002F\u002F User interaction — ALWAYS userEvent, NEVER fireEvent\nimport userEvent from '@testing-library\u002Fuser-event';\n\n\u002F\u002F Hook testing\nimport { renderHook, act } from '@testing-library\u002Freact';\n```\n\nNEVER import from `jest`. Use `vi.fn()`, `vi.spyOn()`, `vi.mock()`.\n\n---\n\n## Query Priority\n\nQueries are ordered by how closely they reflect user experience.\n\n### Tier 1 — Accessible (default choice)\n\n| Query | Use For |\n|-------|---------|\n| `getByRole` | Buttons, links, headings, inputs, checkboxes, comboboxes — **always try first** |\n| `getByLabelText` | Form fields with a `\u003Clabel>` |\n| `getByPlaceholderText` | Inputs without a label (prefer adding a label instead) |\n| `getByText` | Static text content — paragraphs, spans, error messages |\n| `getByDisplayValue` | Input with a current value |\n\n### Tier 2 — Semantic\n\n| Query | Use For |\n|-------|---------|\n| `getByAltText` | Images |\n| `getByTitle` | Elements with `title` attribute |\n\n### Tier 3 — Last resort\n\n| Query | Use For |\n|-------|---------|\n| `getByTestId` | Only when no accessible query works; requires `data-testid` |\n\n### Query Variants\n\n| Variant | Returns | Use When |\n|---------|---------|----------|\n| `getBy` | Element or throws | Element **must** be present |\n| `queryBy` | Element or `null` | Asserting element does **not** exist |\n| `findBy` | Promise\\\u003CElement\\> | Element appears **after** an async operation |\n| `*AllBy` | Array variants | Multiple matching elements |\n\n### Role Query Patterns\n\n```\ngetByRole('button', { name: \u002Fsubmit\u002Fi })\ngetByRole('heading', { level: 2 })\ngetByRole('textbox', { name: \u002Femail\u002Fi })\ngetByRole('link', { name: \u002Fread more\u002Fi })\ngetByRole('checkbox', { name: \u002Fagree\u002Fi })\ngetByRole('combobox')              \u002F\u002F \u003Cselect>\ngetByRole('status')                \u002F\u002F role=\"status\"\ngetByRole('alert')                 \u002F\u002F role=\"alert\"\ngetByRole('dialog')                \u002F\u002F \u003Cdialog> or role=\"dialog\"\ngetByRole('navigation')            \u002F\u002F \u003Cnav>\n```\n\n---\n\n## userEvent\n\nAlways call `userEvent.setup()` before rendering. All methods are async.\n\n| Method | Purpose |\n|--------|---------|\n| `user.click(el)` | Click |\n| `user.dblClick(el)` | Double-click |\n| `user.type(el, 'text')` | Type text (appends to existing value) |\n| `user.clear(el)` | Clear input value |\n| `user.selectOptions(el, 'value')` | Select dropdown option |\n| `user.tab()` | Tab to next focusable element |\n| `user.keyboard('{Enter}')` | Press a key |\n| `user.hover(el)` \u002F `user.unhover(el)` | Mouse hover |\n| `user.upload(el, file)` | File upload |\n\nPattern:\n```js\nconst user = userEvent.setup();\nrender(\u003CComponent \u002F>);\nawait user.click(screen.getByRole('button', { name: \u002Fsave\u002Fi }));\n```\n\n---\n\n## Async Testing\n\n### `findBy` — element appears after async work\n\n```js\nrender(\u003CBlogList \u002F>);\nexpect(await screen.findByText('Blog Title')).toBeInTheDocument();\n```\n\n### `waitFor` — multiple assertions, complex conditions\n\n```js\nawait waitFor(() => {\n  expect(screen.getAllByRole('listitem')).toHaveLength(3);\n});\n```\n\n### `waitForElementToBeRemoved` — element disappears\n\n```js\nrender(\u003CBlogList \u002F>);\nawait waitForElementToBeRemoved(() => screen.queryByText('Loading...'));\n```\n\n### Rules\n\n- **Never** use `setTimeout` or fixed delays\n- **Never** use `act()` directly unless testing hooks outside components — RTL wraps it\n- `findBy` is preferred over `waitFor` + `getBy` for single-element waits\n- `waitFor` retries until the callback passes or times out (default 1000ms)\n\n---\n\n## Component Testing Patterns\n\n### Basic render + interaction\n\n```\n1. Arrange — render the component with props\u002Fproviders\n2. Act — simulate user interaction via userEvent\n3. Assert — check what the user would see\n```\n\nCombine all three into a single test when they form one user flow. Don't split Arrange\u002FAct\u002FAssert into separate `it()` blocks.\n\n### Render helper\n\nCreate a local `renderComponent` function when the component needs providers:\n\n```js\nconst renderComponent = (props = {}) =>\n  render(\n    \u003CMemoryRouter>\n      \u003CMyComponent defaultProp=\"value\" {...props} \u002F>\n    \u003C\u002FMemoryRouter>\n  );\n```\n\n### Asserting absence\n\n```js\n\u002F\u002F queryBy returns null — safe with .not\nexpect(screen.queryByText('Error')).not.toBeInTheDocument();\n```\n\n### Scoping queries with `within`\n\n```js\nconst card = screen.getByRole('article');\nexpect(within(card).getByText('Title')).toBeInTheDocument();\n```\n\n---\n\n## Hook Testing\n\nUse `renderHook` for hooks with **complex pure logic** only. If a hook just fetches data or manages simple state, test it through the component that uses it instead.\n\n```js\nimport { renderHook, act } from '@testing-library\u002Freact';\n\nconst { result } = renderHook(() => useCounter());\nact(() => result.current.increment());\nexpect(result.current.count).toBe(1);\n```\n\nFor hooks needing providers, pass a `wrapper`:\n\n```js\nrenderHook(() => useAuth(), {\n  wrapper: ({ children }) => \u003CAuthProvider>{children}\u003C\u002FAuthProvider>,\n});\n```\n\n---\n\n## React Router Wrapping\n\nComponents using `\u003CLink>`, `useNavigate`, `useParams`, or `useLocation` must be wrapped:\n\n```js\n\u002F\u002F Simple\nrender(\u003CMemoryRouter>\u003CMyComponent \u002F>\u003C\u002FMemoryRouter>);\n\n\u002F\u002F With route params\nrender(\n  \u003CMemoryRouter initialEntries={['\u002Fblogs\u002F123']}>\n    \u003CRoutes>\n      \u003CRoute path=\"\u002Fblogs\u002F:id\" element={\u003CBlogDetail \u002F>} \u002F>\n    \u003C\u002FRoutes>\n  \u003C\u002FMemoryRouter>\n);\n```\n\n---\n\n## Mocking Strategies\n\n### MSW (Mock Service Worker) — preferred for all data-fetching components\n\nIntercepts at the network layer. Tests don't couple to HTTP client internals. Most realistic approach.\n\n```js\nimport { setupServer } from 'msw\u002Fnode';\nimport { http, HttpResponse } from 'msw';\n\nconst server = setupServer(\n  \u002F\u002F Default happy-path handlers\n  http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json({ success: true, blogs: [...] })),\n  http.post('\u002Fapi\u002Fblogs', async ({ request }) => {\n    const body = await request.json();\n    return HttpResponse.json({ success: true, blog: { _id: '1', ...body } }, { status: 201 });\n  }),\n);\n\nbeforeAll(() => server.listen());\nafterEach(() => server.resetHandlers());\nafterAll(() => server.close());\n\n\u002F\u002F Override for specific tests:\nit('handles error', async () => {\n  server.use(\n    http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json({ success: false }, { status: 500 })),\n  );\n  \u002F\u002F ...\n});\n```\n\n### Module mock (`vi.mock`) — fallback when MSW is overkill\n\n```js\nvi.mock('..\u002F..\u002Fapi\u002FblogApi', () => ({\n  getBlogs: vi.fn(),\n}));\n```\n\n- Mock at the API\u002Fhook level, not at Axios\u002Ffetch level\n- Reset in `beforeEach`: `vi.clearAllMocks()`\n- Use `vi.mocked(fn)` for type-safe access to mock methods\n\n### Context mocking\n\nWrap component in a test provider with controlled values. Don't mock context internals — render with the real provider.\n\n### Timers\n\n```js\nvi.useFakeTimers();\n\u002F\u002F ... render and trigger timer-dependent code\nvi.advanceTimersByTime(3000);\nvi.useRealTimers(); \u002F\u002F restore in afterEach\n```\n\n---\n\n## What to Test \u002F What to Skip\n\n**Test (as user-visible flows):**\n- User journeys: form fill → submit → feedback\n- Data display: loading → loaded → interaction\n- State transitions: empty → filled, logged out → logged in\n- Error boundaries: API failure → error message\n- Conditional UI: different user roles see different things\n\n**Skip:**\n- Internal state (`useState` values)\n- Implementation details (hook calls, private functions)\n- CSS classes or inline styles\n- Third-party library internals\n- Render counts or performance\n- Snapshot tests (unless explicitly requested)\n- Constants or static data\n- Individual assertions that belong inside a longer flow test\n\n---\n\n## jest-dom Matchers Reference\n\n| Matcher | Checks |\n|---------|--------|\n| `toBeInTheDocument()` | Element is in the DOM |\n| `toBeVisible()` | Element is visible to the user |\n| `toBeEnabled()` \u002F `toBeDisabled()` | Enabled\u002Fdisabled state |\n| `toHaveTextContent(\u002Ftext\u002Fi)` | Contains text |\n| `toHaveValue('val')` | Input\u002Fselect current value |\n| `toHaveAttribute('href', '\u002Fpath')` | HTML attribute |\n| `toBeChecked()` | Checkbox\u002Fradio is checked |\n| `toHaveFocus()` | Element has focus |\n| `toBeRequired()` | Input is required |\n| `toHaveClass('cls')` | Has CSS class (use sparingly) |\n| `toHaveAccessibleDescription()` | `aria-describedby` text |\n| `toBeEmptyDOMElement()` | No visible content |\n\n---\n\n## Test File Conventions\n\n- Place tests next to source: `BlogCard.jsx` -> `BlogCard.test.jsx`\n- Use `.test.jsx` extension (not `.spec.jsx`)\n- One `describe` per component\u002Fhook\n- Test names describe user-visible behavior: `\"user fills form and sees success message\"`\n- Use `vi.fn()` for all mock functions\n- Call `userEvent.setup()` before `render()`\n- Always use `screen` — never destructure from `render()`\n- **1-3 tests per component** (user flows), 1-2 per hook, 2-3 per utility\n\n---\n\n## Anti-Patterns\n\n| Anti-Pattern | Fix |\n|-------------|-----|\n| Many tiny tests with one assertion each | Combine into fewer flow tests that walk through a user journey |\n| `fireEvent.click()` | Use `await user.click()` from `userEvent.setup()` |\n| Destructuring from `render()` | Use `screen.getByRole(...)` |\n| `getByTestId` as first choice | Try `getByRole`, `getByLabelText`, `getByText` first |\n| Testing `useState` \u002F hook internals | Test the rendered output instead |\n| `setTimeout` \u002F fixed delays | Use `findBy` or `waitFor` |\n| Snapshot tests replacing behavior tests | Write explicit assertions |\n| `container.querySelector()` | Use RTL queries |\n| Shared mutable state between tests | Reset in `beforeEach` |\n| Importing from `jest` | Import from `vitest` (`vi.fn()`, `vi.mock()`) |\n| Mocking what you're testing | Mock dependencies, not the subject |\n| `act()` wrapping RTL calls | RTL handles `act()` internally |\n| Mocking Axios\u002Ffetch directly | Use MSW for network-level mocking |\n| Testing every prop combination | Test the meaningful user-facing differences only |\n","# React Testing Library\n\nGeneral-purpose guide for testing React components and hooks with React Testing Library (RTL) and Vitest. Project-agnostic — works with any Vite + React setup.\n\n## Philosophy: Fewer Tests, Real Scenarios\n\n> \"Write tests. Not too many. Mostly integration.\" — Kent C. Dodds\n\n1. **Use-case coverage > code coverage** — aim for 100% use-case coverage, not 100% line coverage. Think about what the user can DO, not what the code does internally.\n2. **Write fewer, longer tests** — one test that walks through a full user flow beats six isolated assertions. Combine related steps (render → interact → verify) into a single test.\n3. **Test behavior, not implementation** — assert on what the user sees and can do. Never assert on internal state, hook calls, or DOM structure.\n4. **Mock at boundaries only** — mock API calls and external services. Never mock your own components, hooks, or context internals.\n5. **Each test must justify its existence** — if removing a test wouldn't reduce your confidence that the app works, delete it.\n\n### The Testing Trophy (what to invest in)\n\n```\n    E2E        ← Few: critical user journeys only (Playwright\u002FCypress)\n  Integration  ← MOST tests: components with real providers, MSW for APIs\n  Unit         ← Some: complex pure logic, utilities, formatters\nStatic Analysis ← Always: TypeScript, ESLint\n```\n\n---\n\n## Setup from Scratch\n\n### 1. Install Dependencies\n\n```bash\nnpm install -D vitest @testing-library\u002Freact @testing-library\u002Fjest-dom @testing-library\u002Fuser-event jsdom\n```\n\nOptional but recommended:\n```bash\nnpm install -D msw                     # Network-level API mocking\nnpm install -D @vitest\u002Fcoverage-v8     # Code coverage\n```\n\n### 2. Vitest Config\n\nCreate `vitest.config.js` at the client root (or extend `vite.config.js`):\n\n```js\nimport { defineConfig, mergeConfig } from 'vitest\u002Fconfig';\nimport viteConfig from '.\u002Fvite.config.js';\n\nexport default mergeConfig(viteConfig, defineConfig({\n  test: {\n    globals: true,\n    environment: 'jsdom',\n    setupFiles: ['.\u002Fsrc\u002Ftest\u002Fsetup.js'],\n    css: true,\n    include: ['src\u002F**\u002F*.test.{js,jsx,ts,tsx}'],\n  },\n}));\n```\n\n### 3. Setup File\n\nCreate `src\u002Ftest\u002Fsetup.js`:\n\n```js\nimport '@testing-library\u002Fjest-dom\u002Fvitest';\n```\n\nThis registers matchers like `toBeInTheDocument()`, `toBeVisible()`, `toHaveTextContent()`.\n\n### 4. Package Scripts\n\nAdd to `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"vitest run\",\n    \"test:watch\": \"vitest\",\n    \"test:coverage\": \"vitest run --coverage\"\n  }\n}\n```\n\n---\n\n## Test Scenarios by Component Type\n\nBefore writing tests, identify the component type and pick scenarios from this matrix. Write **1-3 tests per component** — each test covers a full user flow, not a single assertion.\n\n### Form Component (e.g., BlogEditor, LoginForm, CommentForm)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Happy path: fill all fields → submit → success feedback** | Rendering, typing, validation passing, API call, success state |\n| 2 | **Validation: submit empty\u002Finvalid → error messages appear** | Required fields, validation rules, error rendering |\n| 3 | **API failure: fill valid → submit → server error shown** | Error handling, error UI, form stays filled |\n\n### List\u002FTable Component (e.g., BlogList, CommentList, Dashboard)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Happy path: data loads → items render → user interacts** | Loading state, data rendering, click\u002Fnavigation |\n| 2 | **Empty state: no data → empty message shown** | Zero-data handling |\n| 3 | **Error state: API fails → error message shown** | Network failure handling |\n\n### Detail\u002FView Component (e.g., BlogDetail, UserProfile)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Happy path: data loads → full content renders → user actions work** | Data fetching, rendering, interactions (edit\u002Fdelete\u002Fcomment) |\n| 2 | **Not found \u002F error: invalid ID → appropriate message** | 404 handling, error boundaries |\n\n### Auth-Gated Component (e.g., AdminPanel, ProtectedRoute)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Authenticated: user sees protected content and can interact** | Auth context, content rendering, user actions |\n| 2 | **Unauthenticated: redirects or shows login prompt** | Guard behavior, redirect |\n\n### Shared\u002FPresentational Component (e.g., BlogCard, Button, Modal)\n\n| # | Test | What it covers |\n|---|------|----------------|\n| 1 | **Renders with props and handles user interaction** | Props → UI mapping, click\u002Fhover callbacks |\n| 2 | **Conditional rendering: different props → different output** | Only if the component has meaningful branching |\n\n---\n\n## Complete Spec Template\n\nThis is what a well-structured test file looks like. Each test walks through a real user flow.\n\n```jsx\n\u002F\u002F BlogList.test.jsx\nimport { describe, it, expect, vi, beforeEach } from 'vitest';\nimport { render, screen, within } from '@testing-library\u002Freact';\nimport userEvent from '@testing-library\u002Fuser-event';\nimport { MemoryRouter } from 'react-router';\nimport { http, HttpResponse } from 'msw';\nimport { setupServer } from 'msw\u002Fnode';\nimport BlogList from '.\u002FBlogList';\n\n\u002F\u002F --- MSW setup: mock the API at the network level ---\nconst blogs = [\n  { _id: '1', title: 'First Post', category: 'Technology', excerpt: 'About tech' },\n  { _id: '2', title: 'Second Post', category: 'Startup', excerpt: 'About startups' },\n];\n\nconst server = setupServer(\n  http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json({ success: true, blogs })),\n);\n\nbeforeAll(() => server.listen());\nafterEach(() => server.resetHandlers());\nafterAll(() => server.close());\n\n\u002F\u002F --- Render helper (keeps tests DRY) ---\nconst renderBlogList = () =>\n  render(\u003CMemoryRouter>\u003CBlogList \u002F>\u003C\u002FMemoryRouter>);\n\n\u002F\u002F --- Tests: 3 tests covering ALL real scenarios ---\ndescribe('BlogList', () => {\n  it('loads blogs and lets user navigate to a post', async () => {\n    const user = userEvent.setup();\n    renderBlogList();\n\n    \u002F\u002F Loading state appears first\n    expect(screen.getByText(\u002Floading\u002Fi)).toBeInTheDocument();\n\n    \u002F\u002F Blogs appear after fetch\n    expect(await screen.findByText('First Post')).toBeInTheDocument();\n    expect(screen.getByText('Second Post')).toBeInTheDocument();\n\n    \u002F\u002F User clicks a blog card\n    await user.click(screen.getByRole('link', { name: \u002Ffirst post\u002Fi }));\n    \u002F\u002F Assert navigation happened (or verify detail view renders)\n  });\n\n  it('shows empty state when no blogs exist', async () => {\n    server.use(\n      http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json({ success: true, blogs: [] })),\n    );\n    renderBlogList();\n\n    expect(await screen.findByText(\u002Fno blogs\u002Fi)).toBeInTheDocument();\n    expect(screen.queryByRole('article')).not.toBeInTheDocument();\n  });\n\n  it('shows error message when API fails', async () => {\n    server.use(\n      http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json(\n        { success: false, message: 'Server error' },\n        { status: 500 },\n      )),\n    );\n    renderBlogList();\n\n    expect(await screen.findByRole('alert')).toBeInTheDocument();\n    expect(screen.queryByRole('article')).not.toBeInTheDocument();\n  });\n});\n```\n\n### Form Spec Template\n\n```jsx\n\u002F\u002F LoginForm.test.jsx\ndescribe('LoginForm', () => {\n  it('logs in with valid credentials and shows dashboard', async () => {\n    const user = userEvent.setup();\n    render(\u003CMemoryRouter>\u003CLoginForm \u002F>\u003C\u002FMemoryRouter>);\n\n    \u002F\u002F Fill form\n    await user.type(screen.getByLabelText(\u002Femail\u002Fi), 'admin@test.com');\n    await user.type(screen.getByLabelText(\u002Fpassword\u002Fi), 'password123');\n    await user.click(screen.getByRole('button', { name: \u002Fsign in\u002Fi }));\n\n    \u002F\u002F Success: redirected or success message\n    expect(await screen.findByText(\u002Fwelcome\u002Fi)).toBeInTheDocument();\n  });\n\n  it('shows validation errors when submitted empty', async () => {\n    const user = userEvent.setup();\n    render(\u003CMemoryRouter>\u003CLoginForm \u002F>\u003C\u002FMemoryRouter>);\n\n    await user.click(screen.getByRole('button', { name: \u002Fsign in\u002Fi }));\n\n    \u002F\u002F Both fields show errors\n    expect(await screen.findByText(\u002Femail is required\u002Fi)).toBeInTheDocument();\n    expect(screen.getByText(\u002Fpassword is required\u002Fi)).toBeInTheDocument();\n\n    \u002F\u002F Form is still visible (not redirected)\n    expect(screen.getByRole('button', { name: \u002Fsign in\u002Fi })).toBeInTheDocument();\n  });\n\n  it('shows server error when API returns 401', async () => {\n    server.use(\n      http.post('\u002Fapi\u002Fadmin\u002Flogin', () =>\n        HttpResponse.json({ success: false, message: 'Invalid credentials' }, { status: 401 }),\n      ),\n    );\n    const user = userEvent.setup();\n    render(\u003CMemoryRouter>\u003CLoginForm \u002F>\u003C\u002FMemoryRouter>);\n\n    await user.type(screen.getByLabelText(\u002Femail\u002Fi), 'admin@test.com');\n    await user.type(screen.getByLabelText(\u002Fpassword\u002Fi), 'wrongpassword');\n    await user.click(screen.getByRole('button', { name: \u002Fsign in\u002Fi }));\n\n    expect(await screen.findByText(\u002Finvalid credentials\u002Fi)).toBeInTheDocument();\n  });\n});\n```\n\n---\n\n## Import Rules\n\n```js\n\u002F\u002F Test runner — ALWAYS from vitest\nimport { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';\n\n\u002F\u002F RTL — render, screen, waitFor\nimport { render, screen, waitFor, within } from '@testing-library\u002Freact';\n\n\u002F\u002F User interaction — ALWAYS userEvent, NEVER fireEvent\nimport userEvent from '@testing-library\u002Fuser-event';\n\n\u002F\u002F Hook testing\nimport { renderHook, act } from '@testing-library\u002Freact';\n```\n\nNEVER import from `jest`. Use `vi.fn()`, `vi.spyOn()`, `vi.mock()`.\n\n---\n\n## Query Priority\n\nQueries are ordered by how closely they reflect user experience.\n\n### Tier 1 — Accessible (default choice)\n\n| Query | Use For |\n|-------|---------|\n| `getByRole` | Buttons, links, headings, inputs, checkboxes, comboboxes — **always try first** |\n| `getByLabelText` | Form fields with a `\u003Clabel>` |\n| `getByPlaceholderText` | Inputs without a label (prefer adding a label instead) |\n| `getByText` | Static text content — paragraphs, spans, error messages |\n| `getByDisplayValue` | Input with a current value |\n\n### Tier 2 — Semantic\n\n| Query | Use For |\n|-------|---------|\n| `getByAltText` | Images |\n| `getByTitle` | Elements with `title` attribute |\n\n### Tier 3 — Last resort\n\n| Query | Use For |\n|-------|---------|\n| `getByTestId` | Only when no accessible query works; requires `data-testid` |\n\n### Query Variants\n\n| Variant | Returns | Use When |\n|---------|---------|----------|\n| `getBy` | Element or throws | Element **must** be present |\n| `queryBy` | Element or `null` | Asserting element does **not** exist |\n| `findBy` | Promise\\\u003CElement\\> | Element appears **after** an async operation |\n| `*AllBy` | Array variants | Multiple matching elements |\n\n### Role Query Patterns\n\n```\ngetByRole('button', { name: \u002Fsubmit\u002Fi })\ngetByRole('heading', { level: 2 })\ngetByRole('textbox', { name: \u002Femail\u002Fi })\ngetByRole('link', { name: \u002Fread more\u002Fi })\ngetByRole('checkbox', { name: \u002Fagree\u002Fi })\ngetByRole('combobox')              \u002F\u002F \u003Cselect>\ngetByRole('status')                \u002F\u002F role=\"status\"\ngetByRole('alert')                 \u002F\u002F role=\"alert\"\ngetByRole('dialog')                \u002F\u002F \u003Cdialog> or role=\"dialog\"\ngetByRole('navigation')            \u002F\u002F \u003Cnav>\n```\n\n---\n\n## userEvent\n\nAlways call `userEvent.setup()` before rendering. All methods are async.\n\n| Method | Purpose |\n|--------|---------|\n| `user.click(el)` | Click |\n| `user.dblClick(el)` | Double-click |\n| `user.type(el, 'text')` | Type text (appends to existing value) |\n| `user.clear(el)` | Clear input value |\n| `user.selectOptions(el, 'value')` | Select dropdown option |\n| `user.tab()` | Tab to next focusable element |\n| `user.keyboard('{Enter}')` | Press a key |\n| `user.hover(el)` \u002F `user.unhover(el)` | Mouse hover |\n| `user.upload(el, file)` | File upload |\n\nPattern:\n```js\nconst user = userEvent.setup();\nrender(\u003CComponent \u002F>);\nawait user.click(screen.getByRole('button', { name: \u002Fsave\u002Fi }));\n```\n\n---\n\n## Async Testing\n\n### `findBy` — element appears after async work\n\n```js\nrender(\u003CBlogList \u002F>);\nexpect(await screen.findByText('Blog Title')).toBeInTheDocument();\n```\n\n### `waitFor` — multiple assertions, complex conditions\n\n```js\nawait waitFor(() => {\n  expect(screen.getAllByRole('listitem')).toHaveLength(3);\n});\n```\n\n### `waitForElementToBeRemoved` — element disappears\n\n```js\nrender(\u003CBlogList \u002F>);\nawait waitForElementToBeRemoved(() => screen.queryByText('Loading...'));\n```\n\n### Rules\n\n- **Never** use `setTimeout` or fixed delays\n- **Never** use `act()` directly unless testing hooks outside components — RTL wraps it\n- `findBy` is preferred over `waitFor` + `getBy` for single-element waits\n- `waitFor` retries until the callback passes or times out (default 1000ms)\n\n---\n\n## Component Testing Patterns\n\n### Basic render + interaction\n\n```\n1. Arrange — render the component with props\u002Fproviders\n2. Act — simulate user interaction via userEvent\n3. Assert — check what the user would see\n```\n\nCombine all three into a single test when they form one user flow. Don't split Arrange\u002FAct\u002FAssert into separate `it()` blocks.\n\n### Render helper\n\nCreate a local `renderComponent` function when the component needs providers:\n\n```js\nconst renderComponent = (props = {}) =>\n  render(\n    \u003CMemoryRouter>\n      \u003CMyComponent defaultProp=\"value\" {...props} \u002F>\n    \u003C\u002FMemoryRouter>\n  );\n```\n\n### Asserting absence\n\n```js\n\u002F\u002F queryBy returns null — safe with .not\nexpect(screen.queryByText('Error')).not.toBeInTheDocument();\n```\n\n### Scoping queries with `within`\n\n```js\nconst card = screen.getByRole('article');\nexpect(within(card).getByText('Title')).toBeInTheDocument();\n```\n\n---\n\n## Hook Testing\n\nUse `renderHook` for hooks with **complex pure logic** only. If a hook just fetches data or manages simple state, test it through the component that uses it instead.\n\n```js\nimport { renderHook, act } from '@testing-library\u002Freact';\n\nconst { result } = renderHook(() => useCounter());\nact(() => result.current.increment());\nexpect(result.current.count).toBe(1);\n```\n\nFor hooks needing providers, pass a `wrapper`:\n\n```js\nrenderHook(() => useAuth(), {\n  wrapper: ({ children }) => \u003CAuthProvider>{children}\u003C\u002FAuthProvider>,\n});\n```\n\n---\n\n## React Router Wrapping\n\nComponents using `\u003CLink>`, `useNavigate`, `useParams`, or `useLocation` must be wrapped:\n\n```js\n\u002F\u002F Simple\nrender(\u003CMemoryRouter>\u003CMyComponent \u002F>\u003C\u002FMemoryRouter>);\n\n\u002F\u002F With route params\nrender(\n  \u003CMemoryRouter initialEntries={['\u002Fblogs\u002F123']}>\n    \u003CRoutes>\n      \u003CRoute path=\"\u002Fblogs\u002F:id\" element={\u003CBlogDetail \u002F>} \u002F>\n    \u003C\u002FRoutes>\n  \u003C\u002FMemoryRouter>\n);\n```\n\n---\n\n## Mocking Strategies\n\n### MSW (Mock Service Worker) — preferred for all data-fetching components\n\nIntercepts at the network layer. Tests don't couple to HTTP client internals. Most realistic approach.\n\n```js\nimport { setupServer } from 'msw\u002Fnode';\nimport { http, HttpResponse } from 'msw';\n\nconst server = setupServer(\n  \u002F\u002F Default happy-path handlers\n  http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json({ success: true, blogs: [...] })),\n  http.post('\u002Fapi\u002Fblogs', async ({ request }) => {\n    const body = await request.json();\n    return HttpResponse.json({ success: true, blog: { _id: '1', ...body } }, { status: 201 });\n  }),\n);\n\nbeforeAll(() => server.listen());\nafterEach(() => server.resetHandlers());\nafterAll(() => server.close());\n\n\u002F\u002F Override for specific tests:\nit('handles error', async () => {\n  server.use(\n    http.get('\u002Fapi\u002Fblogs', () => HttpResponse.json({ success: false }, { status: 500 })),\n  );\n  \u002F\u002F ...\n});\n```\n\n### Module mock (`vi.mock`) — fallback when MSW is overkill\n\n```js\nvi.mock('..\u002F..\u002Fapi\u002FblogApi', () => ({\n  getBlogs: vi.fn(),\n}));\n```\n\n- Mock at the API\u002Fhook level, not at Axios\u002Ffetch level\n- Reset in `beforeEach`: `vi.clearAllMocks()`\n- Use `vi.mocked(fn)` for type-safe access to mock methods\n\n### Context mocking\n\nWrap component in a test provider with controlled values. Don't mock context internals — render with the real provider.\n\n### Timers\n\n```js\nvi.useFakeTimers();\n\u002F\u002F ... render and trigger timer-dependent code\nvi.advanceTimersByTime(3000);\nvi.useRealTimers(); \u002F\u002F restore in afterEach\n```\n\n---\n\n## What to Test \u002F What to Skip\n\n**Test (as user-visible flows):**\n- User journeys: form fill → submit → feedback\n- Data display: loading → loaded → interaction\n- State transitions: empty → filled, logged out → logged in\n- Error boundaries: API failure → error message\n- Conditional UI: different user roles see different things\n\n**Skip:**\n- Internal state (`useState` values)\n- Implementation details (hook calls, private functions)\n- CSS classes or inline styles\n- Third-party library internals\n- Render counts or performance\n- Snapshot tests (unless explicitly requested)\n- Constants or static data\n- Individual assertions that belong inside a longer flow test\n\n---\n\n## jest-dom Matchers Reference\n\n| Matcher | Checks |\n|---------|--------|\n| `toBeInTheDocument()` | Element is in the DOM |\n| `toBeVisible()` | Element is visible to the user |\n| `toBeEnabled()` \u002F `toBeDisabled()` | Enabled\u002Fdisabled state |\n| `toHaveTextContent(\u002Ftext\u002Fi)` | Contains text |\n| `toHaveValue('val')` | Input\u002Fselect current value |\n| `toHaveAttribute('href', '\u002Fpath')` | HTML attribute |\n| `toBeChecked()` | Checkbox\u002Fradio is checked |\n| `toHaveFocus()` | Element has focus |\n| `toBeRequired()` | Input is required |\n| `toHaveClass('cls')` | Has CSS class (use sparingly) |\n| `toHaveAccessibleDescription()` | `aria-describedby` text |\n| `toBeEmptyDOMElement()` | No visible content |\n\n---\n\n## Test File Conventions\n\n- Place tests next to source: `BlogCard.jsx` -> `BlogCard.test.jsx`\n- Use `.test.jsx` extension (not `.spec.jsx`)\n- One `describe` per component\u002Fhook\n- Test names describe user-visible behavior: `\"user fills form and sees success message\"`\n- Use `vi.fn()` for all mock functions\n- Call `userEvent.setup()` before `render()`\n- Always use `screen` — never destructure from `render()`\n- **1-3 tests per component** (user flows), 1-2 per hook, 2-3 per utility\n\n---\n\n## Anti-Patterns\n\n| Anti-Pattern | Fix |\n|-------------|-----|\n| Many tiny tests with one assertion each | Combine into fewer flow tests that walk through a user journey |\n| `fireEvent.click()` | Use `await user.click()` from `userEvent.setup()` |\n| Destructuring from `render()` | Use `screen.getByRole(...)` |\n| `getByTestId` as first choice | Try `getByRole`, `getByLabelText`, `getByText` first |\n| Testing `useState` \u002F hook internals | Test the rendered output instead |\n| `setTimeout` \u002F fixed delays | Use `findBy` or `waitFor` |\n| Snapshot tests replacing behavior tests | Write explicit assertions |\n| `container.querySelector()` | Use RTL queries |\n| Shared mutable state between tests | Reset in `beforeEach` |\n| Importing from `jest` | Import from `vitest` (`vi.fn()`, `vi.mock()`) |\n| Mocking what you're testing | Mock dependencies, not the subject |\n| `act()` wrapping RTL calls | RTL handles `act()` internally |\n| Mocking Axios\u002Ffetch directly | Use MSW for network-level mocking |\n| Testing every prop combination | Test the meaningful user-facing differences only |\n",{"name":5,"description":7},"main","3bcf689e2951ea8cef76e93d0e9a96a8443cec13","plugins\u002Fengineering-paved-path\u002Fskills\u002Freact-testing-library","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva","2026-10-27 00:55:00",{"source":8,"skillName":5,"commands":30,"prompt":40,"zipAvailable":41},[31,34,37],{"tool":32,"command":33},"npx","npx skills add marynabieliaieva\u002Fdev-ai-harness-marketplace --skill react-testing-library",{"tool":35,"command":36},"bunx","bunx skills add marynabieliaieva\u002Fdev-ai-harness-marketplace --skill react-testing-library",{"tool":38,"command":39},"pnpm","pnpm dlx skills add marynabieliaieva\u002Fdev-ai-harness-marketplace --skill react-testing-library","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fengineering-paved-path\u002Fskills\u002Freact-testing-library\u002FSKILL.md",true,[43],{"path":44,"resourceType":45,"resourceTypeDesc":46,"sizeBytes":47,"sourceHtmlUrl":48},"README.md","REFERENCE","参考文档",3786,"https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fengineering-paved-path\u002Fskills\u002Freact-testing-library\u002FREADME.md",[50,57,64,71,78,85],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":18},"01M7FBX6FAH2MGVNNE4RGG2RPF","workflow-retro","Retrospective of a finished multi-agent workflow run (e.g. \u002Fsdd-engineering:run-plan, a code review, spec → plan → execution) — collects run facts (agents spawned, spawn order and waves, tokens per agent and per type, fix rounds, caps hit, human interventions), extracts insights per agent type (what was hard, what was easy, what information was duplicated, what each gate missed and who caught it later) and turns them into concrete, evidence-backed proposals for agent\u002Fskill\u002Fplan changes. Writes a ledger entry to docs\u002Fretro\u002Fledger\u002F and a summary in chat. Data source is the current conversation by default; --deep also parses the session transcripts on disk. Invoked only by the user as \u002Fsdd-engineering:workflow-retro — never automatically, never by another skill or agent.","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fsdd-engineering\u002Fskills\u002Fworkflow-retro\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":18},"01M7FBX11WK2ZEC50W955GVJ87","run-plan","Runs the Spec Driven Development execution workflow for an already-written Implementation Plan (docs\u002Fplans\u002F\u003Cslug>.md) — implementer tasks wave by wave along the plan's DAG, one plan-verifier pass with a fix loop, an architecture-review loop (review → fix → re-review until clean or the round cap), then one full test run. Accepts the plan, optionally the spec, extra requirements text and design files. Does NOT run spec-creator or implementation-planner (those are run manually first). Invoked only by the user as \u002Fsdd-engineering:run-plan.","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fsdd-engineering\u002Fskills\u002Frun-plan\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":18},"01M7FBWWYCS5F001B95Z8YXX3Q","engineering-insights","Captures a non-obvious engineering insight (a working pattern, an antipattern\u002Fdead end, a decision with its reason, or a recurring error and fix) found while working in this repo, and files it into the INSIGHTS.md of the package the session touched. Use at the end of a session that learned something substantial, or immediately when something surprising comes up — skip when nothing non-obvious happened.","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fsdd-engineering\u002Fskills\u002Fengineering-insights\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":18},"01M7FBWSMXJGXS3KSHKSVCZR8V","flaky-patterns","Reference catalogue of flaky-test causes — for each class, how it shows up in a stack trace, the real fix, the masking fixes to reject, and how to reproduce it deterministically without running the test many times. Use when diagnosing or reviewing a fix for a test that passes and fails on the same code.","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fflaky-fix\u002Fskills\u002Fflaky-patterns\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":18},"01M7FBWKCDZNTQE9AW5PYA47KS","flaky-fix","Triage and fix one flaky test without extra pipeline or test runs — from the test name, a stack trace, the date it became flaky and its failure rate to a Jira issue, a fix branch, a reviewed commit and a PR, with verification left to the normal runs of main after merge. Invoked only by the user as \u002Fflaky-fix:flaky-fix.","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fflaky-fix\u002Fskills\u002Fflaky-fix\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":89,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":18},"01M7FBWDF214X5KZ4YKD2XDJD8","zod","Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover form-library integration (e.g. React Hook Form resolvers) or OpenAPI client generation.","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fengineering-paved-path\u002Fskills\u002Fzod\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fmarynabieliaieva\u002Fdev-ai-harness-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fengineering-paved-path\u002Fskills\u002Fzod\u002FSKILL.md",[],[]]