@jmruthers/pace-core 0.5.87 → 0.5.88

package/src/__tests__/TEST_GUIDE_CURSOR.md

@@ -1,1605 +0,0 @@
-# 🧪 Testing Guidelines & Best Practices
-
-## 📋 Table of Contents
-- [Testing Philosophy](#testing-philosophy)
-- [Test Structure](#test-structure)
-- [Naming Conventions](#naming-conventions)
-- [Test Categories](#test-categories)
-- [Best Practices](#best-practices)
-- [Common Patterns](#common-patterns)
-- [Anti-Patterns](#anti-patterns)
-- [Code Coverage](#code-coverage)
-- [Coverage Thresholds](#coverage-thresholds)
-- [RBAC Testing Patterns](#rbac-testing-patterns)
-- [Service Testing Patterns](#service-testing-patterns)
-- [DataTable Testing Patterns](#datatable-testing-patterns)
-- [PublicLayout Testing Patterns](#publiclayout-testing-patterns)
-- [Service Hook Testing Patterns](#service-hook-testing-patterns)
-
-## 🎯 Testing Philosophy
-
-### The Testing Pyramid
-```
-    /\
-   /  \     E2E Tests (Few)
-  /____\    
- /      \   Integration Tests (Some)
-/________\  
-            Unit Tests (Many)
-```
-
-### Test Principles
-1. **Fast** - Tests should run quickly
-2. **Independent** - Tests should not depend on each other
-3. **Repeatable** - Tests should produce the same results every time
-4. **Self-Validating** - Tests should have a clear pass/fail result
-5. **Timely** - Tests should be written close to the code they test
-
-## 🏗️ Test Structure
-
-### File Organization
-
-**Preferred Structure (Colocated with Source)**:
-```
-src/
-├── components/
-│   ├── Button/
-│   │   ├── Button.tsx
-│   │   └── Button.test.tsx          ✅ Colocated
-│   └── DataTable/
-│       ├── DataTable.tsx
-│       ├── DataTable.test.tsx      ✅ Colocated
-│       └── __tests__/               ✅ For integration tests
-│           └── DataTable.integration.test.tsx
-├── hooks/
-│   ├── useCounter.ts
-│   ├── useCounter.test.ts          ✅ Colocated
-│   └── useDebounce.ts
-│       └── useDebounce.test.ts     ✅ Colocated
-├── providers/
-│   ├── EventProvider.tsx
-│   └── __tests__/
-│       └── EventProvider.test.tsx  ✅ Grouped in __tests__
-└── validation/
-    ├── sanitization.ts
-    ├── sanitization.unit.test.ts  ✅ Colocated
-    └── __tests__/                 ✅ Shared test utilities
-        ├── sanitization.unit.test.ts
-        └── common.unit.test.ts
-```
-
-**When to Use `__tests__/` Subdirectory**:
-- Group multiple test files for one source file (e.g., `.test.ts`, `.integration.test.tsx`)
-- Shared test utilities within a module
-- Integration tests that span components
-
-**Central `src/__tests__/` Directory** - ONLY for:
-- Cross-module integration tests
-- Shared test utilities and fixtures
-- Test configuration files
-
-### Test Colocation Rules
-
-#### ✅ DO: Colocate Tests with Source
-```typescript
-// Component file structure
-src/components/Button/
-├── Button.tsx
-└── Button.test.tsx          ✅ Next to source
-
-// Hook file structure  
-src/hooks/
-├── useCounter.ts
-└── useCounter.test.ts       ✅ Next to source
-```
-
-#### ⚠️ MAY: Use `__tests__/` Subdirectory
-```typescript
-// When you have multiple test files for one component
-src/components/DataTable/
-├── DataTable.tsx
-└── __tests__/
-    ├── DataTable.test.tsx              ✅ Unit tests
-    └── DataTable.integration.test.tsx  ✅ Integration tests
-```
-
-#### ❌ DON'T: Duplicate Test Files
-```typescript
-// WRONG: Don't create duplicates
-src/providers/
-├── OrganisationProvider.tsx
-├── OrganisationProvider.test.tsx  ❌ Duplicate!
-└── __tests__/
-    └── OrganisationProvider.test.tsx  ❌ Duplicate!
-
-// RIGHT: Single location
-src/providers/
-├── OrganisationProvider.tsx
-└── __tests__/
-    └── OrganisationProvider.test.tsx  ✅ One location only
-```
-
-#### ❌ DON'T: Use Central `__tests__/` for Single-Module Tests
-```typescript
-// WRONG: Don't put component tests in central directory
-src/__tests__/components/Button.test.tsx  ❌ Too far from source
-
-// RIGHT: Colocate with source
-src/components/Button/Button.test.tsx  ✅ Near source
-```
-
-### Test File Naming
-- `ComponentName.test.tsx` - Component tests
-- `hookName.test.ts` - Hook tests
-- `utilityName.test.ts` - Utility tests
-- `feature.integration.test.tsx` - Integration tests
-
-## 📝 Naming Conventions
-
-### Describe Blocks
-```typescript
-describe('ComponentName', () => {
-  describe('Rendering', () => {
-    // Rendering tests
-  });
-  
-  describe('Event Handling', () => {
-    // Event tests
-  });
-  
-  describe('State Management', () => {
-    // State tests
-  });
-});
-```
-
-### Test Names
-```typescript
-// ✅ Good
-it('renders with text content', () => {});
-it('handles click events', () => {});
-it('can be disabled', () => {});
-
-// ❌ Bad
-it('works', () => {});
-it('test button', () => {});
-it('should do something', () => {});
-```
-
-## 🎭 Test Categories
-
-### 1. Unit Tests
-- Test individual functions/components in isolation
-- Fast, focused, and numerous
-- Mock all dependencies
-
-### 2. Integration Tests
-- Test how multiple units work together
-- Test data flow between components
-- Use real implementations where possible
-
-### 3. Component Tests
-- Test React components in isolation
-- Test rendering, props, events, and state
-- Use React Testing Library
-
-### 4. Hook Tests
-- Test custom hooks in isolation
-- Use `renderHook` from React Testing Library
-- Test state changes and side effects
-
-## ✅ Best Practices
-
-### 1. Test Structure (AAA Pattern)
-```typescript
-it('should increment counter when clicked', () => {
-  // Arrange
-  const { getByRole } = render(<Counter />);
-  const button = getByRole('button');
-  
-  // Act
-  fireEvent.click(button);
-  
-  // Assert
-  expect(button).toHaveTextContent('1');
-});
-```
-
-### 2. Use Semantic Queries
-```typescript
-// ✅ Good - Semantic queries
-screen.getByRole('button', { name: 'Submit' });
-screen.getByLabelText('Email address');
-screen.getByText('Welcome back');
-
-// ❌ Bad - Implementation details
-screen.getByClassName('btn-primary');
-screen.getByTestId('submit-button');
-```
-
-### 3. Test User Behavior
-```typescript
-// ✅ Good - Test what users see/do
-expect(screen.getByText('Welcome, John')).toBeInTheDocument();
-await user.click(screen.getByRole('button'));
-
-// ❌ Bad - Test implementation details
-expect(component.state.isVisible).toBe(true);
-expect(component.props.onClick).toHaveBeenCalled();
-```
-
-### 4. Mock External Dependencies
-```typescript
-// Mock API calls
-vi.mock('../api/users', () => ({
-  fetchUser: vi.fn().mockResolvedValue({ id: 1, name: 'John' })
-}));
-
-// Mock modules
-vi.mock('react-router-dom', () => ({
-  useNavigate: () => vi.fn()
-}));
-```
-
-### 5. Clean Up After Tests
-```typescript
-afterEach(() => {
-  cleanup();
-  vi.clearAllMocks();
-});
-```
-
-## 🔄 Common Patterns
-
-### 1. Component Testing Pattern
-```typescript
-describe('Button Component', () => {
-  describe('Rendering', () => {
-    it('renders with text', () => {
-      render(<Button>Click me</Button>);
-      expect(screen.getByRole('button')).toBeInTheDocument();
-    });
-  });
-  
-  describe('Event Handling', () => {
-    it('handles click events', async () => {
-      const handleClick = vi.fn();
-      const user = userEvent.setup();
-      
-      render(<Button onClick={handleClick}>Click me</Button>);
-      await user.click(screen.getByRole('button'));
-      
-      expect(handleClick).toHaveBeenCalledTimes(1);
-    });
-  });
-});
-```
-
-### 2. Hook Testing Pattern
-```typescript
-describe('useCounter Hook', () => {
-  it('initializes with default value', () => {
-    const { result } = renderHook(() => useCounter());
-    expect(result.current.count).toBe(0);
-  });
-  
-  it('increments count', () => {
-    const { result } = renderHook(() => useCounter(0));
-    
-    act(() => {
-      result.current.increment();
-    });
-    
-    expect(result.current.count).toBe(1);
-  });
-});
-```
-
-### 3. Integration Testing Pattern
-```typescript
-describe('User Profile Integration', () => {
-  it('loads and displays user data', async () => {
-    render(<UserProfile userId="1" />);
-    
-    await waitFor(() => {
-      expect(screen.getByText('John Doe')).toBeInTheDocument();
-    });
-  });
-});
-```
-
-## ❌ Anti-Patterns
-
-### 1. Testing Implementation Details
-```typescript
-// ❌ Bad
-expect(component.state.isVisible).toBe(true);
-expect(component.props.onClick).toHaveBeenCalled();
-
-// ✅ Good
-expect(screen.getByText('Visible content')).toBeInTheDocument();
-await user.click(screen.getByRole('button'));
-```
-
-### 2. Over-Mocking
-```typescript
-// ❌ Bad - Mocking everything
-vi.mock('../utils/formatDate');
-vi.mock('../hooks/useAuth');
-vi.mock('../components/Button');
-
-// ✅ Good - Mock only what's necessary
-vi.mock('../api/users');
-```
-
-### 3. Testing Multiple Things in One Test
-```typescript
-// ❌ Bad
-it('renders button and handles click and shows loading', () => {
-  // Too many assertions
-});
-
-// ✅ Good
-it('renders button', () => {});
-it('handles click', () => {});
-it('shows loading state', () => {});
-```
-
-### 4. Brittle Selectors
-```typescript
-// ❌ Bad - Fragile selectors
-screen.getByClassName('btn-primary');
-screen.getByTestId('submit-button');
-
-// ✅ Good - Semantic selectors
-screen.getByRole('button', { name: 'Submit' });
-screen.getByLabelText('Email address');
-```
-
-## 📊 Code Coverage
-
-### Coverage Targets
-- **Statements**: 80%
-- **Branches**: 80%
-- **Functions**: 80%
-- **Lines**: 80%
-
-### What to Test
-- ✅ Happy paths
-- ✅ Error conditions
-- ✅ Edge cases
-- ✅ User interactions
-- ✅ State changes
-
-### What NOT to Test
-- ❌ Third-party library code
-- ❌ Generated code
-- ❌ Configuration files
-- ❌ Type definitions
-
-## 🧩 Test Expansion Workflow
-
-When expanding test coverage:
-
-1. **Start with the coverage report** (`npm test -- --coverage`)
-2. Identify high-priority or under-tested modules
-3. Choose the appropriate test type (unit, component, integration)
-4. Use our standard structure and semantic queries
-5. Assert observable behaviour (not internal state or styles)
-6. Use test tags (`[unit]`, `[integration]`, etc.) for discoverability
-
-## ✅ Pre-Merge Test Checklist
-
-- [ ] Are all tests passing (no `it.only` or `test.skip`)?
-- [ ] Are coverage thresholds still met?
-- [ ] Are tests colocated with the source?
-- [ ] Are semantic queries used (no test IDs)?
-- [ ] Is global state cleaned up properly?
-- [ ] Are new utilities or hooks covered with tests?
-
-## 🚀 Running Tests
-
-### Commands
-```bash
-# Run all tests
-npm test
-
-# Run tests in watch mode
-npm test -- --watch
-
-# Run tests with coverage
-npm test -- --coverage
-
-# Run specific test file
-npm test -- Button.test.tsx
-
-# Run tests matching pattern
-npm test -- --grep "Button"
-```
-
-### Debugging Tests
-```typescript
-// Debug output
-screen.debug();
-
-// Debug specific element
-screen.debug(screen.getByRole('button'));
-
-// Log all queries
-screen.logTestingPlaygroundURL();
-```
-
-## 📚 Resources
-
-- [React Testing Library Docs](https://testing-library.com/docs/react-testing-library/intro/)
-- [Vitest Docs](https://vitest.dev/)
-- [Testing Best Practices](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
-- [Jest DOM Matchers](https://github.com/testing-library/jest-dom)
----
-
-## 🔖 Test Type Tags
-
-Use explicit tags to clarify the type of test being written:
-
-- `[unit]` – for isolated logic (e.g. pure functions, hooks)
-- `[component]` – for rendering UI components with interactions
-- `[integration]` – for multi-module tests or user journeys
-
-**Example:**
-
-```ts
-describe('[unit] useDebounce', () => {
-  it('should delay the update', () => { ... })
-})
-```
-
----
-
-## 🚫 Skipped Tests Policy
-
-- All `it.skip` or `test.skip` must include a comment explaining why, and reference a JIRA or GitHub issue.
-- Example:
-
-```ts
-it.skip('fails intermittently in CI – see GH#456', () => { ... })
-```
-
----
-
-## 🗂 File Placement
-
-- ✅ Unit/component tests should be colocated with their source file.
-- ✅ Integration tests go in `src/__tests__/integration/`.
-- ✅ Test utilities, fixtures, and mock setup belong in `src/__tests__/helpers/` or `src/__tests__/fixtures/`.
-
----
-
-## 🧑‍🎨 Style-Resilient Test Practices
-
-Tests should **never assert class names, layout structure, or DOM nesting** unless explicitly testing responsive/UI logic.  
-Instead, assert **visible output and interactive behaviour** that users experience (e.g. text content, button states, aria roles, form values).  
-This ensures tests remain stable through valid styling and layout changes.
-
----
-
-## 🚀 Performance Best Practices
-
-- Avoid global mocks unless necessary.
-- Prefer `beforeEach` over `beforeAll` to keep tests isolated.
-- Minimise deep setup logic—use lightweight, focused factories.
-- Use `vi.useFakeTimers()` for time-sensitive logic.
-- Monitor heap usage with `--logHeapUsage` flag for memory-intensive tests.
-- Reduce parallelization if encountering memory issues.
-
----
-
-## 🧹 Memory Leak Prevention
-
-### Common Causes of Memory Leaks
-1. **Unmounted timers** - setInterval/setTimeout not cleared
-2. **Event listeners** - Not removed in cleanup
-3. **Subscriptions** - Not unsubscribed
-4. **DOM references** - Lingering references to removed elements
-5. **Global state** - Not reset between tests
-6. **Mocks** - Not cleared after tests
-
-### Prevention Checklist
-```typescript
-describe('Component with Resources', () => {
-  beforeEach(() => {
-    // Setup fake timers if using setTimeout/setInterval
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    // Clear all timers
-    vi.clearAllTimers();
-    vi.useRealTimers();
-    
-    // React Testing Library cleanup (unmount components)
-    cleanup();
-    
-    // Clear all mocks
-    vi.clearAllMocks();
-    
-    // Clear storage
-    localStorage.clear();
-    sessionStorage.clear();
-  });
-
-  it('handles async operations', async () => {
-    // test implementation
-  });
-});
-```
-
-### Detecting Memory Leaks
-```bash
-# Run tests with heap logging
-npm test -- --logHeapUsage
-
-# Look for tests showing increasing memory usage
-# Baseline: 44-50 MB
-# Warning: 50-55 MB
-# Critical: >55 MB
-```
-
----
-
-## ⏱️ Async Testing Best Practices
-
-### Use findBy Over getBy + waitFor
-```typescript
-// ❌ Bad - Inefficient
-await waitFor(() => {
-  expect(screen.getByRole('button')).toBeInTheDocument();
-});
-
-// ✅ Good - Built-in waiting
-const button = await screen.findByRole('button');
-expect(button).toBeInTheDocument();
-```
-
-### Set Appropriate Timeouts
-```typescript
-// For fast synchronous operations - don't use waitFor
-expect(result.current.value).toBe('test');
-
-// For quick async operations
-await waitFor(() => {
-  expect(result.current.isLoading).toBe(false);
-}, { timeout: 100, interval: 10 });
-
-// For slow operations only
-await waitFor(() => {
-  expect(result.current.data).toBeDefined();
-}, { timeout: 5000 });
-```
-
-### waitFor Usage Guidelines
-- **DON'T** use waitFor for synchronous operations
-- **DO** use findBy queries when waiting for elements
-- **DO** set explicit timeouts based on expected operation speed
-- **DO** add interval to reduce polling frequency for slow operations
-- **DON'T** nest waitFor calls (causes exponential delays)
-
-### Common waitFor Mistakes
-```typescript
-// ❌ Bad - Waiting for sync operation
-const { result } = renderHook(() => useCounter(0));
-await waitFor(() => {
-  expect(result.current.count).toBe(0); // This is synchronous!
-});
-
-// ✅ Good - Direct assertion
-const { result } = renderHook(() => useCounter(0));
-expect(result.current.count).toBe(0);
-
-// ❌ Bad - Generic timeout without condition
-await waitFor(() => {}, { timeout: 1000 }); // Just waiting
-
-// ✅ Good - Wait for specific condition
-await waitFor(() => {
-  expect(result.current.isLoading).toBe(false);
-});
-```
-
----
-
-## 🔧 Mocking Complex APIs
-
-### Mocking Functions with Multiple Call Signatures
-When testing code that calls a mocked function multiple times with different parameters:
-
-```typescript
-// ❌ Bad - mockResolvedValue returns same data for all calls
-mockSupabase.rpc.mockResolvedValue({ data: [...], error: null });
-
-// ✅ Good - mockImplementation handles different calls
-mockSupabase.rpc.mockImplementation((functionName: string, params) => {
-  if (functionName === 'get_user') {
-    return Promise.resolve({ data: { id: '1' }, error: null });
-  }
-  if (functionName === 'get_permissions') {
-    return Promise.resolve({ data: [...], error: null });
-  }
-  return Promise.resolve({ data: null, error: null });
-});
-```
-
-### Example: useRBAC Hook Mocking
-```typescript
-// useRBAC makes TWO RPC calls - must mock both
-const setupRBACMock = (permissions: any[] = []) => {
-  mockSupabase.rpc.mockImplementation((functionName, params) => {
-    if (functionName === 'util_app_resolve') {
-      return Promise.resolve({
-        data: [{ app_id: 'test-app-id', has_access: true }],
-        error: null
-      });
-    }
-    if (functionName === 'rbac_permissions_get') {
-      return Promise.resolve({ data: permissions, error: null });
-    }
-    return Promise.resolve({ data: null, error: null });
-  });
-};
-
-// Usage in tests
-it('loads user permissions', async () => {
-  setupRBACMock([
-    { permission_type: 'all_permissions', role_name: 'super_admin' }
-  ]);
-  
-  const { result } = renderHook(() => useRBAC());
-  await waitFor(() => {
-    expect(result.current.globalRole).toBe('super_admin');
-  });
-});
-```
-
----
-
-## 🔐 RBAC Testing Patterns
-
-When testing RBAC components, providers, and hooks, follow these patterns to ensure comprehensive coverage of security-critical functionality.
-
-### Testing RBAC Providers
-
-#### Organisation Context Integration
-```typescript
-describe('RBACProvider', () => {
-  it('requires organisation context when set', () => {
-    const { result } = renderHook(() => useRBAC());
-    
-    expect(() => result.current.requireOrganisationContext()).toThrow();
-  });
-
-  it('returns organisation ID when context is available', () => {
-    renderWithProviders(<App />, { organisationId: 'org-123' });
-    const { result } = renderHook(() => useRBAC());
-    
-    expect(result.current.requireOrganisationContext()).toBe('org-123');
-  });
-});
-```
-
-#### Permission Refresh Logic
-```typescript
-describe('RBACProvider', () => {
-  it('refreshes permissions when event changes', async () => {
-    const mockPermissions = [
-      { permission_type: 'event_app_access', role_name: 'planner' }
-    ];
-    
-    setupRBACMock(mockPermissions);
-    
-    const { result } = renderHook(() => useRBAC());
-    
-    // Initial permissions
-    expect(result.current.isLoading).toBe(true);
-    
-    await waitFor(() => {
-      expect(result.current.isLoading).toBe(false);
-    });
-    
-    // Change event
-    act(() => {
-      result.current.setSelectedEventId('new-event-id');
-    });
-    
-    await waitFor(() => {
-      expect(result.current.rbacLoading).toBe(false);
-    });
-  });
-});
-```
-
-### Testing Permission Hooks
-
-#### Cache vs No-Cache Behavior
-```typescript
-describe('usePermissions Hook', () => {
-  it('uses cached results when useCache is true', async () => {
-    const setupPermissionsMock = () => {
-      mockSupabase.rpc.mockImplementation((functionName) => {
-        if (functionName === 'rbac_permissions_get') {
-          return Promise.resolve({
-            data: [{ permission_type: 'read:users', role_name: 'viewer' }],
-            error: null
-          });
-        }
-        return Promise.resolve({ data: null, error: null });
-      });
-    };
-    
-    setupPermissionsMock();
-    
-    const { result, rerender } = renderHook(
-      ({ cache }) => usePermissions('user-123', scope, { useCache: cache }),
-      { initialProps: { cache: true } }
-    );
-    
-    await waitFor(() => {
-      expect(result.current.permissions).toBeDefined();
-    });
-    
-    // Second call should use cache (no new API call expected)
-    rerender({ cache: true });
-    
-    // Verify API was only called once (would need mock tracking)
-  });
-});
-```
-
-#### Multi-Permission Validation
-```typescript
-describe('useHasAnyPermission Hook', () => {
-  it('returns true if user has any of the required permissions', async () => {
-    const mockPermissions = [
-      { permission_type: 'read:users', role_name: 'viewer' }
-    ];
-    
-    setupRBACMock(mockPermissions);
-    
-    const { result } = renderHook(() => 
-      useHasAnyPermission('user-123', scope, ['read:users', 'write:users'])
-    );
-    
-    await waitFor(() => {
-      expect(result.current.hasAny).toBe(true);
-    });
-  });
-  
-  it('returns false if user has none of the required permissions', async () => {
-    const mockPermissions = [];
-    
-    setupRBACMock(mockPermissions);
-    
-    const { result } = renderHook(() => 
-      useHasAnyPermission('user-123', scope, ['read:users', 'write:users'])
-    );
-    
-    await waitFor(() => {
-      expect(result.current.hasAny).toBe(false);
-    });
-  });
-});
-```
-
-### Testing Error Recovery
-
-```typescript
-describe('RBACProvider', () => {
-  it('handles permission fetch errors gracefully', async () => {
-    const mockError = new Error('Permission fetch failed');
-    
-    mockSupabase.rpc.mockImplementation(() => {
-      return Promise.resolve({ data: null, error: mockError });
-    });
-    
-    const { result } = renderHook(() => useRBAC());
-    
-    await waitFor(() => {
-      expect(result.current.rbacError).toBeDefined();
-      expect(result.current.rbacError?.message).toContain('Permission fetch failed');
-    });
-    
-    // Verify permissions are cleared on error
-    expect(result.current.permissions).toEqual({});
-  });
-  
-  it('allows retry after error', async () => {
-    // Setup initial error
-    mockSupabase.rpc.mockRejectedValueOnce(new Error('Network error'));
-    
-    const { result } = renderHook(() => useRBAC());
-    
-    await waitFor(() => {
-      expect(result.current.rbacError).toBeDefined();
-    });
-    
-    // Setup successful response for retry
-    mockSupabase.rpc.mockResolvedValueOnce({
-      data: [{ permission_type: 'read:users' }],
-      error: null
-    });
-    
-    await act(async () => {
-      await result.current.refreshPermissions();
-    });
-    
-    expect(result.current.rbacError).toBeNull();
-    expect(result.current.permissions).toBeDefined();
-  });
-});
-```
-
-### Mocking RBAC RPC Functions
-
-When testing RBAC components, ensure all RPC calls are properly mocked:
-
-```typescript
-const setupRBACMock = (permissions: any[] = [], orgContext = true) => {
-  mockSupabase.rpc.mockImplementation((functionName, params) => {
-    if (functionName === 'util_app_resolve') {
-      return Promise.resolve({
-        data: [{ app_id: 'test-app-id', has_access: true }],
-        error: null
-      });
-    }
-    
-    if (functionName === 'rbac_permissions_get') {
-      // Always include organisation context in RBAC calls
-      expect(params).toHaveProperty('p_organisation_id');
-      if (!orgContext) {
-        return Promise.resolve({ data: [], error: null });
-      }
-      
-      return Promise.resolve({ data: permissions, error: null });
-    }
-    
-    return Promise.resolve({ data: null, error: null });
-  });
-};
-```
-
-### Testing Complete RBAC Workflows
-
-```typescript
-describe('Complete RBAC Workflow', () => {
-  it('handles full user journey: login → select org → select event → check permissions', async () => {
-    // 1. User logs in
-    const { result: authResult } = renderHook(() => useAuth());
-    
-    await act(async () => {
-      await authResult.current.signIn({
-        email: 'user@example.com',
-        password: 'password'
-      });
-    });
-    
-    // 2. User selects organisation
-    const { result: orgResult } = renderHook(() => useOrganisationContext());
-    
-    await act(async () => {
-      await orgResult.current.setSelectedOrganisationId('org-123');
-    });
-    
-    // 3. User selects event
-    const { result: rbacResult } = renderHook(() => useRBAC());
-    
-    await act(async () => {
-      rbacResult.current.setSelectedEventId('event-456');
-    });
-    
-    // 4. Verify permissions are loaded
-    await waitFor(() => {
-      expect(rbacResult.current.rbacLoading).toBe(false);
-    });
-    
-    expect(rbacResult.current.hasPermission('read:users')).toBe(true);
-  });
-});
-```
-
----
-
-## 🔌 Service Testing Patterns
-
-When testing services (Auth, Event, Organisation, RBAC, Security), ensure comprehensive coverage of API interactions, error handling, and data transformations.
-
-### Testing Service Methods
-
-#### Mocking Supabase Client
-```typescript
-describe('AuthService', () => {
-  let mockSupabase: ReturnType<typeof createMockSupabaseClient>;
-  let authService: AuthService;
-  
-  beforeEach(() => {
-    mockSupabase = createMockSupabaseClient();
-    authService = new AuthService(mockSupabase);
-  });
-  
-  it('signs in user successfully', async () => {
-    const mockUser = { id: '123', email: 'user@example.com' };
-    
-    mockSupabase.auth.signInWithPassword.mockResolvedValue({
-      data: { user: mockUser, session: {} },
-      error: null
-    });
-    
-    const result = await authService.signIn({
-      email: 'user@example.com',
-      password: 'password'
-    });
-    
-    expect(result).toBeDefined();
-    expect(result.user).toEqual(mockUser);
-    expect(mockSupabase.auth.signInWithPassword).toHaveBeenCalledWith({
-      email: 'user@example.com',
-      password: 'password'
-    });
-  });
-});
-```
-
-### Testing Error Scenarios
-
-```typescript
-describe('EventService', () => {
-  it('handles fetch errors gracefully', async () => {
-    const mockError = new Error('Network error');
-    
-    mockSupabase.from().select().mockRejectedValue(mockError);
-    
-    await expect(eventService.fetchEvent('event-id')).rejects.toThrow();
-  });
-  
-  it('returns null for non-existent events', async () => {
-    mockSupabase.from().select().mockResolvedValue({
-      data: null,
-      error: null
-    });
-    
-    const result = await eventService.fetchEvent('non-existent-id');
-    
-    expect(result).toBeNull();
-  });
-});
-```
-
-### Testing Data Transformations
-
-```typescript
-describe('OrganisationService', () => {
-  it('transforms raw database data to entity format', async () => {
-    const rawData = {
-      id: 'org-123',
-      name: 'Test Organisation',
-      created_at: '2024-01-01T00:00:00Z'
-    };
-    
-    mockSupabase.from().select().mockResolvedValue({
-      data: [rawData],
-      error: null
-    });
-    
-    const result = await organisationService.fetchOrganisation('org-123');
-    
-    expect(result).toMatchObject({
-      id: 'org-123',
-      name: 'Test Organisation',
-      createdAt: expect.any(Date)
-    });
-  });
-});
-```
-
-### Testing Subscription Handling
-
-```typescript
-describe('EventService with Realtime', () => {
-  it('subscribes to event updates', () => {
-    const callback = vi.fn();
-    
-    eventService.subscribeToEvent('event-id', callback);
-    
-    expect(mockSupabase.channel).toHaveBeenCalled();
-    
-    const channelMock = mockSupabase.channel.mock.results[0].value;
-    expect(channelMock.on).toHaveBeenCalledWith(
-      'postgres_changes',
-      expect.objectContaining({
-        event: 'UPDATE',
-        schema: 'public',
-        table: 'event'
-      }),
-      callback
-    );
-  });
-  
-  it('unsubscribes on cleanup', () => {
-    const callback = vi.fn();
-    const unsubscribe = eventService.subscribeToEvent('event-id', callback);
-    
-    const channelMock = mockSupabase.channel.mock.results[0].value;
-    
-    unsubscribe();
-    
-    expect(channelMock.unsubscribe).toHaveBeenCalled();
-  });
-});
-```
-
-### Testing Service Error Recovery
-
-```typescript
-describe('RBACService', () => {
-  it('implements retry logic for transient errors', async () => {
-    let callCount = 0;
-    
-    mockSupabase.rpc.mockImplementation(() => {
-      callCount++;
-      if (callCount === 1) {
-        return Promise.resolve({ data: null, error: { code: 'PGRST116' } });
-      }
-      return Promise.resolve({ data: [{ permission_type: 'read' }], error: null });
-    });
-    
-    const result = await rbacService.getPermissions('user-id');
-    
-    expect(result).toBeDefined();
-    expect(callCount).toBe(2);
-  });
-});
-```
-
-### Verifying API Call Parameters
-
-```typescript
-describe('AuthService', () => {
-  it('includes all required parameters in API calls', async () => {
-    await authService.updateUser({ name: 'John Doe' });
-    
-    expect(mockSupabase.auth.updateUser).toHaveBeenCalledWith({
-      data: { name: 'John Doe' }
-    });
-  });
-  
-  it('handles organisation context in RBAC calls', async () => {
-    await rbacService.getPermissions('user-id', 'org-123', 'event-456');
-    
-    expect(mockSupabase.rpc).toHaveBeenCalledWith(
-      'rbac_permissions_get',
-      expect.objectContaining({
-        p_user_id: 'user-id',
-        p_organisation_id: 'org-123',
-        p_event_id: 'event-456'
-      })
-    );
-  });
-});
-```
-
----
-
-## 🎨 jsdom Configuration
-
-### Enable Visual Testing Features
-To prevent `getComputedStyle` and other visual API errors:
-
-```typescript
-// vitest.config.ts
-export default defineConfig({
-  test: {
-    environment: 'jsdom',
-    environmentOptions: {
-      jsdom: {
-        pretendToBeVisual: true, // Enables getComputedStyle
-        resources: 'usable',      // Enables resource loading
-      }
-    }
-  }
-});
-```
-
-### Benefits
-- ✅ Automatic getComputedStyle support
-- ✅ Proper CSS property access
-- ✅ Window.matchMedia support
-- ✅ Element.getBoundingClientRect support
-- ✅ No manual mocking needed
-
----
-
-## 🚫 Common Test Anti-Patterns
-
-### 1. Testing with Wrong Mock Approach
-```typescript
-// ❌ Bad - Single mockResolvedValue for multiple calls
-mockApi.fetch.mockResolvedValue(data);
-// Problem: All calls get same data, even if they should differ
-
-// ✅ Good - mockImplementation for different calls
-mockApi.fetch.mockImplementation((endpoint) => {
-  if (endpoint === '/users') return Promise.resolve(users);
-  if (endpoint === '/posts') return Promise.resolve(posts);
-  return Promise.resolve(null);
-});
-```
-
-### 2. Not Accounting for Multiple API Calls
-```typescript
-// ❌ Bad - Assumes hook makes one call
-mockApi.getData.mockResolvedValue(testData);
-
-// ✅ Good - Account for all calls hook makes
-mockApi.getData.mockImplementation((type) => {
-  if (type === 'config') return Promise.resolve(config);
-  if (type === 'data') return Promise.resolve(testData);
-  return Promise.resolve(null);
-});
-```
-
-### 3. Insufficient Async Handling
-```typescript
-// ❌ Bad - Not waiting for async updates
-const { result } = renderHook(() => useAsync());
-expect(result.current.data).toBeDefined(); // May still be loading!
-
-// ✅ Good - Wait for async completion
-const { result } = renderHook(() => useAsync());
-await waitFor(() => {
-  expect(result.current.isLoading).toBe(false);
-});
-expect(result.current.data).toBeDefined();
-```
-
----
-
-## 🎯 Coverage Expectations
-
-Minimum thresholds per category:
-
-- Core utils/hooks: **≥ 95%**
-- UI components: **≥ 90%**
-- Feature modules: **≥ 85%**
-- Overall project: **≥ 82%** (targeting continuous improvement)
-
-## 📊 Coverage Thresholds
-
-| Type | Target | Block CI | Rationale |
-|------|--------|----------|-----------|
-| **Utils/Hooks** | 95% | Yes | Core business logic, high usage |
-| **UI Components** | 90% | Yes | User-facing, must be reliable |
-| **Services** | 85% | Yes | API interactions, critical paths |
-| **Validation** | 95% | Yes | Security and data integrity |
-| **Overall** | 82% | Yes | Maintains quality baseline |
-
-### Enforcing Coverage Thresholds
-
-```typescript
-// vitest.config.ts
-coverage: {
-  thresholds: {
-    lines: 82,
-    branches: 80,
-    functions: 80,
-    statements: 82,
-    
-    // Per-file thresholds
-    'src/hooks/**': {
-      lines: 95,
-      branches: 95,
-      functions: 95
-    },
-    'src/components/**': {
-      lines: 90,
-      branches: 90,
-      functions: 90
-    },
-    'src/services/**': {
-      lines: 85,
-      branches: 85,
-      functions: 85
-    }
-  }
-}
-```
-
-### Coverage Goals by Module
-
-**High Priority (Security & Business Logic)**:
-- RBAC Providers: **≥ 90%** (critical for security)
-- Permission Hooks: **≥ 90%** (used throughout app)
-- Authentication Services: **≥ 90%** (security-critical)
-- Validation Functions: **≥ 95%** (data integrity)
-
-**Medium Priority (Core Features)**:
-- UI Components: **≥ 90%** (user experience)
-- Service Layer: **≥ 85%** (API interactions)
-- Providers: **≥ 85%** (state management)
-
-**Acceptable Gaps**:
-- Type definitions (interfaces, types only): **0%** (acceptable)
-- Auto-generated code: **0%** (acceptable)
-- Example components: **0%** (not in production)
-- DataTable subcomponents with **intentional low coverage** (tested via integration tests)
-
----
-
-## 🧩 DataTable Testing Patterns
-
-The DataTable component and its subcomponents follow a specific testing strategy that prioritizes integration tests over isolated unit tests for tightly-coupled components.
-
-### Intentional Low Coverage on Subcomponents
-
-Several DataTable subcomponents show low coverage percentages (0-15%):
-- `ColumnFilter.tsx` - 5.81%
-- `FilterRow.tsx` - 2.77%
-- `EditableRow.tsx` - 5.14%
-- `DraggableColumnHeader.tsx` - 0%
-- `ViewRowModal.tsx` - 0%
-- `ExpandButton.tsx` - 0%
-- `GroupHeader.tsx` - 11.53%
-- `DataTableBody.tsx` - 0%
-
-**This is intentional and correct** - these components are comprehensively tested through DataTable integration tests.
-
-### Why Integration Tests Over Unit Tests?
-
-1. **Tight Coupling with TanStack React Table**: These subcomponents depend heavily on table internals that would require extensive mocking
-2. **Behavior Over Implementation**: Integration tests verify actual user interactions rather than internal implementation details
-3. **Prevent Brittle Tests**: Isolated unit tests would be fragile and break on any internal refactoring
-4. **User Value Focus**: Users interact with DataTable as a whole, not individual subcomponents
-
-### DataTable Testing Strategy
-
-```typescript
-// ✅ Good - Integration test for DataTable workflows
-describe('DataTable - Editing Workflow', () => {
-  it('allows editing rows with save/cancel actions', async () => {
-    render(<DataTable data={mockData} onSave={mockSave} />);
-    await user.click(screen.getByRole('button', { name: 'Edit' }));
-    await user.type(screen.getByRole('textbox'), 'Updated Value');
-    await user.click(screen.getByRole('button', { name: 'Save' }));
-    expect(mockSave).toHaveBeenCalledWith(expectedData);
-  });
-});
-
-// ❌ Bad - Unit test for isolated subcomponent
-// Would require mocking TanStack table internals
-describe('EditableRow Component', () => {
-  it('handles edit state', () => {
-    // Tests implementation, not behavior
-  });
-});
-```
-
-### Where to Add Tests
-
-**✅ Test These:**
-- Core DataTable component logic (`DataTable.tsx`)
-- DataTable context and state management
-- Feature configuration logic
-- Data transformation utilities
-
-**❌ Don't Test These (Acceptable Low Coverage):**
-- TanStack table subcomponent wrappers
-- Presentation-only rendering components
-- Components tested via integration tests
-
-### Coverage Exemption
-
-Low coverage on DataTable subcomponents is **explicitly exempt** from coverage thresholds. The integration test suite provides comprehensive coverage:
-
-- **Workflow Validation**: 23 tests covering all user interactions
-- **Regression Fixes**: 13 tests preventing known issues
-- **Sorting**: Comprehensive sorting functionality tests
-- **Data Integrity**: Validation of data consistency
-
-**Reference**: See `packages/core/src/components/DataTable/components/__tests__/COVERAGE_NOTE.md` for complete justification.
-
----
-
-## 📚 Additional Resources
-
-- [Vitest Mocking Guide](https://vitest.dev/guide/mocking.html)
-- [Testing Library Best Practices](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
-- [React Hooks Testing](https://react-hooks-testing-library.com/)
-- [jsdom Documentation](https://github.com/jsdom/jsdom)
-
-### Internal Documentation
-- [TEST_FAILURE_ANALYSIS.md](../../../TEST_FAILURE_ANALYSIS.md) - Common test failures and fixes
-- [MEMORY_PERFORMANCE_ANALYSIS.md](../../../MEMORY_PERFORMANCE_ANALYSIS.md) - Performance optimization guide
-- [TEST_SUITE_IMPLEMENTATION_GUIDE.md](../../../TEST_SUITE_IMPLEMENTATION_GUIDE.md) - Step-by-step implementation guide
-
----
-
-## 🌐 PublicLayout Testing Patterns
-
-PublicLayout components are designed to be completely isolated from authentication and organisation context for public-facing pages.
-
-### Testing PublicPageProvider
-
-**Key Principles**:
-- Test environment variable handling (Vite & Node.js environments)
-- Test Supabase client creation from environment variables
-- Test error boundary integration
-- Verify no authentication context triggers
-
-```typescript
-describe('PublicPageProvider', () => {
-  it('provides Supabase client when environment variables are present', () => {
-    render(
-      <PublicPageProvider>
-        <TestComponent />
-      </PublicPageProvider>
-    );
-
-    expect(screen.getByTestId('has-client')).toBeInTheDocument();
-  });
-
-  it('provides isPublicPage flag in context', () => {
-    const { result } = renderHook(() => usePublicPageContext(), {
-      wrapper: ({ children }) => (
-        <PublicPageProvider>{children}</PublicPageProvider>
-      )
-    });
-
-    expect(result.current.isPublicPage).toBe(true);
-  });
-
-  it('wraps children with PublicErrorBoundary', () => {
-    const { container } = render(
-      <PublicPageProvider>
-        <div>Test Content</div>
-      </PublicPageProvider>
-    );
-
-    // Should render children through error boundary
-    expect(screen.getByText('Test Content')).toBeInTheDocument();
-  });
-});
-```
-
-### Testing PublicPageDebugger
-
-**Key Principles**:
-- Test console logging when enabled
-- Test context detection logic
-- Test enable/disable state changes
-
-```typescript
-describe('PublicPageDebugger', () => {
-  it('logs context information when enabled', async () => {
-    const consoleSpy = vi.spyOn(console, 'log');
-    
-    render(
-      <PublicPageProvider>
-        <PublicPageDebugger enabled={true} label="TestDebugger" />
-      </PublicPageProvider>
-    );
-
-    // Wait for useEffect to execute
-    await new Promise(resolve => setTimeout(resolve, 10));
-    
-    expect(consoleSpy).toHaveBeenCalled();
-  });
-
-  it('does not render when disabled', () => {
-    render(
-      <PublicPageProvider>
-        <PublicPageDebugger enabled={false} />
-      </PublicPageProvider>
-    );
-
-    expect(screen.queryByText('Public Page Debugger')).not.toBeInTheDocument();
-  });
-});
-```
-
-### Testing PublicPageContextChecker
-
-**Key Principles**:
-- Test immediate context validation
-- Test console error warnings
-- Test architecture guidance
-
-```typescript
-describe('PublicPageContextChecker', () => {
-  it('groups console output with proper labels', async () => {
-    const consoleGroupSpy = vi.spyOn(console, 'group');
-    
-    render(
-      <PublicPageProvider>
-        <PublicPageContextChecker enabled={true} label="TestChecker" />
-      </PublicPageProvider>
-    );
-
-    await new Promise(resolve => setTimeout(resolve, 10));
-    
-    expect(consoleGroupSpy).toHaveBeenCalled();
-  });
-
-  it('displays warning about context issues', () => {
-    render(
-      <PublicPageProvider>
-        <PublicPageContextChecker enabled={true} />
-      </PublicPageProvider>
-    );
-
-    expect(screen.getByText(/If you see ❌ errors in console/)).toBeInTheDocument();
-  });
-});
-```
-
-### Common Pitfalls
-
-**❌ Don't: Directly set import.meta.env**
-```typescript
-// ❌ Bad - This doesn't work reliably in tests
-(import.meta as any).env.VITE_SUPABASE_URL = 'http://localhost';
-
-// ✅ Good - Mock createClient instead
-vi.mock('@supabase/supabase-js', () => ({
-  createClient: vi.fn(() => mockClient)
-}));
-```
-
-**❌ Don't: Test internal environment variable values**
-```typescript
-// ❌ Bad - Testing implementation details
-expect(context.environment.supabaseUrl).toBe('specific-value');
-
-// ✅ Good - Test observable behavior
-expect(console.warn).toHaveBeenCalledWith(
-  expect.stringContaining('Missing Supabase environment variables')
-);
-```
-
-**✅ Do: Test observable behavior**
-- Verify context is provided (not specific values)
-- Verify Supabase client attempts creation
-- Verify error boundary wraps children
-- Verify console warnings are logged when appropriate
-
----
-
-## 🎯 Service Hook Testing Patterns
-
-Service hooks provide access to services with reactive state updates. They follow a simple but critical pattern.
-
-### Pattern Overview
-
-All service hooks follow the same structure:
-1. Get context from provider
-2. Throw if context is missing
-3. Subscribe to service state changes
-4. Force re-render on service updates
-
-### Testing Context Validation
-
-```typescript
-describe('Service Hooks', () => {
-  it('throws error when used outside provider', () => {
-    expect(() => {
-      renderHook(() => useEventService());
-    }).toThrow('useEventService must be used within EventServiceProvider');
-  });
-
-  it('validates provider requirement consistently', () => {
-    const errorMessages = [
-      'useEventService must be used within EventServiceProvider',
-      'useOrganisationService must be used within OrganisationServiceProvider',
-      'useInactivityService must be used within InactivityServiceProvider'
-    ];
-
-    errorMessages.forEach(msg => {
-      expect(msg).toMatch(/must be used within \w+Provider$/);
-    });
-  });
-});
-```
-
-### Testing Subscription Cleanup
-
-```typescript
-describe('Service Hook Subscriptions', () => {
-  it('cleans up subscriptions on unmount', () => {
-    const unsubscribe = vi.fn();
-    const mockService = {
-      subscribe: vi.fn(() => unsubscribe)
-    };
-
-    const { unmount } = renderHook(() => useEventService(), {
-      wrapper: ({ children }) => (
-        <EventServiceContext.Provider value={{ eventService: mockService }}>
-          {children}
-        </EventServiceContext.Provider>
-      )
-    });
-
-    unmount();
-    
-    expect(unsubscribe).toHaveBeenCalled();
-  });
-});
-```
-
-### Testing Error Message Consistency
-
-```typescript
-describe('Service Hook Error Handling', () => {
-  it('all hooks use consistent error message pattern', () => {
-    const hooks = [
-      useEventService,
-      useOrganisationService,
-      useInactivityService,
-      useRBACService,
-      useAuthService
-    ];
-
-    hooks.forEach(hook => {
-      expect(() => renderHook(() => hook())).toThrow(
-        /must be used within \w+Provider$/
-      );
-    });
-  });
-});
-```
-
-### Common Patterns
-
-**Hook Pattern**:
-```typescript
-export function useEventService(): EventService {
-  const context = useContext(EventServiceContext);
-  
-  if (!context) {
-    throw new Error('useEventService must be used within EventServiceProvider');
-  }
-  
-  const [, forceUpdate] = useReducer(x => x + 1, 0);
-  
-  useEffect(() => {
-    return context.eventService.subscribe(() => forceUpdate());
-  }, [context.eventService]);
-  
-  return context.eventService;
-}
-```
-
-**Test Pattern**:
-```typescript
-describe('useServiceHook', () => {
-  it('throws error when outside provider', () => {
-    expect(() => renderHook(() => useService())).toThrow();
-  });
-
-  it('returns service when inside provider', () => {
-    const { result } = renderHook(() => useService(), {
-      wrapper: ({ children }) => (
-        <ServiceContext.Provider value={{ service: mockService }}>
-          {children}
-        </ServiceContext.Provider>
-      )
-    });
-
-    expect(result.current).toBe(mockService);
-  });
-
-  it('subscribes to service updates', () => {
-    // Test subscription logic
-  });
-});
-```
-
-### Benefits
-
-- **Consistent Error Messages**: All hooks provide clear, actionable error messages
-- **Reactivity**: Components re-render when service state changes
-- **Automatic Cleanup**: Subscriptions are cleaned up on unmount
-- **Type Safety**: TypeScript ensures correct service type usage