@jmruthers/pace-core 0.6.9 → 0.6.11

package/docs/testing/test-setup-for-consumers.md

@@ -0,0 +1,916 @@
+---
+lastUpdated: 2025-01-20T00:00:00+11:00
+version: 0.6.9
+reviewedBy: documentation-standards-audit
+---
+
+# Test Infrastructure Setup Guide
+
+This guide will help you set up test infrastructure in your consuming app to match the pace-core testing setup. After following this guide, you'll be able to run `npm run test:coverage` and receive the same comprehensive coverage reports as pace-core.
+
+## Overview
+
+This setup provides:
+- **Vitest** as the test runner
+- **React Testing Library** for component testing
+- **Coverage reporting** with v8 provider (text, JSON, and HTML reports)
+- **Proper test isolation** and cleanup
+- **Mock utilities** for pace-core providers
+- **Consistent test configuration** matching pace-core standards
+
+**Test colocation:** pace-core colocates test files with source files (e.g. `Component.test.tsx` next to `Component.tsx`). Consumers should follow the same pattern per the project structure standard; do not use a dedicated `__tests__/` or `tests/` folder for unit/integration tests. Shared test helpers may live in a single location (e.g. `src/__tests__/helpers`) if needed.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- Your app already has `@jmruthers/pace-core` installed
+- TypeScript configured (if using TypeScript)
+
+## Step 1: Install Dependencies
+
+Install the required testing dependencies:
+
+```bash
+npm install --save-dev \
+  vitest@^4.0.16 \
+  @vitest/coverage-v8@^4.0.16 \
+  @vitejs/plugin-react@^5.1.2 \
+  @testing-library/react@^16.3.0 \
+  @testing-library/jest-dom@^6.6.3 \
+  @testing-library/user-event@^14.6.1 \
+  happy-dom@^20.0.0 \
+  cross-env@^10.1.0
+```
+
+**Optional but recommended:**
+```bash
+npm install --save-dev \
+  jest-axe@^10.0.0 \
+  @types/jest-axe@^3.5.9
+```
+
+## Step 2: Create Vitest Configuration
+
+Create a `vitest.config.ts` file in your project root:
+
+```typescript
+/// <reference types="vitest" />
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+import { config } from 'dotenv';
+import { existsSync } from 'fs';
+import { createRequire } from 'module';
+
+// Load .env if it exists
+if (existsSync(path.resolve(__dirname, '.env'))) {
+  config({ path: path.resolve(__dirname, '.env') });
+}
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: (() => {
+          const require = createRequire(import.meta.url);
+
+          try {
+            return [require('babel-plugin-react-compiler')];
+          } catch (error) {
+            // Optional dependency - continue without it
+            return [];
+          }
+        })(),
+      },
+    }),
+  ],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: [path.resolve(__dirname, './vitest.setup.ts')],
+    globalTeardown: path.resolve(__dirname, './vitest.teardown.ts'),
+    testTimeout: 30000, // 30 seconds
+    pool: 'threads',
+    threads: {
+      singleThread: false,
+      maxThreads: 4,
+      minThreads: 1,
+      isolate: true,
+      useAtomics: false,
+    },
+    bail: 0,
+    watch: false,
+    isolate: true,
+    sequence: {
+      concurrent: false,
+      shuffle: false,
+    },
+    forceRerunTriggers: ['**/package.json/**', '**/vitest.config.*/**'],
+    passWithNoTests: true,
+    include: [
+      'src/**/*.{test,spec}.{ts,tsx}',
+      'tests/**/*.{test,spec}.{ts,tsx}',
+    ],
+    exclude: [
+      'node_modules',
+      'dist',
+      'build',
+      '**/*.d.ts',
+      'coverage',
+      '**/*.template.{ts,tsx}',
+    ],
+    reporters: ['verbose'],
+    hookTimeout: 5000,
+    teardownTimeout: 5000,
+    restoreMocks: true,
+    clearMocks: true,
+    unstubEnvs: false,
+    unstubGlobals: false,
+    fileParallelism: true,
+    logHeapUsage: true,
+    silent: false,
+    retry: 0,
+    maxConcurrency: 4,
+    
+    // Coverage configuration
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      reportsDirectory: path.resolve(__dirname, './coverage'),
+      include: [
+        'src/**/*.{ts,tsx}',
+      ],
+      exclude: [
+        '**/*.d.ts',
+        '**/*.test.{ts,tsx}',
+        '**/*.spec.{ts,tsx}',
+        '**/__tests__/**',
+        '**/__mocks__/**',
+        '**/*.example.{ts,tsx}',
+        '**/scripts/**',
+        '**/tests/**',
+      ],
+      thresholds: {
+        lines: 80,
+        branches: 80,
+        functions: 80,
+        statements: 80,
+      },
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+      // Add your app-specific aliases here
+    },
+  },
+  define: {
+    'process.env.NODE_ENV': '"test"',
+    'import.meta.env.MODE': '"development"',
+    'import.meta.env.DEV': 'true',
+    'import.meta.env.PROD': 'false',
+    'global': 'globalThis',
+    'process': 'process',
+  },
+  esbuild: {
+    jsx: 'automatic',
+    target: 'es2020',
+  },
+  optimizeDeps: {
+    include: [
+      'react',
+      'react-dom',
+      '@testing-library/react',
+      '@testing-library/jest-dom',
+      '@tanstack/react-query',
+      '@supabase/supabase-js',
+    ],
+  },
+});
+```
+
+**Note:** If you're using a monorepo or have a different project structure, adjust the `include` and `exclude` paths accordingly.
+
+## Step 3: Create Test Setup File
+
+Create a `vitest.setup.ts` file in your project root:
+
+```typescript
+import { vi } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import React from 'react';
+
+// ========================================
+// GLOBAL MOCKS - MUST BE DEFINED FIRST
+// ========================================
+
+// CRITICAL: Ensure process is available globally before any other imports
+const processPolyfill = {
+  env: { NODE_ENV: 'test' },
+  exit: vi.fn((code = 0) => {
+    processPolyfill.exitCode = code;
+  }),
+  exitCode: 0,
+  version: 'v18.0.0',
+  platform: 'test',
+  cwd: () => '/test',
+  on: vi.fn(),
+  off: vi.fn(),
+  emit: vi.fn(),
+  listeners: vi.fn(() => []),
+  listenerCount: vi.fn(() => 0),
+  removeListener: vi.fn(),
+  removeAllListeners: vi.fn(),
+  setMaxListeners: vi.fn(),
+  getMaxListeners: vi.fn(() => 10),
+  nextTick: vi.fn((cb) => setTimeout(cb, 0)),
+  stdout: { write: vi.fn() },
+  stderr: { write: vi.fn() },
+  stdin: { read: vi.fn() },
+  argv: ['node', 'test'],
+  pid: 12345,
+  ppid: 12344,
+  title: 'node',
+  arch: 'x64',
+  memoryUsage: vi.fn(() => ({ rss: 0, heapTotal: 0, heapUsed: 0, external: 0 })),
+  uptime: vi.fn(() => 0),
+  hrtime: vi.fn(() => [0, 0]),
+  kill: vi.fn(),
+  chdir: vi.fn(),
+  umask: vi.fn(),
+  getuid: vi.fn(() => 1000),
+  getgid: vi.fn(() => 1000),
+  setuid: vi.fn(),
+  setgid: vi.fn(),
+  binding: vi.fn(),
+  _fatalException: vi.fn(),
+  workerOnGlobalUncaughtException: vi.fn(),
+  uncaughtException: vi.fn(),
+  unhandledRejection: vi.fn(),
+  get exitCode() { return this._exitCode || 0; },
+  set exitCode(value) { this._exitCode = value; },
+  _exitCode: 0,
+};
+
+// Apply to all possible global contexts
+if (typeof globalThis.process === 'undefined') {
+  globalThis.process = processPolyfill;
+}
+if (typeof global.process === 'undefined') {
+  (global as any).process = processPolyfill;
+}
+if (typeof window !== 'undefined' && typeof (window as any).process === 'undefined') {
+  (window as any).process = processPolyfill;
+}
+
+Object.defineProperty(globalThis, 'process', {
+  value: processPolyfill,
+  writable: true,
+  configurable: true,
+});
+
+Object.defineProperty(global, 'process', {
+  value: processPolyfill,
+  writable: true,
+  configurable: true,
+});
+
+if (typeof process !== 'undefined') {
+  Object.keys(processPolyfill).forEach(key => {
+    if (!(key in process) || process[key] === undefined) {
+      try {
+        (process as any)[key] = (processPolyfill as any)[key];
+      } catch (e) {
+        // Skip read-only properties
+      }
+    }
+  });
+}
+
+if (typeof process !== 'undefined') {
+  if (!('exitCode' in process)) {
+    Object.defineProperty(process, 'exitCode', {
+      value: 0,
+      writable: true,
+      configurable: true,
+    });
+  }
+}
+
+// Store original process.exit for use in teardown
+if (typeof process !== 'undefined' && process.exit) {
+  const originalExit = process.exit.bind(process);
+  
+  if (typeof globalThis !== 'undefined') {
+    (globalThis as any).__vitest_original_exit__ = originalExit;
+  }
+  
+  process.exit = (code = process.exitCode || 0) => {
+    process.exitCode = code;
+    return;
+  };
+}
+
+// Suppress specific Vitest process errors
+const originalConsoleError = console.error;
+console.error = (...args) => {
+  const message = args[0];
+  if (typeof message === 'string' && message.includes('process is not defined')) {
+    return;
+  }
+  originalConsoleError(...args);
+};
+
+// Global test cleanup
+afterEach(() => {
+  const navigatorMock = {
+    clipboard: {
+      writeText: vi.fn(),
+      readText: vi.fn(),
+    },
+  };
+  
+  if (typeof globalThis !== 'undefined') {
+    Object.defineProperty(globalThis, 'navigator', {
+      value: navigatorMock,
+      writable: true,
+      configurable: true,
+    });
+  }
+  
+  if (typeof window !== 'undefined') {
+    Object.defineProperty(window, 'navigator', {
+      value: navigatorMock,
+      writable: true,
+      configurable: true,
+    });
+  }
+  
+  cleanup();
+  vi.clearAllMocks();
+  
+  // Re-ensure navigator after clearing mocks
+  if (typeof globalThis !== 'undefined') {
+    Object.defineProperty(globalThis, 'navigator', {
+      value: navigatorMock,
+      writable: true,
+      configurable: true,
+    });
+  }
+  
+  if (typeof window !== 'undefined') {
+    Object.defineProperty(window, 'navigator', {
+      value: navigatorMock,
+      writable: true,
+      configurable: true,
+    });
+  }
+  
+  vi.clearAllTimers();
+  if (vi.isFakeTimers()) {
+    vi.useRealTimers();
+  }
+  
+  if (typeof localStorage !== 'undefined') {
+    localStorage.clear();
+  }
+  if (typeof sessionStorage !== 'undefined') {
+    sessionStorage.clear();
+  }
+  
+  if (typeof document !== 'undefined' && document.body) {
+    document.body.innerHTML = '';
+  }
+});
+
+beforeAll(() => {
+  // Mock navigator for userEvent
+  if (typeof globalThis !== 'undefined' && !globalThis.navigator) {
+    Object.defineProperty(globalThis, 'navigator', {
+      value: {
+        clipboard: {
+          writeText: vi.fn(),
+          readText: vi.fn(),
+        },
+      },
+      writable: true,
+      configurable: true,
+    });
+  }
+  if (typeof window !== 'undefined' && !window.navigator) {
+    Object.defineProperty(window, 'navigator', {
+      value: {
+        clipboard: {
+          writeText: vi.fn(),
+          readText: vi.fn(),
+        },
+      },
+      writable: true,
+      configurable: true,
+    });
+  }
+
+  // Mock IntersectionObserver
+  global.IntersectionObserver = class IntersectionObserver {
+    observe = vi.fn();
+    unobserve = vi.fn();
+    disconnect = vi.fn();
+    takeRecords = vi.fn(() => []);
+    root = null;
+    rootMargin = '';
+    thresholds = [];
+    
+    constructor(callback: any, options?: any) {
+      // Constructor does nothing in mock
+    }
+  } as any;
+
+  // Mock ResizeObserver
+  global.ResizeObserver = class ResizeObserver {
+    observe = vi.fn();
+    unobserve = vi.fn();
+    disconnect = vi.fn();
+    
+    constructor(callback: any) {
+      // Constructor does nothing in mock
+    }
+  } as any;
+
+  // Mock requestAnimationFrame
+  global.requestAnimationFrame = vi.fn((callback: FrameRequestCallback) => {
+    callback(performance.now());
+    return 1;
+  }) as any;
+  
+  global.cancelAnimationFrame = vi.fn(() => {}) as any;
+});
+
+afterAll(() => {
+  vi.clearAllMocks();
+  vi.clearAllTimers();
+});
+
+// Mock pace-core RBAC hooks
+vi.mock('@jmruthers/pace-core/rbac', () => ({
+  usePermissions: () => ({
+    permissions: [],
+    isLoading: false,
+    error: null,
+    hasPermission: () => true,
+    hasAnyPermission: () => true,
+    hasAllPermissions: () => true,
+    refetch: vi.fn(),
+  }),
+  useCan: () => ({
+    hasPermission: () => true,
+    isLoading: false,
+    error: null,
+  }),
+  useAccessLevel: () => ({
+    accessLevel: { level: 'admin' },
+    isLoading: false,
+    error: null,
+  }),
+  useMultiplePermissions: () => ({
+    checkPermissions: () => ({ all: true, any: true }),
+    isLoading: false,
+    error: null,
+  }),
+  useHasAnyPermission: () => ({
+    hasAnyPermission: () => true,
+    isLoading: false,
+    error: null,
+  }),
+  useHasAllPermissions: () => ({
+    hasAllPermissions: () => true,
+    isLoading: false,
+    error: null,
+  }),
+  useCachedPermissions: () => ({
+    cachedPermissions: [],
+    isLoading: false,
+    error: null,
+    invalidateCache: vi.fn(),
+    refetch: vi.fn(),
+  }),
+}));
+
+// Mock UnifiedAuthProvider
+vi.mock('@jmruthers/pace-core/providers', () => {
+  const UnifiedAuthProvider = ({ children }: any) => children;
+  const useUnifiedAuth = () => ({
+    user: { id: 'user-123', email: 'test@example.com' },
+    session: {},
+    isAuthenticated: true,
+    isLoading: false,
+    authLoading: false,
+    authError: null,
+    error: null,
+    supabase: {},
+    signIn: vi.fn(),
+    signUp: vi.fn(),
+    signOut: vi.fn(),
+    resetPassword: vi.fn(),
+    updatePassword: vi.fn(),
+    refreshSession: vi.fn(),
+    can: () => true,
+    hasRole: () => true,
+    hasPermission: () => true,
+    appName: 'Test App',
+    hasErrors: false,
+  });
+  return { UnifiedAuthProvider, useUnifiedAuth, UnifiedAuthContext: React.createContext(null) };
+});
+
+// Mock react-router-dom
+vi.mock('react-router-dom', async () => {
+  const actual = await vi.importActual('react-router-dom');
+  const mockLocation = { pathname: '/', search: '', hash: '', state: null, key: 'default' };
+  const mockNavigate = vi.fn();
+  
+  return {
+    ...actual,
+    useLocation: () => mockLocation,
+    useNavigate: () => mockNavigate,
+    useParams: () => ({}),
+    useSearchParams: () => [new URLSearchParams(), vi.fn()],
+    MemoryRouter: actual?.MemoryRouter,
+    BrowserRouter: actual?.BrowserRouter,
+    Router: actual?.Router,
+    Routes: actual?.Routes,
+    Route: actual?.Route,
+    Outlet: actual?.Outlet,
+  };
+});
+
+// Mock EventProvider
+vi.mock('@jmruthers/pace-core/providers', () => {
+  const mockEventContext = {
+    events: [],
+    selectedEvent: null,
+    isLoading: false,
+    error: null,
+    setSelectedEvent: vi.fn(),
+    refreshEvents: vi.fn(),
+  };
+
+  const EventProvider = ({ children, ...props }: any) => {
+    return React.createElement('div', { 'data-testid': 'event-provider', ...props }, children);
+  };
+  const useEvents = () => mockEventContext;
+  return {
+    EventProvider,
+    useEvents,
+  };
+});
+
+// Mock OrganisationProvider
+vi.mock('@jmruthers/pace-core/providers', () => {
+  const OrganisationProvider = ({ children }: any) => {
+    return React.createElement('div', { 'data-testid': 'organisation-provider' }, children);
+  };
+  const useOrganisations = () => ({
+    organisations: [{ id: 'org-123', name: 'Test Organisation' }],
+    selectedOrganisation: { id: 'org-123', name: 'Test Organisation' },
+    isOrganisationLoaded: true,
+    isLoading: false,
+    error: null,
+    setSelectedOrganisation: vi.fn(),
+    refreshOrganisations: vi.fn(),
+  });
+  return { OrganisationProvider, useOrganisations } as any;
+});
+
+// Mock lucide-react icons
+vi.mock('lucide-react', () => {
+  const icons = [
+    'ChevronDown', 'ChevronUp', 'ChevronLeft', 'ChevronRight',
+    'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown',
+    'Search', 'Filter', 'X', 'Plus', 'Minus', 'Edit', 'Trash2',
+    'Eye', 'EyeOff', 'Download', 'Upload', 'RefreshCw', 'Settings',
+    'User', 'Users', 'Shield', 'Check', 'AlertCircle',
+    'Info', 'Warning', 'HelpCircle', 'Calendar', 'Clock',
+    'Mail', 'Phone', 'Globe', 'Lock', 'Unlock', 'Key', 'Home',
+    'Menu', 'MoreHorizontal', 'MoreVertical', 'Star', 'Heart',
+    // Add other icons you use in your app
+  ];
+  
+  const iconMocks = icons.reduce((acc, icon) => {
+    acc[icon] = vi.fn(() => React.createElement('div', { 'data-testid': `lucide-${icon.toLowerCase()}` }));
+    return acc;
+  }, {} as Record<string, any>);
+  
+  return iconMocks;
+});
+```
+
+**Note:** You may need to adjust the mock paths based on how you import from `@jmruthers/pace-core` in your app. Check your import statements and update the mock paths accordingly.
+
+## Step 4: Create Test Teardown File
+
+Create a `vitest.teardown.ts` file in your project root:
+
+```typescript
+/**
+ * @file Vitest Global Teardown
+ * 
+ * Global teardown to ensure process exits cleanly after all tests complete.
+ * This prevents hanging when there are open handles (Supabase connections, timers, etc.)
+ */
+
+export async function teardown() {
+  // Get the original process.exit function if available
+  const originalExit = typeof globalThis !== 'undefined' 
+    ? (globalThis as any).__vitest_original_exit__
+    : undefined;
+  
+  // Force exit immediately to prevent hanging
+  // This is necessary when there are open handles (Supabase connections, etc.)
+  // that prevent Node.js from exiting naturally
+  if (typeof process !== 'undefined') {
+    // Only force exit in non-watch mode to prevent hanging
+    if (!process.env.VITEST_WATCH && process.env.CI !== 'true') {
+      // Use the original exit function if available
+      if (originalExit) {
+        // Restore the original exit function temporarily
+        const currentExit = process.exit;
+        process.exit = originalExit;
+        // Now call it
+        process.exit(0);
+      } else {
+        // Fallback: try to use process.exit directly
+        try {
+          process.exit(0);
+        } catch (e) {
+          // If that fails, use the Node.js built-in exit
+          if (typeof require !== 'undefined') {
+            require('process').exit(0);
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Step 5: Add Test Scripts to package.json
+
+Add the following scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "test": "cross-env NODE_OPTIONS=--max-old-space-size=12288 vitest run --no-coverage",
+    "test:watch": "cross-env NODE_OPTIONS=--max-old-space-size=12288 vitest --watch",
+    "test:coverage": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --coverage --reporter=verbose",
+    "test:ui": "vitest --ui"
+  }
+}
+```
+
+**Script explanations:**
+- `test` - Run all tests without coverage (faster for CI)
+- `test:watch` - Run tests in watch mode for development
+- `test:coverage` - Run tests with coverage report (matches pace-core output)
+- `test:ui` - Open Vitest UI for interactive test running
+
+## Step 6: Configure TypeScript (if using TypeScript)
+
+If you're using TypeScript, add Vitest types to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["vitest/globals", "@testing-library/jest-dom"]
+  }
+}
+```
+
+Or create a `tsconfig.test.json`:
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["vitest/globals", "@testing-library/jest-dom"]
+  },
+  "include": [
+    "src/**/*",
+    "tests/**/*",
+    "vitest.setup.ts",
+    "vitest.config.ts"
+  ]
+}
+```
+
+## Step 7: Create a Test Utilities File (Optional but Recommended)
+
+Create a `src/test-utils.tsx` file for custom render helpers:
+
+```typescript
+import { render, RenderOptions } from '@testing-library/react';
+import { ReactElement } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+
+// Create a test QueryClient with default options
+const createTestQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        cacheTime: 0,
+      },
+    },
+  });
+
+// Custom render function that includes all providers
+const AllTheProviders = ({ children }: { children: React.ReactNode }) => {
+  const queryClient = createTestQueryClient();
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        {children}
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+const customRender = (
+  ui: ReactElement,
+  options?: Omit<RenderOptions, 'wrapper'>
+) => render(ui, { wrapper: AllTheProviders, ...options });
+
+export * from '@testing-library/react';
+export { customRender as render };
+```
+
+Then use it in your tests:
+
+```typescript
+import { render, screen } from '../test-utils';
+
+describe('MyComponent', () => {
+  it('renders correctly', () => {
+    render(<MyComponent />);
+    expect(screen.getByText('Hello')).toBeInTheDocument();
+  });
+});
+```
+
+## Step 8: Add Coverage to .gitignore
+
+Add coverage directory to your `.gitignore`:
+
+```
+coverage/
+*.lcov
+```
+
+## Step 9: Verify Setup
+
+Create a simple test to verify everything works:
+
+```typescript
+// src/components/Button.test.tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Button } from '@jmruthers/pace-core';
+
+describe('Button', () => {
+  it('renders correctly', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByText('Click me')).toBeInTheDocument();
+  });
+});
+```
+
+Run the test:
+
+```bash
+npm run test
+```
+
+Then run coverage:
+
+```bash
+npm run test:coverage
+```
+
+You should see:
+1. Test execution output
+2. Coverage summary in the terminal
+3. A `coverage/` directory with:
+   - `coverage/index.html` - HTML coverage report
+   - `coverage/coverage-final.json` - JSON coverage data
+
+## Coverage Report Output
+
+When you run `npm run test:coverage`, you'll receive:
+
+### Terminal Output
+```
+✓ src/components/Button.test.tsx (1)
+  ✓ Button renders correctly
+
+Test Files  1 passed (1)
+     Tests  1 passed (1)
+      Time  2.34s
+
+% Coverage report from v8
+-------------------------------
+Statements   : 85.23% ( 234/275 )
+Branches     : 78.45% ( 123/157 )
+Functions    : 82.10% ( 92/112 )
+Lines        : 85.23% ( 234/275 )
+-------------------------------
+```
+
+### HTML Report
+Open `coverage/index.html` in your browser to see:
+- File-by-file coverage breakdown
+- Line-by-line highlighting
+- Coverage percentages per file
+- Uncovered lines highlighted
+
+### JSON Report
+The `coverage/coverage-final.json` file contains machine-readable coverage data for CI/CD integration.
+
+## Customizing Coverage Thresholds
+
+You can adjust coverage thresholds in `vitest.config.ts`:
+
+```typescript
+coverage: {
+  // ... other config
+  thresholds: {
+    lines: 80,        // Minimum line coverage
+    branches: 80,     // Minimum branch coverage
+    functions: 80,    // Minimum function coverage
+    statements: 80,   // Minimum statement coverage
+    
+    // Per-directory thresholds (optional)
+    'src/hooks/**': {
+      lines: 95,
+      branches: 95,
+      functions: 95,
+    },
+    'src/components/**': {
+      lines: 90,
+      branches: 90,
+      functions: 90,
+    },
+  },
+}
+```
+
+## Troubleshooting
+
+### Tests hang and don't exit
+- Ensure `vitest.teardown.ts` is properly configured
+- Check for open handles (Supabase connections, timers)
+- Verify `process.exit` is being called in teardown
+
+### Coverage not generating
+- Verify `@vitest/coverage-v8` is installed
+- Check that `coverage.provider` is set to `'v8'` in config
+- Ensure files are not excluded in `coverage.exclude`
+
+### Mocks not working
+- Verify mock paths match your import paths
+- Check that mocks are defined before imports in `vitest.setup.ts`
+- Ensure `vi.mock()` is called at the top level
+
+### TypeScript errors
+- Add `/// <reference types="vitest" />` to test files
+- Ensure `vitest/globals` is in `tsconfig.json` types
+- Check that `@testing-library/jest-dom` types are included
+
+### Process is not defined errors
+- Verify the process polyfill in `vitest.setup.ts` is complete
+- Check that process polyfill is applied before any other code
+
+## Next Steps
+
+1. **Write your first test** - Start with a simple component test
+2. **Set up CI/CD** - Add `npm run test:coverage` to your CI pipeline
+3. **Review coverage reports** - Use HTML reports to identify untested code
+4. **Adjust thresholds** - Set realistic coverage goals for your project
+5. **Add more mocks** - Mock any additional dependencies as needed
+
+## Additional Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [React Testing Library](https://testing-library.com/react)
+- [pace-core Testing Guide](./README.md)
+- [pace-core Testing Standards](../standards/8-testing-documentation-standards.md)
+
+## Support
+
+If you encounter issues setting up your test infrastructure:
+1. Check the troubleshooting section above
+2. Review the pace-core test setup files for reference
+3. Ensure all dependencies are installed and versions match
+4. Verify your configuration matches the examples in this guide