@macpaw/cctk 1.0.0-beta.1

package/templates/claude/skills/vitest/SKILL.md

@@ -0,0 +1,595 @@
+---
+name: vitest
+description: >
+  Write high-quality Vitest tests for Next.js applications and shared monorepo packages
+  (hooks, utilities, components). Use this skill whenever the user asks to write, fix,
+  generate, or improve tests using Vitest — including unit tests, component tests, hook
+  tests, mocking strategies, test setup, and coverage. Trigger for any request involving
+  "test", "spec", "vitest", "testing-library", or "mock" in a TypeScript/React/Next.js context.
+  Also trigger when the user shares a source file and asks "write tests for this" or
+  "how do I test this".
+license: MIT  
+version: 1.0.0  
+---
+
+# Vitest Testing Skill
+
+A guide for writing production-quality Vitest tests in Next.js monorepos with shared
+packages (components, hooks, utilities).
+
+---
+
+## Detect the Repo Context First
+
+**Before giving any setup advice or config examples, check which environment you're in.** The right configuration differs significantly across setups.
+
+### Step 1 — Identify the repo type
+
+Look for these signals (check files the user shares, or ask them to run `ls` at the root):
+
+| Signal | Conclusion |
+|---|---|
+| `turbo.json` present at root | **Turborepo monorepo** → follow [Turborepo section](#turborepo-monorepo) |
+| `pnpm-workspace.yaml` or `lerna.json` or `nx.json` but no `turbo.json` | **Other monorepo** → follow [Generic Monorepo section](#generic-monorepo) |
+| Single `package.json` at root, no workspace config | **Standalone project** → follow [Standalone section](#standalone-project) |
+
+If unsure, ask: *"Does your project have a `turbo.json` at the root? Or is it a single-package project?"*
+
+### Step 2 — Jump to the right config section
+
+- Turborepo → [Turborepo Monorepo](#turborepo-monorepo)
+- Other monorepo → [Generic Monorepo](#generic-monorepo)  
+- Single project → [Standalone Project](#standalone-project)
+
+---
+
+## Stack Assumptions
+
+Unless told otherwise, assume:
+- **Vitest** as the test runner
+- **@testing-library/react** + **@testing-library/user-event** for component/hook tests
+- **@testing-library/jest-dom** for DOM matchers (`toBeInTheDocument`, etc.)
+- **MSW v2** for API mocking (when network calls are involved)
+- **TypeScript** throughout
+
+If the user's stack differs from any of the above, adapt accordingly.
+
+---
+
+## Quick Decision Tree
+
+Before writing any test, identify what you're testing:
+
+| Subject | Strategy | Reference |
+|---|---|---|
+| Pure function / utility | Unit test, no rendering | [→ Utilities](#utilities) |
+| Custom React hook | `renderHook` from testing-library | [→ Hooks](#hooks) |
+| React component (presentational) | `render` + assertions | [→ Components](#components) |
+| React component (with data fetching) | MSW + `render` | [→ Async Components](#async-components) |
+| Next.js page / route handler | Per-file mocking of `next/*` | [→ Next.js Specifics](#nextjs-specifics) |
+| Context / Provider | Wrap with provider in `render` | [→ Components](#components) |
+
+---
+
+## Standalone Project
+
+A single `package.json`, no workspaces. Simple and self-contained.
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+import tsconfigPaths from 'vite-tsconfig-paths'
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./src/test/setup.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov'],
+    },
+  },
+})
+```
+
+```ts
+// src/test/setup.ts
+import '@testing-library/jest-dom'
+import { afterEach } from 'vitest'
+import { cleanup } from '@testing-library/react'
+
+afterEach(() => cleanup())
+```
+
+Run: `vitest` / `vitest run --coverage`
+
+---
+
+## Generic Monorepo
+
+A monorepo without Turborepo (Lerna, Nx, bare pnpm workspaces, etc.). Each package has its own `vitest.config.ts`; a root `vitest.workspace.ts` ties them together.
+
+```ts
+// vitest.workspace.ts (root)
+import { defineWorkspace } from 'vitest/config'
+
+export default defineWorkspace([
+  'packages/*/vitest.config.ts',
+  'apps/*/vitest.config.ts',
+])
+```
+
+Per-package config and shared `test-utils` setup: see [`references/monorepo-setup.md`](./references/monorepo-setup.md).
+
+Run all: `vitest --workspace` | Single package: `vitest --project ui`
+
+---
+
+## Turborepo Monorepo
+
+> **Use this section when `turbo.json` is present at the root.**
+
+For the complete Turborepo setup guide, read [`references/turborepo-setup.md`](./references/turborepo-setup.md).
+
+**Key differences from a generic monorepo:**
+
+- Tests are run **per-package** via `turbo run test` — Turborepo caches results and only re-runs packages affected by changes
+- Each package must declare a `"test"` script in its `package.json`
+- A root `vitest.workspace.ts` is **optional** — Turborepo orchestrates runs itself, so you may not need it
+- `turbo.json` must declare `test` as a task with correct `inputs` so caching works correctly
+
+**Minimal `turbo.json` task definition:**
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "test": {
+      "dependsOn": ["^build"],
+      "inputs": ["src/**/*.ts", "src/**/*.tsx", "**/*.test.ts", "**/*.test.tsx"],
+      "outputs": ["coverage/**"],
+      "cache": true
+    },
+    "test:watch": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}
+```
+
+**Each package's `package.json`:**
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+**Running tests:**
+
+```bash
+# All packages (respects cache — skips unchanged packages)
+turbo run test
+
+# Force re-run everything, ignore cache
+turbo run test --force
+
+# Only packages affected by current git changes
+turbo run test --filter=...[HEAD^1]
+
+# Single package by name
+turbo run test --filter=@acme/ui
+
+# Single package + its dependents
+turbo run test --filter=@acme/ui...
+
+# Watch mode (not cached — use directly in the package)
+cd packages/ui && pnpm test:watch
+```
+
+> ⚠️ Don't run `vitest --workspace` from the root in a Turborepo project — it bypasses Turborepo's cache and task graph. Always go through `turbo run test`.
+
+---
+
+## Utilities
+
+Pure functions are the easiest to test. Be exhaustive: happy path, edge cases, error cases.
+
+```ts
+// packages/utils/src/format.test.ts
+import { describe, it, expect } from 'vitest'
+import { formatCurrency } from './format'
+
+describe('formatCurrency', () => {
+  it('formats a positive number', () => {
+    expect(formatCurrency(1234.5)).toBe('$1,234.50')
+  })
+
+  it('handles zero', () => {
+    expect(formatCurrency(0)).toBe('$0.00')
+  })
+
+  it('handles negative numbers', () => {
+    expect(formatCurrency(-50)).toBe('-$50.00')
+  })
+
+  it('throws for non-numeric input', () => {
+    expect(() => formatCurrency(NaN)).toThrow()
+  })
+})
+```
+
+**Checklist:**
+- [ ] Happy path
+- [ ] Boundary / edge values (0, empty string, null, undefined)
+- [ ] Error / invalid input
+- [ ] All significant branches of logic
+
+---
+
+## Hooks
+
+Use `renderHook` + `act` for custom hooks. Never test implementation details — test observable behavior.
+
+```ts
+// packages/hooks/src/useCounter.test.ts
+import { describe, it, expect } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useCounter } from './useCounter'
+
+describe('useCounter', () => {
+  it('initializes with the given value', () => {
+    const { result } = renderHook(() => useCounter(5))
+    expect(result.current.count).toBe(5)
+  })
+
+  it('increments the count', () => {
+    const { result } = renderHook(() => useCounter(0))
+    act(() => result.current.increment())
+    expect(result.current.count).toBe(1)
+  })
+
+  it('does not go below 0 when decrementing', () => {
+    const { result } = renderHook(() => useCounter(0))
+    act(() => result.current.decrement())
+    expect(result.current.count).toBe(0)
+  })
+})
+```
+
+### Hooks that use context
+
+```ts
+import { renderHook } from '@testing-library/react'
+import { ThemeProvider } from '../ThemeProvider'
+
+const wrapper = ({ children }: { children: React.ReactNode }) => (
+  <ThemeProvider defaultTheme="dark">{children}</ThemeProvider>
+)
+
+const { result } = renderHook(() => useTheme(), { wrapper })
+```
+
+### Hooks with async operations
+
+```ts
+import { waitFor } from '@testing-library/react'
+
+it('fetches user data', async () => {
+  const { result } = renderHook(() => useUser('user-1'))
+  await waitFor(() => expect(result.current.isLoading).toBe(false))
+  expect(result.current.data?.name).toBe('Alice')
+})
+```
+
+---
+
+## Components
+
+### Basic rendering and interactions
+
+```ts
+// packages/ui/src/Button.test.tsx
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Button } from './Button'
+
+describe('Button', () => {
+  it('renders its label', () => {
+    render(<Button>Save</Button>)
+    expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument()
+  })
+
+  it('calls onClick when clicked', async () => {
+    const user = userEvent.setup()
+    const handleClick = vi.fn()
+    render(<Button onClick={handleClick}>Save</Button>)
+    await user.click(screen.getByRole('button', { name: 'Save' }))
+    expect(handleClick).toHaveBeenCalledOnce()
+  })
+
+  it('is disabled when the disabled prop is set', () => {
+    render(<Button disabled>Save</Button>)
+    expect(screen.getByRole('button')).toBeDisabled()
+  })
+})
+```
+
+### Query priority (in order of preference)
+
+1. `getByRole` — mirrors how assistive tech sees the page
+2. `getByLabelText` — for form elements
+3. `getByPlaceholderText` — fallback for inputs
+4. `getByText` — for non-interactive text
+5. `getByTestId` — last resort only
+
+Avoid `getByClassName` or DOM traversal — tests will break on refactors.
+
+### Form interactions
+
+```ts
+it('submits with the entered email', async () => {
+  const user = userEvent.setup()
+  const onSubmit = vi.fn()
+  render(<LoginForm onSubmit={onSubmit} />)
+
+  await user.type(screen.getByLabelText('Email'), 'alice@example.com')
+  await user.type(screen.getByLabelText('Password'), 'secret123')
+  await user.click(screen.getByRole('button', { name: /sign in/i }))
+
+  expect(onSubmit).toHaveBeenCalledWith({
+    email: 'alice@example.com',
+    password: 'secret123',
+  })
+})
+```
+
+### Testing error states and conditional rendering
+
+```ts
+it('shows validation error for an empty email', async () => {
+  const user = userEvent.setup()
+  render(<LoginForm onSubmit={vi.fn()} />)
+  await user.click(screen.getByRole('button', { name: /sign in/i }))
+  expect(screen.getByText('Email is required')).toBeInTheDocument()
+})
+```
+
+---
+
+## Async Components
+
+Use **MSW v2** to intercept fetch/axios calls at the network level.
+
+### MSW setup (`src/test/server.ts`)
+
+```ts
+import { setupServer } from 'msw/node'
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+  http.get('/api/users/:id', ({ params }) => {
+    return HttpResponse.json({ id: params.id, name: 'Alice' })
+  }),
+]
+
+export const server = setupServer(...handlers)
+```
+
+### Wire up MSW in `setup.ts`
+
+```ts
+import { server } from './server'
+import { beforeAll, afterEach, afterAll } from 'vitest'
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+
+### Override handlers per-test
+
+```ts
+import { http, HttpResponse } from 'msw'
+import { server } from '@/test/server'
+
+it('shows an error on API failure', async () => {
+  server.use(
+    http.get('/api/users/:id', () => HttpResponse.json({ message: 'Not found' }, { status: 404 }))
+  )
+  render(<UserProfile userId="user-1" />)
+  expect(await screen.findByText('User not found')).toBeInTheDocument()
+})
+```
+
+---
+
+## Mocking
+
+### Module mocks (`vi.mock`)
+
+```ts
+// Mock an entire module
+vi.mock('@/lib/analytics', () => ({
+  track: vi.fn(),
+  identify: vi.fn(),
+}))
+
+// Access the mock in tests
+import { track } from '@/lib/analytics'
+expect(vi.mocked(track)).toHaveBeenCalledWith('button_clicked', { label: 'Save' })
+```
+
+### Partial mocks
+
+```ts
+vi.mock('@/lib/date', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/lib/date')>()
+  return { ...actual, now: vi.fn(() => new Date('2024-01-01')) }
+})
+```
+
+### Spying on methods
+
+```ts
+import * as storageModule from '@/lib/storage'
+
+it('calls localStorage.setItem', () => {
+  const spy = vi.spyOn(storageModule, 'saveToStorage')
+  render(<SettingsForm />)
+  // ... interact
+  expect(spy).toHaveBeenCalled()
+})
+```
+
+### Mocking `next/navigation`
+
+```ts
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), back: vi.fn() }),
+  usePathname: () => '/dashboard',
+  useSearchParams: () => new URLSearchParams(),
+}))
+```
+
+### Mocking `next/image` and `next/link`
+
+```ts
+vi.mock('next/image', () => ({
+  default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => <img {...props} />,
+}))
+
+vi.mock('next/link', () => ({
+  default: ({ href, children }: { href: string; children: React.ReactNode }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+```
+
+---
+
+## Next.js Specifics
+
+### Server Components
+
+Server Components can't be rendered with testing-library directly. Two strategies:
+
+1. **Extract logic** into a utility or hook and test that instead (preferred)
+2. **Integration test** via Playwright/Cypress for full page behavior
+
+### Route Handlers (`app/api/*/route.ts`)
+
+```ts
+// app/api/hello/route.test.ts
+import { GET } from './route'
+import { NextRequest } from 'next/server'
+
+it('returns 200 with a greeting', async () => {
+  const req = new NextRequest('http://localhost/api/hello')
+  const res = await GET(req)
+  const body = await res.json()
+
+  expect(res.status).toBe(200)
+  expect(body.message).toBe('Hello')
+})
+```
+
+### Middleware
+
+Test middleware by importing the function directly and passing a mock `NextRequest`:
+
+```ts
+import { middleware } from './middleware'
+import { NextRequest } from 'next/server'
+
+it('redirects unauthenticated users', async () => {
+  const req = new NextRequest('http://localhost/dashboard')
+  const res = await middleware(req)
+  expect(res.status).toBe(307)
+  expect(res.headers.get('location')).toContain('/login')
+})
+```
+
+---
+
+## Shared Packages (Monorepo Patterns)
+
+### Path aliases across packages
+
+In each package's `vitest.config.ts`, use `vite-tsconfig-paths` so `@/` aliases resolve correctly:
+
+```ts
+import tsconfigPaths from 'vite-tsconfig-paths'
+// add to plugins: [tsconfigPaths()]
+```
+
+### Shared test utilities
+
+Create a `packages/test-utils` package (works for both Turborepo and generic monorepos):
+
+```ts
+// packages/test-utils/src/render.tsx
+import { render as rtlRender, RenderOptions } from '@testing-library/react'
+import { AllProviders } from './AllProviders' // QueryClient, Theme, etc.
+
+export function render(ui: React.ReactElement, options?: RenderOptions) {
+  return rtlRender(ui, { wrapper: AllProviders, ...options })
+}
+
+export * from '@testing-library/react'
+```
+
+Import this custom `render` in all tests to avoid boilerplate provider wrapping.
+
+**In Turborepo:** make sure `@acme/test-utils` is listed as a `devDependency` in each package that uses it, and that `turbo.json` includes `"^build"` in the `test` task's `dependsOn` so the test-utils package is built before tests run.
+
+---
+
+## Best Practices
+
+**DO:**
+- Test behavior, not implementation (no asserting on internal state or private methods)
+- Use `screen` queries over destructured render results
+- Use `userEvent` over `fireEvent` (more realistic)
+- Use `findBy*` for async elements (it automatically waits)
+- Group related tests with `describe`
+- Name tests as sentences: `it('shows an error when the email is invalid')`
+- Clean up mocks in `afterEach` or use `vi.restoreAllMocks()`
+
+**DON'T:**
+- Assert on CSS classes or styles (fragile)
+- Use `getByTestId` unless absolutely necessary
+- Test third-party library behavior
+- Snapshot test large component trees (hard to maintain)
+- Use `waitFor` just to delay — prefer `findBy*` for element appearance
+
+---
+
+## Coverage Targets (suggested)
+
+| Package type | Line coverage target |
+|---|---|
+| Utilities / pure functions | 95%+ |
+| Hooks | 85%+ |
+| UI components | 75%+ |
+| Next.js pages | 60%+ (supplement with e2e) |
+
+Run coverage: `vitest run --coverage`
+
+---
+
+## Reference Files
+
+- [→ `references/mock-patterns.md`](./references/mock-patterns.md) — Advanced mocking patterns (timers, globals, env vars)
+- [→ `references/async-patterns.md`](./references/async-patterns.md) — Async testing, loading states, error boundaries
+- [→ `references/monorepo-setup.md`](./references/monorepo-setup.md) — Generic monorepo config (shared test-utils, path aliases, workspace setup)
+- [→ `references/turborepo-setup.md`](./references/turborepo-setup.md) — Full Turborepo setup (task config, caching, pipeline, CI)

package/templates/claude/skills/vitest/references/async-patterns.md

@@ -0,0 +1,82 @@
+# Async Testing Patterns
+
+## Loading states
+
+```ts
+it('shows a spinner while loading', () => {
+  render(<UserProfile userId="1" />)
+  expect(screen.getByRole('progressbar')).toBeInTheDocument()
+})
+
+it('shows user data after loading', async () => {
+  render(<UserProfile userId="1" />)
+  expect(await screen.findByText('Alice')).toBeInTheDocument()
+  expect(screen.queryByRole('progressbar')).not.toBeInTheDocument()
+})
+```
+
+## Error boundaries
+
+```ts
+// Suppress the React error boundary console output
+const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+it('renders the fallback on error', () => {
+  const ThrowingComponent = () => { throw new Error('Boom') }
+  render(
+    <ErrorBoundary fallback={<p>Something went wrong</p>}>
+      <ThrowingComponent />
+    </ErrorBoundary>
+  )
+  expect(screen.getByText('Something went wrong')).toBeInTheDocument()
+  consoleSpy.mockRestore()
+})
+```
+
+## Polling / intervals
+
+```ts
+beforeEach(() => vi.useFakeTimers())
+afterEach(() => vi.useRealTimers())
+
+it('re-fetches every 5 seconds', async () => {
+  render(<LivePriceWidget />)
+  expect(fetch).toHaveBeenCalledTimes(1)
+  vi.advanceTimersByTime(5000)
+  expect(fetch).toHaveBeenCalledTimes(2)
+})
+```
+
+## Waiting for element removal
+
+```ts
+it('removes the toast after 3 seconds', async () => {
+  render(<App />)
+  userEvent.click(screen.getByRole('button', { name: /notify/i }))
+  expect(screen.getByRole('alert')).toBeInTheDocument()
+  await waitForElementToBeRemoved(() => screen.queryByRole('alert'), { timeout: 4000 })
+})
+```
+
+## React Query / SWR
+
+Wrap with a fresh QueryClient per test to avoid cache bleed:
+
+```ts
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  })
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  )
+}
+
+it('fetches and displays the user', async () => {
+  const { result } = renderHook(() => useUser('1'), { wrapper: createWrapper() })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  expect(result.current.data?.name).toBe('Alice')
+})
+```