@macpaw/cctk 1.0.0-beta.1

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

@@ -0,0 +1,78 @@
+# Advanced Mock Patterns
+
+## Timers
+
+```ts
+import { vi, beforeEach, afterEach } from 'vitest'
+
+beforeEach(() => vi.useFakeTimers())
+afterEach(() => vi.useRealTimers())
+
+it('debounces the search input', async () => {
+  const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+  render(<SearchInput />)
+  await user.type(screen.getByRole('searchbox'), 'react')
+  vi.advanceTimersByTime(300)
+  expect(screen.getByText('Searching...')).toBeInTheDocument()
+})
+```
+
+## Environment Variables
+
+```ts
+it('uses the correct API base URL', () => {
+  vi.stubEnv('NEXT_PUBLIC_API_URL', 'https://staging.example.com')
+  const url = buildApiUrl('/users')
+  expect(url).toBe('https://staging.example.com/users')
+  vi.unstubAllEnvs()
+})
+```
+
+## Global mocks (`window`, `navigator`, etc.)
+
+```ts
+it('reads from the clipboard', async () => {
+  Object.assign(navigator, {
+    clipboard: { readText: vi.fn().mockResolvedValue('pasted text') },
+  })
+  render(<ClipboardButton />)
+  await userEvent.click(screen.getByRole('button', { name: /paste/i }))
+  expect(screen.getByDisplayValue('pasted text')).toBeInTheDocument()
+})
+```
+
+## localStorage / sessionStorage
+
+```ts
+beforeEach(() => {
+  localStorage.clear()
+  vi.spyOn(Storage.prototype, 'setItem')
+  vi.spyOn(Storage.prototype, 'getItem')
+})
+
+it('persists the theme preference', () => {
+  render(<ThemeToggle />)
+  userEvent.click(screen.getByRole('switch'))
+  expect(localStorage.setItem).toHaveBeenCalledWith('theme', 'dark')
+})
+```
+
+## Mocking `fetch` directly (no MSW)
+
+```ts
+global.fetch = vi.fn().mockResolvedValue({
+  ok: true,
+  json: async () => ({ id: '1', name: 'Alice' }),
+} as Response)
+```
+
+## Mocking `console` to suppress noise
+
+```ts
+beforeAll(() => {
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+})
+afterAll(() => {
+  vi.mocked(console.error).mockRestore()
+})
+```

package/templates/claude/skills/vitest/references/monorepo-setup.md

@@ -0,0 +1,185 @@
+# Monorepo Vitest Setup
+
+## Typical structure
+
+```
+my-monorepo/
+├── vitest.workspace.ts          # Root workspace config
+├── packages/
+│   ├── ui/
+│   │   ├── vitest.config.ts
+│   │   └── src/
+│   ├── hooks/
+│   │   ├── vitest.config.ts
+│   │   └── src/
+│   └── utils/
+│       ├── vitest.config.ts
+│       └── src/
+└── apps/
+    └── web/                     # Next.js app
+        ├── vitest.config.ts
+        └── src/
+```
+
+## Root `vitest.workspace.ts`
+
+```ts
+import { defineWorkspace } from 'vitest/config'
+
+export default defineWorkspace([
+  'packages/*/vitest.config.ts',
+  'apps/*/vitest.config.ts',
+])
+```
+
+Run all tests: `vitest --workspace`
+
+## Per-package `vitest.config.ts`
+
+```ts
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+import tsconfigPaths from 'vite-tsconfig-paths'
+import { resolve } from 'path'
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, './src'),
+    },
+  },
+  test: {
+    name: 'ui',            // Shows in output, helps identify package
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['../../test-utils/src/setup.ts'],
+    include: ['src/**/*.test.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      include: ['src/**'],
+      exclude: ['src/**/*.stories.tsx', 'src/test/**'],
+    },
+  },
+})
+```
+
+## Shared test setup package (`packages/test-utils`)
+
+### `package.json`
+
+```json
+{
+  "name": "@acme/test-utils",
+  "private": true,
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}
+```
+
+### `src/index.ts`
+
+```ts
+export { render, renderHook, screen, waitFor } from './render'
+export { server } from './server'
+export * from '@testing-library/jest-dom'
+```
+
+### `src/render.tsx`
+
+```ts
+import React from 'react'
+import { render as rtlRender, renderHook as rtlRenderHook, RenderOptions } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { ThemeProvider } from '@acme/ui'
+
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, gcTime: 0 },
+      mutations: { retry: false },
+    },
+  })
+}
+
+function AllProviders({ children }: { children: React.ReactNode }) {
+  const queryClient = createTestQueryClient()
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider defaultTheme="light">
+        {children}
+      </ThemeProvider>
+    </QueryClientProvider>
+  )
+}
+
+export function render(ui: React.ReactElement, options?: RenderOptions) {
+  return rtlRender(ui, { wrapper: AllProviders, ...options })
+}
+
+export function renderHook<T>(hook: () => T) {
+  return rtlRenderHook(hook, { wrapper: AllProviders })
+}
+
+export * from '@testing-library/react'
+```
+
+### `src/server.ts`
+
+```ts
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)
+```
+
+### `src/setup.ts`
+
+```ts
+import '@testing-library/jest-dom'
+import { afterAll, afterEach, beforeAll } from 'vitest'
+import { cleanup } from '@testing-library/react'
+import { server } from './server'
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'warn' }))
+afterEach(() => {
+  server.resetHandlers()
+  cleanup()
+})
+afterAll(() => server.close())
+```
+
+## Sharing path aliases
+
+Use `vite-tsconfig-paths` in each package. Make sure each `tsconfig.json` has paths configured:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+## Running tests selectively
+
+```bash
+# All packages
+vitest --workspace
+
+# Single package
+vitest --project ui
+
+# Single file
+vitest src/components/Button.test.tsx
+
+# Watch mode
+vitest
+
+# Coverage
+vitest run --coverage
+```

package/templates/claude/skills/vitest/references/turborepo-setup.md

@@ -0,0 +1,332 @@
+# Turborepo + Vitest Setup
+
+## Typical structure
+
+```
+my-turborepo/
+├── turbo.json                    # Pipeline config — must declare "test" task
+├── package.json                  # Root, workspaces declared here
+├── pnpm-workspace.yaml           # (if using pnpm)
+├── packages/
+│   ├── test-utils/               # Shared test helpers
+│   │   ├── package.json
+│   │   └── src/
+│   ├── ui/
+│   │   ├── package.json          # Must have "test" script
+│   │   ├── vitest.config.ts
+│   │   └── src/
+│   ├── hooks/
+│   │   ├── package.json
+│   │   ├── vitest.config.ts
+│   │   └── src/
+│   └── utils/
+│       ├── package.json
+│       ├── vitest.config.ts
+│       └── src/
+└── apps/
+    └── web/                      # Next.js app
+        ├── package.json
+        ├── vitest.config.ts
+        └── src/
+```
+
+---
+
+## `turbo.json` — full test task config
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"]
+    },
+    "test": {
+      "dependsOn": ["^build"],
+      "inputs": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "vitest.config.ts",
+        "tsconfig.json"
+      ],
+      "outputs": ["coverage/**"],
+      "cache": true
+    },
+    "test:coverage": {
+      "dependsOn": ["^build"],
+      "inputs": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "**/*.test.ts",
+        "**/*.test.tsx"
+      ],
+      "outputs": ["coverage/**"],
+      "cache": true
+    },
+    "test:watch": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}
+```
+
+**Key points:**
+- `"dependsOn": ["^build"]` — ensures upstream packages (like `test-utils`) are built before tests run
+- `"inputs"` — tells Turbo what files affect the cache key; always include test files and config
+- `"outputs": ["coverage/**"]` — caches coverage reports so CI can read them after `turbo run test`
+- `"cache": false` on `test:watch` — watch mode must never be cached
+
+---
+
+## Per-package `package.json`
+
+```json
+{
+  "name": "@acme/ui",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@acme/test-utils": "workspace:*",
+    "vitest": "^2.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "vite-tsconfig-paths": "^5.0.0"
+  }
+}
+```
+
+---
+
+## Per-package `vitest.config.ts`
+
+```ts
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+import tsconfigPaths from 'vite-tsconfig-paths'
+import { resolve } from 'path'
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, './src'),
+    },
+  },
+  test: {
+    name: 'ui',               // Used by Turbo output labeling & vitest --project
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['../../packages/test-utils/src/setup.ts'],
+    include: ['src/**/*.test.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reportsDirectory: './coverage',
+      reporter: ['text', 'lcov', 'json'],
+      include: ['src/**'],
+      exclude: ['src/**/*.stories.tsx', 'src/test/**'],
+    },
+  },
+})
+```
+
+---
+
+## `packages/test-utils` — shared test helpers
+
+### `package.json`
+
+```json
+{
+  "name": "@acme/test-utils",
+  "private": true,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@testing-library/user-event": "^14.0.0",
+    "@testing-library/jest-dom": "^6.0.0",
+    "msw": "^2.0.0"
+  }
+}
+```
+
+### `src/setup.ts`
+
+```ts
+import '@testing-library/jest-dom'
+import { afterAll, afterEach, beforeAll } from 'vitest'
+import { cleanup } from '@testing-library/react'
+import { server } from './server'
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'warn' }))
+afterEach(() => {
+  server.resetHandlers()
+  cleanup()
+})
+afterAll(() => server.close())
+```
+
+### `src/render.tsx`
+
+```ts
+import React from 'react'
+import {
+  render as rtlRender,
+  renderHook as rtlRenderHook,
+  type RenderOptions,
+} from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, gcTime: 0 },
+      mutations: { retry: false },
+    },
+  })
+}
+
+function AllProviders({ children }: { children: React.ReactNode }) {
+  const qc = createTestQueryClient()
+  return <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+}
+
+export function render(ui: React.ReactElement, options?: RenderOptions) {
+  return rtlRender(ui, { wrapper: AllProviders, ...options })
+}
+
+export function renderHook<T>(hook: () => T) {
+  return rtlRenderHook(hook, { wrapper: AllProviders })
+}
+
+export * from '@testing-library/react'
+```
+
+### `src/server.ts`
+
+```ts
+import { setupServer } from 'msw/node'
+import { http, HttpResponse } from 'msw'
+
+// Add your baseline handlers here or keep empty and override per-test
+export const handlers = [
+  http.get('/api/health', () => HttpResponse.json({ status: 'ok' })),
+]
+
+export const server = setupServer(...handlers)
+export { http, HttpResponse }
+```
+
+### `src/index.ts`
+
+```ts
+export { render, renderHook } from './render'
+export { server, http, HttpResponse } from './server'
+export * from '@testing-library/react'
+export * from '@testing-library/jest-dom'
+```
+
+---
+
+## Running tests
+
+```bash
+# All packages — uses cache, only re-runs what changed
+turbo run test
+
+# Force re-run all, ignore cache
+turbo run test --force
+
+# Only packages affected by changes since last commit
+turbo run test --filter=...[HEAD^1]
+
+# Only packages affected by changes on a branch vs main
+turbo run test --filter=...[origin/main]
+
+# Single package
+turbo run test --filter=@acme/ui
+
+# Single package + all packages that depend on it
+turbo run test --filter=@acme/ui...
+
+# All packages that depend on ui (downstream)
+turbo run test --filter=...@acme/ui
+
+# Coverage for all
+turbo run test:coverage
+
+# Watch mode — run directly in the package (not via turbo)
+cd packages/ui && pnpm test:watch
+```
+
+---
+
+## CI setup (GitHub Actions example)
+
+```yaml
+name: Test
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # needed for --filter=[...] comparisons
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: turbo run test --filter=...[origin/main]
+        # On main branch, run everything:
+        # run: turbo run test
+```
+
+### Turborepo remote caching in CI
+
+Add to your CI env to enable remote cache (skips unchanged packages across CI runs):
+
+```yaml
+env:
+  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
+```
+
+Get these from your Vercel dashboard (Turborepo remote cache is free on Vercel).
+
+---
+
+## Common gotchas
+
+**`turbo run test` says "cache hit" but tests didn't run**
+→ That's correct behavior — the inputs haven't changed. Use `--force` to bypass.
+
+**Tests pass locally but fail in CI**
+→ Check that `turbo.json` `inputs` includes all relevant files. If a config file (e.g. `tsconfig.json`, `.env.test`) is missing from `inputs`, Turbo won't invalidate the cache when it changes.
+
+**Packages not found by `--filter`**
+→ Make sure `name` in each package's `package.json` matches what you pass to `--filter`. Use `turbo ls` to see all recognized packages.
+
+**`test-utils` changes don't re-trigger dependent packages**
+→ Add `"dependsOn": ["^build"]` to the `test` task, and make sure `test-utils` has a `build` script. Turbo tracks the build output hash of upstream packages as part of the cache key.