qa-workflow-cc 1.0.0

package/skills/qa/templates/unit-test.md

@@ -0,0 +1,998 @@
+---
+name: unit-test
+description: Create {{testRunner}} unit tests following project patterns. Use when writing tests for utilities, hooks, or pure functions.
+context: fork
+agent: test-qa
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Bash
+---
+
+# Unit Test Creation ({{testRunner}})
+
+This skill guides creation of unit tests using {{testRunner}}.
+
+## Template Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `{{testRunner}}` | Test runner name (vitest, jest) | vitest |
+| `{{testCommand}}` | Command to run tests | pnpm test |
+| `{{testCoverageCommand}}` | Command for coverage report | pnpm test:coverage |
+| `{{testWatchCommand}}` | Command for watch mode | pnpm test:watch |
+| `{{srcAlias}}` | Import alias for source files | @/ |
+| `{{sharedPackage}}` | Shared package import path | @myapp/shared |
+
+---
+
+## Prerequisites
+
+- Understand the function/module being tested
+- Know input/output expectations
+- Identify edge cases and boundary conditions
+- Check existing test patterns in the codebase
+
+---
+
+## Test File Structure
+
+```typescript
+// __tests__/utils/formatCurrency.test.ts
+import { describe, it, expect, vi, beforeEach, afterEach } from '{{testRunner}}'
+import { formatCurrency, parseCurrency } from '{{srcAlias}}lib/utils/currency'
+
+describe('formatCurrency', () => {
+  // Group related tests
+  describe('basic formatting', () => {
+    it('formats positive numbers with $ and commas', () => {
+      expect(formatCurrency(1234.56)).toBe('$1,234.56')
+    })
+
+    it('formats zero as $0.00', () => {
+      expect(formatCurrency(0)).toBe('$0.00')
+    })
+
+    it('formats negative numbers with minus sign', () => {
+      expect(formatCurrency(-500)).toBe('-$500.00')
+    })
+  })
+
+  // Edge cases
+  describe('edge cases', () => {
+    it('handles undefined by returning $0.00', () => {
+      expect(formatCurrency(undefined as any)).toBe('$0.00')
+    })
+
+    it('handles NaN by returning $0.00', () => {
+      expect(formatCurrency(NaN)).toBe('$0.00')
+    })
+
+    it('handles very large numbers', () => {
+      expect(formatCurrency(1000000000)).toBe('$1,000,000,000.00')
+    })
+  })
+})
+```
+
+---
+
+## Test Naming Convention
+
+```
+[file-being-tested].test.ts
+```
+
+| Source File | Test File |
+|-------------|-----------|
+| `lib/utils/currency.ts` | `__tests__/utils/currency.test.ts` |
+| `lib/hooks/useDebounce.ts` | `__tests__/hooks/useDebounce.test.ts` |
+| `lib/api/transform.ts` | `__tests__/api/transform.test.ts` |
+| `services/email.ts` | `__tests__/services/email.test.ts` |
+
+---
+
+## Testing Patterns
+
+### Testing Pure Functions
+
+```typescript
+import { describe, it, expect } from '{{testRunner}}'
+import { calculateTax, calculateTotal } from '{{srcAlias}}lib/utils/pricing'
+
+describe('calculateTax', () => {
+  it('calculates percentage-based tax correctly', () => {
+    const result = calculateTax(100, 0.0825)
+    expect(result).toBe(8.25)
+  })
+
+  it('rounds to 2 decimal places', () => {
+    const result = calculateTax(99.99, 0.0825)
+    expect(result).toBeCloseTo(8.25, 2)
+  })
+
+  it('returns 0 for zero amount', () => {
+    const result = calculateTax(0, 0.0825)
+    expect(result).toBe(0)
+  })
+
+  it('handles negative amounts', () => {
+    const result = calculateTax(-100, 0.0825)
+    expect(result).toBe(-8.25)
+  })
+})
+```
+
+### Testing with Mocks
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from '{{testRunner}}'
+import { fetchUserData } from '{{srcAlias}}lib/api/users'
+
+// Mock the API client module
+vi.mock('{{srcAlias}}lib/api/client', () => ({
+  apiClient: {
+    get: vi.fn(),
+    post: vi.fn(),
+    put: vi.fn(),
+    delete: vi.fn(),
+  },
+}))
+
+import { apiClient } from '{{srcAlias}}lib/api/client'
+
+describe('fetchUserData', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns user data on success', async () => {
+    const mockUser = { id: '1', name: 'Jane Smith', email: 'jane@example.com' }
+    vi.mocked(apiClient.get).mockResolvedValue({ data: mockUser })
+
+    const result = await fetchUserData('1')
+
+    expect(apiClient.get).toHaveBeenCalledWith('/users/1')
+    expect(result).toEqual(mockUser)
+  })
+
+  it('throws on API error', async () => {
+    vi.mocked(apiClient.get).mockRejectedValue(new Error('Network error'))
+
+    await expect(fetchUserData('1')).rejects.toThrow('Network error')
+  })
+
+  it('passes query parameters correctly', async () => {
+    vi.mocked(apiClient.get).mockResolvedValue({ data: {} })
+
+    await fetchUserData('1', { include: 'profile' })
+
+    expect(apiClient.get).toHaveBeenCalledWith('/users/1', {
+      params: { include: 'profile' },
+    })
+  })
+})
+```
+
+### Testing Async Functions
+
+```typescript
+import { describe, it, expect, vi } from '{{testRunner}}'
+import { waitForCondition } from '{{srcAlias}}lib/utils/async'
+
+describe('waitForCondition', () => {
+  it('resolves when condition becomes true', async () => {
+    let counter = 0
+    const condition = () => {
+      counter++
+      return counter >= 3
+    }
+
+    await expect(waitForCondition(condition, 100)).resolves.toBe(true)
+    expect(counter).toBe(3)
+  })
+
+  it('rejects after timeout', async () => {
+    const neverTrue = () => false
+
+    await expect(
+      waitForCondition(neverTrue, 50)
+    ).rejects.toThrow('Timeout')
+  })
+})
+
+describe('retryWithBackoff', () => {
+  it('succeeds on first attempt', async () => {
+    const fn = vi.fn().mockResolvedValue('success')
+
+    const result = await retryWithBackoff(fn, { maxRetries: 3 })
+
+    expect(result).toBe('success')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries on failure and eventually succeeds', async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error('fail 1'))
+      .mockRejectedValueOnce(new Error('fail 2'))
+      .mockResolvedValue('success')
+
+    const result = await retryWithBackoff(fn, { maxRetries: 3 })
+
+    expect(result).toBe('success')
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  it('throws after exhausting retries', async () => {
+    const fn = vi.fn().mockRejectedValue(new Error('persistent failure'))
+
+    await expect(
+      retryWithBackoff(fn, { maxRetries: 2 })
+    ).rejects.toThrow('persistent failure')
+    expect(fn).toHaveBeenCalledTimes(3) // initial + 2 retries
+  })
+})
+```
+
+### Testing with Timers
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from '{{testRunner}}'
+import { debounce } from '{{srcAlias}}lib/utils/debounce'
+
+describe('debounce', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('delays function execution', () => {
+    const fn = vi.fn()
+    const debounced = debounce(fn, 300)
+
+    debounced()
+    expect(fn).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(300)
+    expect(fn).toHaveBeenCalledOnce()
+  })
+
+  it('resets timer on subsequent calls', () => {
+    const fn = vi.fn()
+    const debounced = debounce(fn, 300)
+
+    debounced()
+    vi.advanceTimersByTime(200)
+    debounced()
+    vi.advanceTimersByTime(200)
+
+    expect(fn).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(100)
+    expect(fn).toHaveBeenCalledOnce()
+  })
+
+  it('passes arguments from the last call', () => {
+    const fn = vi.fn()
+    const debounced = debounce(fn, 300)
+
+    debounced('first')
+    debounced('second')
+    debounced('third')
+
+    vi.advanceTimersByTime(300)
+
+    expect(fn).toHaveBeenCalledOnce()
+    expect(fn).toHaveBeenCalledWith('third')
+  })
+
+  it('can be cancelled', () => {
+    const fn = vi.fn()
+    const debounced = debounce(fn, 300)
+
+    debounced()
+    debounced.cancel()
+
+    vi.advanceTimersByTime(300)
+    expect(fn).not.toHaveBeenCalled()
+  })
+})
+```
+
+### Testing with Date/Time
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from '{{testRunner}}'
+import { formatRelativeTime, isExpired } from '{{srcAlias}}lib/utils/date'
+
+describe('formatRelativeTime', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2024-06-15T12:00:00Z'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('returns "just now" for recent timestamps', () => {
+    const now = new Date()
+    expect(formatRelativeTime(now)).toBe('just now')
+  })
+
+  it('returns "5 minutes ago" for 5-minute-old timestamps', () => {
+    const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000)
+    expect(formatRelativeTime(fiveMinAgo)).toBe('5 minutes ago')
+  })
+
+  it('returns "yesterday" for 24-hour-old timestamps', () => {
+    const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000)
+    expect(formatRelativeTime(yesterday)).toBe('yesterday')
+  })
+})
+
+describe('isExpired', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2024-06-15T12:00:00Z'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('returns true for past dates', () => {
+    expect(isExpired(new Date('2024-06-14T00:00:00Z'))).toBe(true)
+  })
+
+  it('returns false for future dates', () => {
+    expect(isExpired(new Date('2024-06-16T00:00:00Z'))).toBe(false)
+  })
+})
+```
+
+---
+
+## Testing Hooks
+
+```typescript
+import { describe, it, expect } from '{{testRunner}}'
+import { renderHook, act } from '@testing-library/react'
+import { useCounter } from '{{srcAlias}}lib/hooks/useCounter'
+
+describe('useCounter', () => {
+  it('initializes with default value', () => {
+    const { result } = renderHook(() => useCounter())
+    expect(result.current.count).toBe(0)
+  })
+
+  it('initializes with provided value', () => {
+    const { result } = renderHook(() => useCounter(10))
+    expect(result.current.count).toBe(10)
+  })
+
+  it('increments count', () => {
+    const { result } = renderHook(() => useCounter())
+
+    act(() => {
+      result.current.increment()
+    })
+
+    expect(result.current.count).toBe(1)
+  })
+
+  it('decrements count', () => {
+    const { result } = renderHook(() => useCounter(5))
+
+    act(() => {
+      result.current.decrement()
+    })
+
+    expect(result.current.count).toBe(4)
+  })
+
+  it('resets to initial value', () => {
+    const { result } = renderHook(() => useCounter(10))
+
+    act(() => {
+      result.current.increment()
+      result.current.increment()
+    })
+
+    expect(result.current.count).toBe(12)
+
+    act(() => {
+      result.current.reset()
+    })
+
+    expect(result.current.count).toBe(10)
+  })
+})
+```
+
+### Testing Hooks with Dependencies
+
+```typescript
+import { describe, it, expect, vi } from '{{testRunner}}'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { useDebounce } from '{{srcAlias}}lib/hooks/useDebounce'
+
+describe('useDebounce', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('returns initial value immediately', () => {
+    const { result } = renderHook(() => useDebounce('hello', 300))
+    expect(result.current).toBe('hello')
+  })
+
+  it('debounces value updates', () => {
+    const { result, rerender } = renderHook(
+      ({ value, delay }) => useDebounce(value, delay),
+      { initialProps: { value: 'hello', delay: 300 } }
+    )
+
+    rerender({ value: 'world', delay: 300 })
+    expect(result.current).toBe('hello') // Still old value
+
+    act(() => {
+      vi.advanceTimersByTime(300)
+    })
+
+    expect(result.current).toBe('world') // Now updated
+  })
+})
+```
+
+### Testing Hooks with Context Providers
+
+```typescript
+import { describe, it, expect } from '{{testRunner}}'
+import { renderHook } from '@testing-library/react'
+import { useTheme } from '{{srcAlias}}lib/hooks/useTheme'
+import { ThemeProvider } from '{{srcAlias}}lib/providers/ThemeProvider'
+
+describe('useTheme', () => {
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <ThemeProvider defaultTheme="light">{children}</ThemeProvider>
+  )
+
+  it('returns current theme from context', () => {
+    const { result } = renderHook(() => useTheme(), { wrapper })
+    expect(result.current.theme).toBe('light')
+  })
+
+  it('throws when used outside ThemeProvider', () => {
+    expect(() => {
+      renderHook(() => useTheme())
+    }).toThrow('useTheme must be used within a ThemeProvider')
+  })
+})
+```
+
+---
+
+## Assertions Reference
+
+| Assertion | Use For |
+|-----------|---------|
+| `expect(x).toBe(y)` | Primitive equality (===) |
+| `expect(x).toEqual(y)` | Deep equality (objects/arrays) |
+| `expect(x).toStrictEqual(y)` | Deep equality + type checking |
+| `expect(x).toBeCloseTo(y, n)` | Float comparison (n decimal places) |
+| `expect(x).toBeTruthy()` | Truthy values |
+| `expect(x).toBeFalsy()` | Falsy values |
+| `expect(x).toBeNull()` | Null check |
+| `expect(x).toBeUndefined()` | Undefined check |
+| `expect(x).toBeDefined()` | Defined check |
+| `expect(x).toBeInstanceOf(C)` | Instance of class |
+| `expect(x).toContain(y)` | Array/string contains |
+| `expect(x).toContainEqual(y)` | Array contains object (deep) |
+| `expect(x).toHaveLength(n)` | Array/string length |
+| `expect(x).toHaveProperty(k)` | Object has property |
+| `expect(x).toHaveProperty(k, v)` | Object has property with value |
+| `expect(x).toMatch(/regex/)` | String matches regex |
+| `expect(x).toMatchObject(y)` | Object contains subset |
+| `expect(fn).toThrow()` | Exception thrown |
+| `expect(fn).toThrow('msg')` | Specific exception message |
+| `expect(fn).toThrow(ErrorClass)` | Specific error type |
+| `expect(mock).toHaveBeenCalled()` | Mock was called |
+| `expect(mock).toHaveBeenCalledWith(x)` | Mock called with args |
+| `expect(mock).toHaveBeenCalledTimes(n)` | Call count |
+| `expect(mock).toHaveBeenLastCalledWith(x)` | Last call args |
+| `expect(mock).toHaveReturnedWith(x)` | Mock returned value |
+
+### Negation
+
+All assertions can be negated with `.not`:
+
+```typescript
+expect(value).not.toBe(other)
+expect(array).not.toContain(item)
+expect(fn).not.toThrow()
+```
+
+### Asymmetric Matchers
+
+```typescript
+expect(obj).toEqual({
+  id: expect.any(String),
+  name: 'Test',
+  createdAt: expect.any(Date),
+  tags: expect.arrayContaining(['important']),
+  metadata: expect.objectContaining({ version: 1 }),
+})
+```
+
+---
+
+## Testing Zod Schemas
+
+Validate Zod schemas independently to verify input validation logic:
+
+```typescript
+import { describe, it, expect } from '{{testRunner}}'
+import { z } from 'zod'
+
+// Import the schema (or define inline if testing a schema module)
+const createItemSchema = z.object({
+  name: z.string().min(1).max(255),
+  email: z.string().email().optional(),
+  phone: z.string().regex(/^\+?[0-9]{10,15}$/).optional(),
+  status: z.enum(['DRAFT', 'ACTIVE', 'ARCHIVED']).default('DRAFT'),
+  description: z.string().max(5000).optional(),
+  tags: z.array(z.string()).max(10).optional(),
+})
+
+describe('createItemSchema', () => {
+  describe('valid inputs', () => {
+    it('accepts minimal valid input', () => {
+      const result = createItemSchema.safeParse({ name: 'Test Item' })
+      expect(result.success).toBe(true)
+      if (result.success) {
+        expect(result.data.status).toBe('DRAFT') // default applied
+      }
+    })
+
+    it('accepts full valid input', () => {
+      const result = createItemSchema.safeParse({
+        name: 'Full Item',
+        email: 'user@example.com',
+        phone: '+15551234567',
+        status: 'ACTIVE',
+        description: 'A full description',
+        tags: ['important', 'urgent'],
+      })
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('invalid inputs', () => {
+    it('rejects empty name', () => {
+      const result = createItemSchema.safeParse({ name: '' })
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects name over 255 chars', () => {
+      const result = createItemSchema.safeParse({ name: 'x'.repeat(256) })
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects invalid email', () => {
+      const result = createItemSchema.safeParse({
+        name: 'Test',
+        email: 'not-an-email',
+      })
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects invalid phone format', () => {
+      const result = createItemSchema.safeParse({
+        name: 'Test',
+        phone: '123',
+      })
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects invalid status enum', () => {
+      const result = createItemSchema.safeParse({
+        name: 'Test',
+        status: 'INVALID_STATUS',
+      })
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects description over 5000 chars', () => {
+      const result = createItemSchema.safeParse({
+        name: 'Test',
+        description: 'x'.repeat(5001),
+      })
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects more than 10 tags', () => {
+      const result = createItemSchema.safeParse({
+        name: 'Test',
+        tags: Array.from({ length: 11 }, (_, i) => `tag-${i}`),
+      })
+      expect(result.success).toBe(false)
+    })
+  })
+
+  describe('type coercion and stripping', () => {
+    it('strips unknown fields', () => {
+      const result = createItemSchema.safeParse({
+        name: 'Test',
+        unknownField: 'should be removed',
+      })
+      expect(result.success).toBe(true)
+      if (result.success) {
+        expect(result.data).not.toHaveProperty('unknownField')
+      }
+    })
+  })
+})
+```
+
+### Shared Schema Testing Pattern
+
+For schemas exported from shared packages:
+
+```typescript
+import { describe, it, expect } from '{{testRunner}}'
+import { phoneSchema, emailSchema, urlSchema } from '{{sharedPackage}}'
+
+describe('shared validation schemas', () => {
+  describe('phoneSchema', () => {
+    it.each([
+      ['+15551234567', true],
+      ['5551234567', true],
+      ['+1234', false],       // Too short
+      ['abc', false],         // Not numeric
+      ['', false],            // Empty
+    ])('validates %s -> %s', (input, expected) => {
+      expect(phoneSchema.safeParse(input).success).toBe(expected)
+    })
+  })
+
+  describe('emailSchema', () => {
+    it.each([
+      ['user@example.com', true],
+      ['name+tag@domain.co', true],
+      ['invalid', false],
+      ['@no-user.com', false],
+      ['', false],
+    ])('validates %s -> %s', (input, expected) => {
+      expect(emailSchema.safeParse(input).success).toBe(expected)
+    })
+  })
+
+  describe('urlSchema', () => {
+    it.each([
+      ['https://example.com', true],
+      ['http://localhost:3000', true],
+      ['ftp://invalid.com', false],
+      ['not-a-url', false],
+    ])('validates %s -> %s', (input, expected) => {
+      expect(urlSchema.safeParse(input).success).toBe(expected)
+    })
+  })
+})
+```
+
+---
+
+## Testing Error Handling
+
+```typescript
+import { describe, it, expect, vi } from '{{testRunner}}'
+import { processPayment } from '{{srcAlias}}lib/services/payment'
+
+describe('processPayment', () => {
+  it('throws typed error for insufficient funds', async () => {
+    const error = await processPayment({ amount: 99999 }).catch(e => e)
+
+    expect(error).toBeInstanceOf(PaymentError)
+    expect(error.code).toBe('INSUFFICIENT_FUNDS')
+    expect(error.message).toContain('insufficient')
+  })
+
+  it('wraps unexpected errors in a generic PaymentError', async () => {
+    vi.spyOn(gateway, 'charge').mockRejectedValue(new Error('connection reset'))
+
+    const error = await processPayment({ amount: 10 }).catch(e => e)
+
+    expect(error).toBeInstanceOf(PaymentError)
+    expect(error.code).toBe('GATEWAY_ERROR')
+  })
+})
+```
+
+---
+
+## Testing Environment Variables
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from '{{testRunner}}'
+import { getConfig } from '{{srcAlias}}lib/config'
+
+describe('getConfig', () => {
+  const originalEnv = process.env
+
+  beforeEach(() => {
+    vi.resetModules()
+    process.env = { ...originalEnv }
+  })
+
+  afterEach(() => {
+    process.env = originalEnv
+  })
+
+  it('reads configuration from env vars', () => {
+    process.env.API_URL = 'https://api.example.com'
+    process.env.API_KEY = 'test-key-123'
+
+    const config = getConfig()
+
+    expect(config.apiUrl).toBe('https://api.example.com')
+    expect(config.apiKey).toBe('test-key-123')
+  })
+
+  it('throws if required env var is missing', () => {
+    delete process.env.API_URL
+
+    expect(() => getConfig()).toThrow('API_URL is required')
+  })
+
+  it('uses default values for optional config', () => {
+    process.env.API_URL = 'https://api.example.com'
+    process.env.API_KEY = 'test-key'
+
+    const config = getConfig()
+
+    expect(config.timeout).toBe(5000) // default
+    expect(config.retries).toBe(3) // default
+  })
+})
+```
+
+---
+
+## Testing Data Transformations
+
+```typescript
+import { describe, it, expect } from '{{testRunner}}'
+import { transformApiResponse, normalizeUser } from '{{srcAlias}}lib/transforms'
+
+describe('transformApiResponse', () => {
+  it('maps API snake_case to camelCase', () => {
+    const apiData = {
+      user_name: 'Jane',
+      created_at: '2024-01-15T00:00:00Z',
+      is_active: true,
+    }
+
+    const result = transformApiResponse(apiData)
+
+    expect(result).toEqual({
+      userName: 'Jane',
+      createdAt: '2024-01-15T00:00:00Z',
+      isActive: true,
+    })
+  })
+
+  it('handles nested objects', () => {
+    const apiData = {
+      user_profile: {
+        first_name: 'Jane',
+        last_name: 'Smith',
+      },
+    }
+
+    const result = transformApiResponse(apiData)
+
+    expect(result).toEqual({
+      userProfile: {
+        firstName: 'Jane',
+        lastName: 'Smith',
+      },
+    })
+  })
+
+  it('handles empty objects', () => {
+    expect(transformApiResponse({})).toEqual({})
+  })
+
+  it('handles null and undefined', () => {
+    expect(transformApiResponse(null)).toBeNull()
+    expect(transformApiResponse(undefined)).toBeUndefined()
+  })
+})
+```
+
+---
+
+## Testing Background Job Processors
+
+For projects using background job frameworks (BullMQ, Temporal, etc.), test processors by mocking the job object and its dependencies:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from '{{testRunner}}'
+
+// Mock external services before importing processor
+vi.mock('{{srcAlias}}services/database', () => ({
+  db: {
+    user: {
+      findFirst: vi.fn(),
+      update: vi.fn(),
+    },
+    activityLog: {
+      create: vi.fn(),
+    },
+  },
+}))
+
+vi.mock('{{srcAlias}}services/external-api', () => ({
+  enrichData: vi.fn().mockResolvedValue({
+    summary: 'Test enrichment summary',
+    score: 85,
+  }),
+}))
+
+import { db } from '{{srcAlias}}services/database'
+import { processEnrichment } from '../processors/enrichment'
+import { enrichData } from '{{srcAlias}}services/external-api'
+
+describe('enrichment processor', () => {
+  const createMockJob = (data: any) => ({
+    id: 'job-123',
+    data,
+    attemptsMade: 0,
+    log: vi.fn(),
+    updateProgress: vi.fn(),
+  })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('enriches data and updates record', async () => {
+    const mockRecord = { id: 'rec-1', name: 'Acme Corp' }
+    vi.mocked(db.user.findFirst).mockResolvedValue(mockRecord as any)
+    vi.mocked(db.user.update).mockResolvedValue({ ...mockRecord, enriched: true } as any)
+
+    const job = createMockJob({ recordId: 'rec-1' })
+    await processEnrichment(job as any)
+
+    expect(db.user.findFirst).toHaveBeenCalledWith({
+      where: { id: 'rec-1' },
+    })
+
+    expect(enrichData).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'Acme Corp' })
+    )
+
+    expect(db.user.update).toHaveBeenCalledWith({
+      where: { id: 'rec-1' },
+      data: expect.objectContaining({ enriched: true }),
+    })
+  })
+
+  it('throws if record not found', async () => {
+    vi.mocked(db.user.findFirst).mockResolvedValue(null)
+
+    const job = createMockJob({ recordId: 'nonexistent' })
+
+    await expect(processEnrichment(job as any)).rejects.toThrow()
+  })
+
+  it('logs progress during processing', async () => {
+    vi.mocked(db.user.findFirst).mockResolvedValue({ id: 'rec-1' } as any)
+    vi.mocked(db.user.update).mockResolvedValue({} as any)
+
+    const job = createMockJob({ recordId: 'rec-1' })
+    await processEnrichment(job as any)
+
+    expect(job.updateProgress).toHaveBeenCalled()
+  })
+})
+```
+
+### Mock Job Factory (Reusable)
+
+```typescript
+// test/helpers.ts
+import { vi } from '{{testRunner}}'
+
+export function createMockJob<T>(data: T, overrides: Partial<any> = {}) {
+  return {
+    id: overrides.id ?? `job-${Date.now()}`,
+    name: overrides.name ?? 'test-job',
+    data,
+    attemptsMade: overrides.attemptsMade ?? 0,
+    opts: overrides.opts ?? {},
+    timestamp: Date.now(),
+    log: vi.fn(),
+    updateProgress: vi.fn(),
+    moveToFailed: vi.fn(),
+    moveToCompleted: vi.fn(),
+    ...overrides,
+  }
+}
+```
+
+---
+
+## Test Coverage
+
+Run coverage report:
+
+```bash
+{{testCoverageCommand}}
+```
+
+Coverage thresholds (if configured):
+- Statements: 80%
+- Branches: 70%
+- Functions: 80%
+- Lines: 80%
+
+---
+
+## Checklist
+
+Before submitting tests:
+
+- [ ] Test file follows naming convention
+- [ ] Tests are organized with `describe` blocks
+- [ ] Test names describe expected behavior (not implementation)
+- [ ] Edge cases are covered (null, undefined, empty, boundary values)
+- [ ] Error cases are tested (thrown errors, rejected promises)
+- [ ] Mocks are cleared between tests (`vi.clearAllMocks()` in `beforeEach`)
+- [ ] No hardcoded timeouts (use fake timers)
+- [ ] Tests are deterministic (no random failures, no shared state)
+- [ ] Tests run in isolation (no dependency on test execution order)
+- [ ] Environment is restored after tests (`afterEach` cleanup)
+
+---
+
+## Running Tests
+
+```bash
+# Run all tests
+{{testCommand}}
+
+# Run specific test file
+{{testCommand}} utils/currency.test.ts
+
+# Run tests in watch mode
+{{testWatchCommand}}
+
+# Run with coverage
+{{testCoverageCommand}}
+
+# Run tests matching a pattern
+{{testCommand}} --testNamePattern="formatCurrency"
+
+# Run tests in a specific directory
+{{testCommand}} __tests__/utils/
+```
+
+---
+
+## See Also
+
+- `component-test.md` - Component testing patterns
+- `e2e-test.md` - End-to-end testing patterns
+- `test-standards.md` - Coverage thresholds and test type requirements