qa-workflow-cc 1.0.0

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

@@ -0,0 +1,1088 @@
+---
+name: component-test
+description: Create tests for React components using Testing Library. Use when testing UI components, user interactions, and rendering logic.
+context: fork
+agent: test-qa
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Bash
+---
+
+# Component Testing (Testing Library)
+
+This skill guides creation of tests for React components using {{componentTestLib}}.
+
+## Template Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `{{componentTestLib}}` | Testing library package | @testing-library/react |
+| `{{testRunner}}` | Test runner name (vitest, jest) | vitest |
+| `{{testCommand}}` | Command to run tests | pnpm test |
+| `{{framework}}` | Framework (react, react-native, next) | react |
+| `{{srcAlias}}` | Import alias for source files | @/ |
+
+---
+
+## Prerequisites
+
+- Understand the component being tested
+- Know the expected rendering behavior
+- Identify user interaction patterns
+- Check for required context providers
+
+---
+
+## Web Component Test Structure
+
+```typescript
+// components/__tests__/ItemCard.test.tsx
+import { render, screen, fireEvent, waitFor } from '{{componentTestLib}}'
+import userEvent from '@testing-library/user-event'
+import { describe, it, expect, vi } from '{{testRunner}}'
+import { ItemCard } from '../ItemCard'
+
+describe('ItemCard', () => {
+  const defaultProps = {
+    item: {
+      id: '1',
+      name: 'Sample Item',
+      email: 'sample@example.com',
+      status: 'ACTIVE' as const,
+      createdAt: new Date('2024-01-15'),
+    },
+    onEdit: vi.fn(),
+    onDelete: vi.fn(),
+  }
+
+  it('renders item information', () => {
+    render(<ItemCard {...defaultProps} />)
+
+    expect(screen.getByText('Sample Item')).toBeInTheDocument()
+    expect(screen.getByText('sample@example.com')).toBeInTheDocument()
+    expect(screen.getByText('ACTIVE')).toBeInTheDocument()
+  })
+
+  it('calls onEdit when edit button clicked', async () => {
+    const user = userEvent.setup()
+    render(<ItemCard {...defaultProps} />)
+
+    await user.click(screen.getByRole('button', { name: /edit/i }))
+
+    expect(defaultProps.onEdit).toHaveBeenCalledWith(defaultProps.item)
+  })
+
+  it('shows confirmation before delete', async () => {
+    const user = userEvent.setup()
+    render(<ItemCard {...defaultProps} />)
+
+    await user.click(screen.getByRole('button', { name: /delete/i }))
+
+    expect(screen.getByText(/are you sure/i)).toBeInTheDocument()
+  })
+
+  it('calls onDelete after confirmation', async () => {
+    const user = userEvent.setup()
+    render(<ItemCard {...defaultProps} />)
+
+    await user.click(screen.getByRole('button', { name: /delete/i }))
+    await user.click(screen.getByRole('button', { name: /confirm/i }))
+
+    expect(defaultProps.onDelete).toHaveBeenCalledWith(defaultProps.item.id)
+  })
+})
+```
+
+---
+
+## Query Priority (Best Practices)
+
+Use queries in this order of preference:
+
+| Priority | Query | Use When |
+|----------|-------|----------|
+| 1 | `getByRole` | Element has semantic role (button, heading, textbox, etc.) |
+| 2 | `getByLabelText` | Form inputs with labels |
+| 3 | `getByPlaceholderText` | Inputs with placeholder text |
+| 4 | `getByText` | Non-interactive text content |
+| 5 | `getByDisplayValue` | Input with current value |
+| 6 | `getByAltText` | Images with alt text |
+| 7 | `getByTitle` | Elements with title attribute |
+| 8 | `getByTestId` | Last resort, for complex elements |
+
+```typescript
+// GOOD - Uses semantic queries
+screen.getByRole('button', { name: /submit/i })
+screen.getByRole('textbox', { name: /email/i })
+screen.getByRole('heading', { level: 1, name: /dashboard/i })
+screen.getByLabelText(/password/i)
+
+// AVOID - Too implementation-specific
+screen.getByTestId('submit-button')
+document.querySelector('.btn-primary')
+```
+
+### Query Variants
+
+| Variant | Returns | Throws if not found? | Use for |
+|---------|---------|---------------------|---------|
+| `getBy*` | Element | Yes | Elements that should exist |
+| `queryBy*` | Element or null | No | Asserting absence |
+| `findBy*` | Promise<Element> | Yes (timeout) | Async elements |
+| `getAllBy*` | Element[] | Yes | Multiple elements |
+| `queryAllBy*` | Element[] (empty ok) | No | Optional multiple elements |
+| `findAllBy*` | Promise<Element[]> | Yes (timeout) | Async multiple elements |
+
+```typescript
+// Assert element exists
+expect(screen.getByText('Hello')).toBeInTheDocument()
+
+// Assert element does NOT exist
+expect(screen.queryByText('Goodbye')).not.toBeInTheDocument()
+
+// Wait for async element
+const element = await screen.findByText('Loaded data')
+expect(element).toBeInTheDocument()
+```
+
+---
+
+## Testing User Interactions
+
+Always prefer `userEvent` over `fireEvent` for realistic interaction simulation:
+
+```typescript
+import userEvent from '@testing-library/user-event'
+
+describe('RegistrationForm', () => {
+  it('submits form with valid data', async () => {
+    const user = userEvent.setup()
+    const onSubmit = vi.fn()
+    render(<RegistrationForm onSubmit={onSubmit} />)
+
+    await user.type(screen.getByLabelText(/name/i), 'Jane Smith')
+    await user.type(screen.getByLabelText(/email/i), 'jane@example.com')
+    await user.type(screen.getByLabelText(/message/i), 'Hello!')
+    await user.click(screen.getByRole('button', { name: /submit/i }))
+
+    expect(onSubmit).toHaveBeenCalledWith({
+      name: 'Jane Smith',
+      email: 'jane@example.com',
+      message: 'Hello!',
+    })
+  })
+
+  it('shows validation errors for empty required fields', async () => {
+    const user = userEvent.setup()
+    render(<RegistrationForm onSubmit={vi.fn()} />)
+
+    // Submit empty form
+    await user.click(screen.getByRole('button', { name: /submit/i }))
+
+    expect(screen.getByText(/name is required/i)).toBeInTheDocument()
+    expect(screen.getByText(/email is required/i)).toBeInTheDocument()
+  })
+
+  it('disables submit button while loading', () => {
+    render(<RegistrationForm onSubmit={vi.fn()} isLoading={true} />)
+
+    expect(screen.getByRole('button', { name: /submit/i })).toBeDisabled()
+  })
+
+  it('clears error when user starts typing', async () => {
+    const user = userEvent.setup()
+    render(<RegistrationForm onSubmit={vi.fn()} />)
+
+    // Trigger error
+    await user.click(screen.getByRole('button', { name: /submit/i }))
+    expect(screen.getByText(/name is required/i)).toBeInTheDocument()
+
+    // Start typing to clear error
+    await user.type(screen.getByLabelText(/name/i), 'J')
+    expect(screen.queryByText(/name is required/i)).not.toBeInTheDocument()
+  })
+})
+```
+
+### Common User Interactions
+
+```typescript
+const user = userEvent.setup()
+
+// Typing
+await user.type(input, 'text')
+await user.clear(input)
+
+// Clicking
+await user.click(button)
+await user.dblClick(element)
+await user.tripleClick(element)
+
+// Keyboard
+await user.keyboard('{Enter}')
+await user.keyboard('{Escape}')
+await user.keyboard('{Tab}')
+await user.keyboard('{Shift>}{Tab}{/Shift}') // Shift+Tab
+
+// Selection
+await user.selectOptions(select, 'option-value')
+await user.deselectOptions(multiSelect, 'option-value')
+
+// Clipboard
+await user.copy()
+await user.paste()
+
+// Hovering
+await user.hover(element)
+await user.unhover(element)
+
+// File upload
+const file = new File(['content'], 'file.png', { type: 'image/png' })
+await user.upload(fileInput, file)
+
+// Pointer (advanced)
+await user.pointer({ keys: '[MouseLeft]', target: element })
+```
+
+---
+
+## Testing Async Behavior
+
+```typescript
+import { render, screen, waitFor, waitForElementToBeRemoved } from '{{componentTestLib}}'
+
+describe('DataList', () => {
+  it('shows loading state then data', async () => {
+    render(<DataList />)
+
+    // Loading state
+    expect(screen.getByTestId('loading-skeleton')).toBeInTheDocument()
+
+    // Wait for data
+    await waitFor(() => {
+      expect(screen.getByText('Item 1')).toBeInTheDocument()
+    })
+
+    // Loading gone
+    expect(screen.queryByTestId('loading-skeleton')).not.toBeInTheDocument()
+  })
+
+  it('shows error state on fetch failure', async () => {
+    // Mock failed fetch
+    server.use(
+      rest.get('/api/items', (req, res, ctx) => {
+        return res(ctx.status(500))
+      })
+    )
+
+    render(<DataList />)
+
+    await waitFor(() => {
+      expect(screen.getByText(/failed to load/i)).toBeInTheDocument()
+    })
+  })
+
+  it('shows empty state when no data', async () => {
+    server.use(
+      rest.get('/api/items', (req, res, ctx) => {
+        return res(ctx.json([]))
+      })
+    )
+
+    render(<DataList />)
+
+    await waitFor(() => {
+      expect(screen.getByText(/no items yet/i)).toBeInTheDocument()
+    })
+  })
+
+  it('can retry after error', async () => {
+    let callCount = 0
+    server.use(
+      rest.get('/api/items', (req, res, ctx) => {
+        callCount++
+        if (callCount === 1) return res(ctx.status(500))
+        return res(ctx.json([{ id: '1', name: 'Item 1' }]))
+      })
+    )
+
+    const user = userEvent.setup()
+    render(<DataList />)
+
+    await waitFor(() => {
+      expect(screen.getByText(/failed to load/i)).toBeInTheDocument()
+    })
+
+    await user.click(screen.getByRole('button', { name: /retry/i }))
+
+    await waitFor(() => {
+      expect(screen.getByText('Item 1')).toBeInTheDocument()
+    })
+  })
+})
+```
+
+### waitFor Best Practices
+
+```typescript
+// GOOD - Single assertion inside waitFor
+await waitFor(() => {
+  expect(screen.getByText('Data loaded')).toBeInTheDocument()
+})
+
+// BAD - Multiple assertions inside waitFor (only last one matters for retry)
+await waitFor(() => {
+  expect(screen.getByText('Header')).toBeInTheDocument()
+  expect(screen.getByText('Data loaded')).toBeInTheDocument()
+})
+
+// GOOD - Use findBy for single async element (shorthand for waitFor + getBy)
+const element = await screen.findByText('Data loaded')
+expect(element).toBeInTheDocument()
+
+// GOOD - waitForElementToBeRemoved for disappearing elements
+await waitForElementToBeRemoved(() => screen.queryByTestId('spinner'))
+```
+
+---
+
+## Testing with Providers
+
+Create a custom render function that wraps components in required providers:
+
+```typescript
+// test-utils.tsx
+import { render as rtlRender, RenderOptions } from '{{componentTestLib}}'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { ThemeProvider } from '{{srcAlias}}lib/providers/ThemeProvider'
+
+const createTestQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false },
+    },
+  })
+
+interface CustomRenderOptions extends RenderOptions {
+  queryClient?: QueryClient
+  theme?: 'light' | 'dark'
+}
+
+function AllProviders({
+  children,
+  queryClient,
+  theme = 'light',
+}: {
+  children: React.ReactNode
+  queryClient: QueryClient
+  theme?: string
+}) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider defaultTheme={theme}>
+        {children}
+      </ThemeProvider>
+    </QueryClientProvider>
+  )
+}
+
+export function render(
+  ui: React.ReactElement,
+  options?: CustomRenderOptions
+) {
+  const queryClient = options?.queryClient ?? createTestQueryClient()
+  const theme = options?.theme ?? 'light'
+
+  return rtlRender(ui, {
+    wrapper: ({ children }) => (
+      <AllProviders queryClient={queryClient} theme={theme}>
+        {children}
+      </AllProviders>
+    ),
+    ...options,
+  })
+}
+
+// Re-export everything from testing-library
+export * from '{{componentTestLib}}'
+export { default as userEvent } from '@testing-library/user-event'
+
+// Usage in tests:
+import { render, screen, userEvent } from './test-utils'
+
+it('renders with providers', () => {
+  render(<Dashboard />)
+  // Component has access to query client, theme, etc.
+})
+```
+
+---
+
+## Testing Modals/Dialogs
+
+```typescript
+describe('ConfirmDialog', () => {
+  it('renders when open', () => {
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Delete Item"
+        message="Are you sure?"
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+      />
+    )
+
+    expect(screen.getByRole('dialog')).toBeInTheDocument()
+    expect(screen.getByText('Delete Item')).toBeInTheDocument()
+    expect(screen.getByText('Are you sure?')).toBeInTheDocument()
+  })
+
+  it('does not render when closed', () => {
+    render(
+      <ConfirmDialog
+        isOpen={false}
+        title="Delete Item"
+        message="Are you sure?"
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+      />
+    )
+
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('calls onConfirm when confirm button clicked', async () => {
+    const user = userEvent.setup()
+    const onConfirm = vi.fn()
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Delete"
+        message="Sure?"
+        onConfirm={onConfirm}
+        onCancel={vi.fn()}
+      />
+    )
+
+    await user.click(screen.getByRole('button', { name: /confirm/i }))
+
+    expect(onConfirm).toHaveBeenCalledOnce()
+  })
+
+  it('calls onCancel when cancel button clicked', async () => {
+    const user = userEvent.setup()
+    const onCancel = vi.fn()
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Delete"
+        message="Sure?"
+        onConfirm={vi.fn()}
+        onCancel={onCancel}
+      />
+    )
+
+    await user.click(screen.getByRole('button', { name: /cancel/i }))
+
+    expect(onCancel).toHaveBeenCalledOnce()
+  })
+
+  it('traps focus within modal', async () => {
+    const user = userEvent.setup()
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Delete"
+        message="Sure?"
+        onConfirm={vi.fn()}
+        onCancel={vi.fn()}
+      />
+    )
+
+    const cancelBtn = screen.getByRole('button', { name: /cancel/i })
+    const confirmBtn = screen.getByRole('button', { name: /confirm/i })
+
+    // Focus should be on first focusable element
+    expect(cancelBtn).toHaveFocus()
+
+    // Tab should cycle through modal elements
+    await user.tab()
+    expect(confirmBtn).toHaveFocus()
+
+    await user.tab()
+    expect(cancelBtn).toHaveFocus() // Wraps back
+  })
+
+  it('closes on escape key', async () => {
+    const user = userEvent.setup()
+    const onCancel = vi.fn()
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Delete"
+        message="Sure?"
+        onConfirm={vi.fn()}
+        onCancel={onCancel}
+      />
+    )
+
+    await user.keyboard('{Escape}')
+
+    expect(onCancel).toHaveBeenCalled()
+  })
+
+  it('closes on backdrop click', async () => {
+    const user = userEvent.setup()
+    const onCancel = vi.fn()
+    render(
+      <ConfirmDialog
+        isOpen={true}
+        title="Delete"
+        message="Sure?"
+        onConfirm={vi.fn()}
+        onCancel={onCancel}
+      />
+    )
+
+    // Click the backdrop (outside the dialog content)
+    await user.click(screen.getByTestId('dialog-backdrop'))
+
+    expect(onCancel).toHaveBeenCalled()
+  })
+})
+```
+
+---
+
+## Testing Accessibility
+
+```typescript
+import { axe, toHaveNoViolations } from 'jest-axe'
+
+expect.extend(toHaveNoViolations)
+
+describe('Form Accessibility', () => {
+  it('has no accessibility violations', async () => {
+    const { container } = render(<RegistrationForm onSubmit={vi.fn()} />)
+
+    const results = await axe(container)
+
+    expect(results).toHaveNoViolations()
+  })
+
+  it('associates labels with inputs', () => {
+    render(<RegistrationForm onSubmit={vi.fn()} />)
+
+    const emailInput = screen.getByLabelText(/email/i)
+    expect(emailInput).toHaveAttribute('id')
+    expect(emailInput.tagName.toLowerCase()).toBe('input')
+  })
+
+  it('has proper ARIA attributes on errors', async () => {
+    const user = userEvent.setup()
+    render(<RegistrationForm onSubmit={vi.fn()} />)
+
+    await user.click(screen.getByRole('button', { name: /submit/i }))
+
+    const emailInput = screen.getByLabelText(/email/i)
+    expect(emailInput).toHaveAttribute('aria-invalid', 'true')
+    expect(emailInput).toHaveAttribute('aria-describedby')
+  })
+
+  it('marks required fields with aria-required', () => {
+    render(<RegistrationForm onSubmit={vi.fn()} />)
+
+    expect(screen.getByLabelText(/name/i)).toHaveAttribute('aria-required', 'true')
+    expect(screen.getByLabelText(/email/i)).toHaveAttribute('aria-required', 'true')
+  })
+
+  it('uses proper heading hierarchy', () => {
+    render(<Dashboard />)
+
+    const headings = screen.getAllByRole('heading')
+    // First heading should be h1
+    expect(headings[0]).toHaveAttribute('level') // or check tagName
+  })
+
+  it('provides alt text for images', () => {
+    render(<UserProfile user={mockUser} />)
+
+    const avatar = screen.getByRole('img', { name: /profile photo/i })
+    expect(avatar).toHaveAttribute('alt')
+    expect(avatar.getAttribute('alt')).not.toBe('')
+  })
+})
+```
+
+---
+
+## Testing Hooks in Components
+
+When a hook is too complex to test with `renderHook` alone, test it through a simple test component:
+
+```typescript
+describe('useLocalStorage', () => {
+  it('persists value to localStorage', () => {
+    function TestComponent() {
+      const [value, setValue] = useLocalStorage('test-key', 'default')
+      return (
+        <div>
+          <span data-testid="value">{value}</span>
+          <button onClick={() => setValue('updated')}>Update</button>
+        </div>
+      )
+    }
+
+    render(<TestComponent />)
+
+    expect(screen.getByTestId('value')).toHaveTextContent('default')
+
+    fireEvent.click(screen.getByRole('button'))
+
+    expect(screen.getByTestId('value')).toHaveTextContent('updated')
+    expect(localStorage.getItem('test-key')).toBe('"updated"')
+  })
+
+  it('reads initial value from localStorage', () => {
+    localStorage.setItem('test-key', '"persisted"')
+
+    function TestComponent() {
+      const [value] = useLocalStorage('test-key', 'default')
+      return <span data-testid="value">{value}</span>
+    }
+
+    render(<TestComponent />)
+
+    expect(screen.getByTestId('value')).toHaveTextContent('persisted')
+  })
+})
+```
+
+---
+
+## Testing Conditional Rendering
+
+```typescript
+describe('StatusMessage', () => {
+  it('renders success variant', () => {
+    render(<StatusMessage type="success" message="Done!" />)
+
+    const el = screen.getByText('Done!')
+    expect(el).toBeInTheDocument()
+    expect(el).toHaveClass('status-success')
+  })
+
+  it('renders error variant with retry button', () => {
+    render(<StatusMessage type="error" message="Failed" onRetry={vi.fn()} />)
+
+    expect(screen.getByText('Failed')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
+  })
+
+  it('does not render retry button for success', () => {
+    render(<StatusMessage type="success" message="Done!" onRetry={vi.fn()} />)
+
+    expect(screen.queryByRole('button', { name: /retry/i })).not.toBeInTheDocument()
+  })
+
+  it('renders nothing when message is empty', () => {
+    const { container } = render(<StatusMessage type="info" message="" />)
+
+    expect(container.firstChild).toBeNull()
+  })
+})
+```
+
+---
+
+## Testing Lists and Iteration
+
+```typescript
+describe('ItemList', () => {
+  const items = [
+    { id: '1', name: 'Alpha', status: 'active' },
+    { id: '2', name: 'Beta', status: 'inactive' },
+    { id: '3', name: 'Gamma', status: 'active' },
+  ]
+
+  it('renders all items', () => {
+    render(<ItemList items={items} />)
+
+    expect(screen.getAllByRole('listitem')).toHaveLength(3)
+    expect(screen.getByText('Alpha')).toBeInTheDocument()
+    expect(screen.getByText('Beta')).toBeInTheDocument()
+    expect(screen.getByText('Gamma')).toBeInTheDocument()
+  })
+
+  it('renders empty state when no items', () => {
+    render(<ItemList items={[]} />)
+
+    expect(screen.queryAllByRole('listitem')).toHaveLength(0)
+    expect(screen.getByText(/no items/i)).toBeInTheDocument()
+  })
+
+  it('applies correct styles based on status', () => {
+    render(<ItemList items={items} />)
+
+    const activeItems = screen.getAllByTestId('status-active')
+    expect(activeItems).toHaveLength(2)
+  })
+})
+```
+
+---
+
+## Snapshot Testing
+
+Use snapshots sparingly -- prefer explicit assertions. Good for detecting unintended UI changes:
+
+```typescript
+describe('StatusBadge Snapshots', () => {
+  it('matches snapshot for each status', () => {
+    const statuses = ['active', 'inactive', 'pending'] as const
+
+    statuses.forEach(status => {
+      const { container } = render(<StatusBadge status={status} />)
+      expect(container).toMatchSnapshot()
+    })
+  })
+
+  // Inline snapshots for small components
+  it('matches inline snapshot', () => {
+    const { container } = render(<StatusBadge status="active" />)
+
+    expect(container.innerHTML).toMatchInlineSnapshot(
+      `"<span class=\"badge badge-active\">Active</span>"`
+    )
+  })
+})
+```
+
+**When to use snapshots:**
+- Small, presentational components with stable output
+- Detecting unintended changes in rendered HTML
+- NOT for components with dynamic content (dates, random IDs)
+
+**When NOT to use snapshots:**
+- Large components (snapshots become unreadable)
+- Components with frequently changing markup
+- As the only test for a component (combine with behavior tests)
+
+---
+
+## React Native Testing (Expo / React Native)
+
+> This section applies when `{{framework}}` is `react-native` or when the project uses Expo.
+
+### Setup
+
+```typescript
+// jest.setup.ts (or vitest setup)
+import '@testing-library/react-native/extend-expect'
+
+// Mock native modules that don't work in test environment
+vi.mock('expo-haptics', () => ({
+  impactAsync: vi.fn(),
+  notificationAsync: vi.fn(),
+  selectionAsync: vi.fn(),
+  ImpactFeedbackStyle: { Light: 'light', Medium: 'medium', Heavy: 'heavy' },
+  NotificationFeedbackType: { Success: 'success', Warning: 'warning', Error: 'error' },
+}))
+
+vi.mock('expo-image-picker', () => ({
+  launchImageLibraryAsync: vi.fn().mockResolvedValue({
+    canceled: false,
+    assets: [{ uri: 'file:///mock/image.jpg', width: 100, height: 100 }],
+  }),
+  launchCameraAsync: vi.fn().mockResolvedValue({
+    canceled: false,
+    assets: [{ uri: 'file:///mock/photo.jpg', width: 100, height: 100 }],
+  }),
+  MediaTypeOptions: { Images: 'images', Videos: 'videos', All: 'all' },
+}))
+
+vi.mock('expo-linking', () => ({
+  openURL: vi.fn(),
+  createURL: vi.fn((path: string) => `exp://localhost:8081/${path}`),
+}))
+
+vi.mock('expo-router', () => ({
+  useRouter: vi.fn(() => ({
+    push: vi.fn(),
+    replace: vi.fn(),
+    back: vi.fn(),
+  })),
+  useLocalSearchParams: vi.fn(() => ({})),
+  useSegments: vi.fn(() => []),
+  Link: ({ children }: any) => children,
+}))
+
+vi.mock('expo-secure-store', () => ({
+  getItemAsync: vi.fn(),
+  setItemAsync: vi.fn(),
+  deleteItemAsync: vi.fn(),
+}))
+
+// Mock native animated helper to avoid warnings
+vi.mock('react-native/Libraries/Animated/NativeAnimatedHelper')
+```
+
+### React Native Component Test
+
+```typescript
+// components/__tests__/ProfileCard.test.tsx
+import { render, screen, fireEvent, waitFor } from '@testing-library/react-native'
+import { describe, it, expect, vi } from '{{testRunner}}'
+import { ProfileCard } from '../ProfileCard'
+
+describe('ProfileCard', () => {
+  const mockProfile = {
+    id: '1',
+    name: 'Jane Smith',
+    phone: '555-123-4567',
+    status: 'ACTIVE' as const,
+  }
+
+  it('renders profile name and phone', () => {
+    render(<ProfileCard profile={mockProfile} onPress={vi.fn()} />)
+
+    expect(screen.getByText('Jane Smith')).toBeTruthy()
+    expect(screen.getByText('555-123-4567')).toBeTruthy()
+  })
+
+  it('calls onPress with profile id when tapped', () => {
+    const onPress = vi.fn()
+    render(<ProfileCard profile={mockProfile} onPress={onPress} />)
+
+    fireEvent.press(screen.getByText('Jane Smith'))
+
+    expect(onPress).toHaveBeenCalledWith('1')
+  })
+
+  it('shows status badge with correct text', () => {
+    render(<ProfileCard profile={mockProfile} onPress={vi.fn()} />)
+
+    expect(screen.getByText('ACTIVE')).toBeTruthy()
+  })
+
+  it('renders placeholder when image fails to load', () => {
+    render(<ProfileCard profile={{ ...mockProfile, avatarUrl: 'broken' }} onPress={vi.fn()} />)
+
+    // Should fall back to initials or placeholder
+    expect(screen.getByText('JS')).toBeTruthy() // Initials
+  })
+})
+```
+
+### Testing Expo Router Navigation
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react-native'
+import { useRouter } from 'expo-router'
+import { describe, it, expect, vi } from '{{testRunner}}'
+import { ItemListScreen } from '../ItemListScreen'
+
+describe('ItemListScreen navigation', () => {
+  it('navigates to detail screen on item tap', () => {
+    const mockPush = vi.fn()
+    vi.mocked(useRouter).mockReturnValue({
+      push: mockPush,
+      replace: vi.fn(),
+      back: vi.fn(),
+    } as any)
+
+    render(<ItemListScreen />)
+
+    fireEvent.press(screen.getByText('Jane Smith'))
+
+    expect(mockPush).toHaveBeenCalledWith('/items/1')
+  })
+
+  it('navigates to create screen on add button tap', () => {
+    const mockPush = vi.fn()
+    vi.mocked(useRouter).mockReturnValue({
+      push: mockPush,
+      replace: vi.fn(),
+      back: vi.fn(),
+    } as any)
+
+    render(<ItemListScreen />)
+
+    fireEvent.press(screen.getByTestId('add-button'))
+
+    expect(mockPush).toHaveBeenCalledWith('/items/new')
+  })
+})
+```
+
+### React Native Query Priority
+
+| Priority | Query | Use When |
+|----------|-------|----------|
+| 1 | `getByText` | Visible text content |
+| 2 | `getByRole` | Accessibility role set on component |
+| 3 | `getByLabelText` | Accessible label (accessibilityLabel) |
+| 4 | `getByPlaceholderText` | Input placeholders |
+| 5 | `getByTestId` | Last resort (testID prop) |
+
+**Key differences from web:**
+- React Native does not have DOM concepts like `getByClassName`
+- Use `fireEvent.press` instead of `fireEvent.click`
+- Use `toBeTruthy()` instead of `toBeInTheDocument()` (unless using extend-expect)
+- `testID` prop (camelCase) maps to `getByTestId`
+
+### Mocking Native Modules
+
+For any Expo/RN module that uses native code:
+
+```typescript
+// Mock audio/video
+vi.mock('expo-av', () => ({
+  Audio: {
+    Sound: {
+      createAsync: vi.fn().mockResolvedValue({
+        sound: { playAsync: vi.fn(), unloadAsync: vi.fn() },
+        status: { isLoaded: true },
+      }),
+    },
+  },
+}))
+
+// Mock Dimensions for responsive tests
+vi.mock('react-native', async () => {
+  const actual = await vi.importActual('react-native')
+  return {
+    ...actual,
+    Dimensions: {
+      get: vi.fn().mockReturnValue({ width: 375, height: 812 }),
+      addEventListener: vi.fn(),
+    },
+  }
+})
+
+// Mock camera
+vi.mock('expo-camera', () => ({
+  Camera: {
+    requestCameraPermissionsAsync: vi.fn().mockResolvedValue({ status: 'granted' }),
+  },
+  CameraView: ({ children }: any) => children,
+}))
+
+// Mock location
+vi.mock('expo-location', () => ({
+  requestForegroundPermissionsAsync: vi.fn().mockResolvedValue({ status: 'granted' }),
+  getCurrentPositionAsync: vi.fn().mockResolvedValue({
+    coords: { latitude: 37.7749, longitude: -122.4194 },
+  }),
+}))
+```
+
+### Testing React Native Animations
+
+```typescript
+import { Animated } from 'react-native'
+
+describe('AnimatedCard', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('fades in on mount', () => {
+    const spy = vi.spyOn(Animated, 'timing')
+    render(<AnimatedCard />)
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.objectContaining({ toValue: 1, duration: 300 })
+    )
+  })
+})
+```
+
+---
+
+## Testing Responsive Behavior (Web)
+
+```typescript
+describe('Navigation', () => {
+  it('shows hamburger menu on small screens', () => {
+    // Set viewport width
+    Object.defineProperty(window, 'innerWidth', { value: 375, writable: true })
+    window.dispatchEvent(new Event('resize'))
+
+    render(<Navigation />)
+
+    expect(screen.getByTestId('hamburger-button')).toBeInTheDocument()
+    expect(screen.queryByTestId('desktop-nav')).not.toBeInTheDocument()
+  })
+
+  it('shows full nav on desktop', () => {
+    Object.defineProperty(window, 'innerWidth', { value: 1280, writable: true })
+    window.dispatchEvent(new Event('resize'))
+
+    render(<Navigation />)
+
+    expect(screen.queryByTestId('hamburger-button')).not.toBeInTheDocument()
+    expect(screen.getByTestId('desktop-nav')).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Checklist
+
+Before submitting component tests:
+
+- [ ] Uses semantic queries (getByRole, getByLabelText first)
+- [ ] Tests user interactions with userEvent (not fireEvent where possible)
+- [ ] Tests loading state
+- [ ] Tests error state
+- [ ] Tests empty state
+- [ ] Tests accessibility (a11y violations)
+- [ ] Avoids testing implementation details (no internal state, no className)
+- [ ] Mock functions verified with correct arguments
+- [ ] Async behavior tested with waitFor/findBy
+- [ ] No direct DOM queries (no querySelector)
+- [ ] Providers wrapped via test-utils render
+- [ ] For RN: Uses fireEvent.press, not fireEvent.click
+- [ ] For RN: Mocks native modules in setup file
+
+---
+
+## Running Component Tests
+
+```bash
+# Run all component tests
+{{testCommand}}
+
+# Run specific component tests
+{{testCommand}} ItemCard.test.tsx
+
+# Run with coverage
+{{testCommand}} --coverage
+
+# Run in watch mode
+{{testCommand}} --watch
+
+# Run tests matching a pattern
+{{testCommand}} --testNamePattern="submits form"
+```
+
+---
+
+## See Also
+
+- `unit-test.md` - Unit testing patterns
+- `e2e-test.md` - End-to-end testing patterns
+- `test-standards.md` - Coverage thresholds and test type requirements