@jmruthers/pace-core 0.5.87 → 0.5.88

package/src/__tests__/TEST_STANDARD.md

@@ -0,0 +1,674 @@
+# Testing Standard
+
+The authoritative guide for writing world-class tests in the pace-core project. Every test contribution should follow these standards to ensure reliability, maintainability, and comprehensive coverage.
+
+## 🎯 Testing Philosophy
+
+### Core Principles
+
+1. **Test Behavior, Not Implementation** - Focus on what users see and do, not internal code structure
+2. **Fast & Reliable** - Tests should run quickly and produce consistent results
+3. **Independent & Isolated** - Tests should not depend on each other or external state
+4. **Self-Documenting** - Tests should clearly express intent and expected behavior
+5. **Maintainable** - Tests should be easy to update when requirements change
+
+### The Testing Pyramid
+
+```
+    /\
+   /  \     E2E Tests (Few)
+  /____\    
+ /      \   Integration Tests (Some)
+/________\  
+            Unit Tests (Many)
+```
+
+**Distribution Guidelines:**
+- **Unit Tests (80%)**: Fast, isolated tests for individual functions/components
+- **Integration Tests (15%)**: Test component interactions and data flow
+- **E2E Tests (5%)**: Full user journey validation
+
+## 🏗️ Test Organization
+
+### File Structure
+
+**✅ Preferred: Colocated Tests**
+```
+src/
+├── components/
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   └── Button.test.tsx          ✅ Next to source
+│   └── DataTable/
+│       ├── DataTable.tsx
+│       ├── DataTable.test.tsx       ✅ Main component tests
+│       └── __tests__/               ✅ For multiple test files
+│           └── DataTable.integration.test.tsx
+├── hooks/
+│   ├── useCounter.ts
+│   └── useCounter.test.ts           ✅ Colocated
+└── services/
+    ├── AuthService.ts
+    └── AuthService.test.ts          ✅ Colocated
+```
+
+**When to Use `__tests__/` Directory:**
+- Multiple test files for one source file (unit + integration)
+- Shared test utilities within a module
+- Integration tests spanning multiple components
+
+**Central `src/__tests__/` Directory - ONLY for:**
+- Cross-module integration tests
+- Shared test utilities and fixtures
+- Test configuration files
+
+### File Naming Conventions
+
+- `ComponentName.test.tsx` - Component tests
+- `hookName.test.ts` - Hook tests  
+- `serviceName.test.ts` - Service tests
+- `feature.integration.test.tsx` - Integration tests
+- `utils.unit.test.ts` - Utility function tests
+
+## 📝 Test Structure & Naming
+
+### Describe Block Organization
+
+```typescript
+describe('ComponentName', () => {
+  describe('Rendering', () => {
+    it('renders with default props', () => {});
+    it('renders with custom content', () => {});
+  });
+  
+  describe('User Interactions', () => {
+    it('handles click events', () => {});
+    it('handles keyboard navigation', () => {});
+  });
+  
+  describe('State Management', () => {
+    it('updates state on user input', () => {});
+    it('resets state on form submission', () => {});
+  });
+  
+  describe('Error Handling', () => {
+    it('displays error message on validation failure', () => {});
+    it('recovers from network errors', () => {});
+  });
+});
+```
+
+### Test Naming Best Practices
+
+```typescript
+// ✅ Good - Descriptive and behavior-focused
+it('renders submit button when form is valid', () => {});
+it('disables submit button when required fields are empty', () => {});
+it('shows loading spinner during form submission', () => {});
+
+// ❌ Bad - Vague or implementation-focused
+it('works correctly', () => {});
+it('test button component', () => {});
+it('should call onClick prop', () => {});
+```
+
+## 🧪 Testing Patterns
+
+### 1. Component Testing (AAA Pattern)
+
+```typescript
+describe('Button Component', () => {
+  it('handles click events with custom handler', async () => {
+    // Arrange
+    const handleClick = vi.fn();
+    const user = userEvent.setup();
+    
+    render(<Button onClick={handleClick}>Click me</Button>);
+    
+    // Act
+    await user.click(screen.getByRole('button', { name: 'Click me' }));
+    
+    // Assert
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### 2. Hook Testing
+
+```typescript
+describe('useCounter Hook', () => {
+  it('initializes with provided value', () => {
+    const { result } = renderHook(() => useCounter(5));
+    
+    expect(result.current.count).toBe(5);
+  });
+  
+  it('increments count when increment is called', () => {
+    const { result } = renderHook(() => useCounter(0));
+    
+    act(() => {
+      result.current.increment();
+    });
+    
+    expect(result.current.count).toBe(1);
+  });
+});
+```
+
+### 3. Service Testing
+
+```typescript
+describe('AuthService', () => {
+  let mockSupabase: ReturnType<typeof createMockSupabaseClient>;
+  let authService: AuthService;
+  
+  beforeEach(() => {
+    mockSupabase = createMockSupabaseClient();
+    authService = new AuthService(mockSupabase);
+  });
+  
+  it('signs in user with valid credentials', 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.user).toEqual(mockUser);
+  });
+});
+```
+
+### 4. Integration Testing
+
+```typescript
+describe('User Registration Flow', () => {
+  it('completes full registration workflow', async () => {
+    const user = userEvent.setup();
+    
+    render(<RegistrationForm />);
+    
+    // Fill form
+    await user.type(screen.getByLabelText('Email'), 'user@example.com');
+    await user.type(screen.getByLabelText('Password'), 'password123');
+    
+    // Submit
+    await user.click(screen.getByRole('button', { name: 'Register' }));
+    
+    // Verify success
+    expect(await screen.findByText('Registration successful')).toBeInTheDocument();
+  });
+});
+```
+
+## 🔍 Query Best Practices
+
+### Semantic Queries (Preferred)
+
+```typescript
+// ✅ Excellent - Semantic and accessible
+screen.getByRole('button', { name: 'Submit' });
+screen.getByLabelText('Email address');
+screen.getByText('Welcome back');
+screen.getByPlaceholderText('Enter your name');
+
+// ✅ Good - Content-based
+screen.getByDisplayValue('current-value');
+screen.getByTitle('Close dialog');
+
+// ⚠️ Use sparingly - When semantic queries aren't sufficient
+screen.getByTestId('complex-widget');
+```
+
+### Query Priority Order
+
+1. **getByRole** - Most accessible and semantic
+2. **getByLabelText** - Form elements with labels
+3. **getByText** - Visible text content
+4. **getByDisplayValue** - Form elements with values
+5. **getByAltText** - Images with alt text
+6. **getByTitle** - Elements with title attribute
+7. **getByTestId** - Last resort for complex cases
+
+### Async Query Patterns
+
+```typescript
+// ✅ Good - Built-in waiting with findBy
+const button = await screen.findByRole('button', { name: 'Submit' });
+
+// ✅ Good - Wait for specific condition
+await waitFor(() => {
+  expect(screen.getByText('Data loaded')).toBeInTheDocument();
+});
+
+// ❌ Bad - Waiting for synchronous operations
+await waitFor(() => {
+  expect(result.current.count).toBe(0); // This is immediate!
+});
+```
+
+## 🔧 Mocking & Test Doubles
+
+### Mock Strategy
+
+```typescript
+// ✅ Good - Mock external dependencies only
+vi.mock('../api/users', () => ({
+  fetchUser: vi.fn().mockResolvedValue({ id: 1, name: 'John' })
+}));
+
+// ✅ Good - Mock complex external libraries
+vi.mock('react-router-dom', () => ({
+  useNavigate: () => vi.fn(),
+  useLocation: () => ({ pathname: '/test' })
+}));
+
+// ❌ Bad - Over-mocking internal utilities
+vi.mock('../utils/formatDate'); // Usually not necessary
+```
+
+### Multi-Call Mocking
+
+```typescript
+// ✅ Good - Handle different calls with mockImplementation
+mockSupabase.rpc.mockImplementation((functionName, params) => {
+  if (functionName === 'get_user') {
+    return Promise.resolve({ data: { id: '1' }, error: null });
+  }
+  if (functionName === 'get_permissions') {
+    return Promise.resolve({ data: permissions, error: null });
+  }
+  return Promise.resolve({ data: null, error: null });
+});
+```
+
+### Cleanup Best Practices
+
+```typescript
+describe('Component with Resources', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    // Clean up timers
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    
+    // React Testing Library cleanup
+    cleanup();
+    
+    // Clear all mocks
+    vi.clearAllMocks();
+    
+    // Clear storage
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+});
+```
+
+## 🚫 Anti-Patterns to Avoid
+
+### 1. Testing Implementation Details
+
+```typescript
+// ❌ Bad - Testing internal state
+expect(component.state.isVisible).toBe(true);
+expect(wrapper.find('.hidden-class')).toHaveLength(0);
+
+// ✅ Good - Testing observable behavior
+expect(screen.getByText('Visible content')).toBeInTheDocument();
+expect(screen.queryByText('Hidden content')).not.toBeInTheDocument();
+```
+
+### 2. Brittle Selectors
+
+```typescript
+// ❌ Bad - Fragile and non-semantic
+screen.getByClassName('btn-primary');
+container.querySelector('.form > div:nth-child(2)');
+
+// ✅ Good - Semantic and stable
+screen.getByRole('button', { name: 'Submit' });
+screen.getByLabelText('Email address');
+```
+
+### 3. Testing Multiple Concerns
+
+```typescript
+// ❌ Bad - Too many assertions in one test
+it('renders form and validates and submits and shows success', () => {
+  // Multiple unrelated assertions
+});
+
+// ✅ Good - Single responsibility
+it('renders form with all required fields', () => {});
+it('validates email format on blur', () => {});
+it('submits form with valid data', () => {});
+it('shows success message after submission', () => {});
+```
+
+## 📊 Coverage Standards
+
+### Coverage Thresholds
+
+| Component Type | Target | CI Blocking | Rationale |
+|----------------|--------|-------------|-----------|
+| **Utils/Hooks** | 95% | Yes | Core business logic, high reuse |
+| **UI Components** | 90% | Yes | User-facing, must be reliable |
+| **Services** | 85% | Yes | API interactions, critical paths |
+| **Validation** | 95% | Yes | Security and data integrity |
+| **Overall Project** | 82% | Yes | Quality baseline |
+
+### What to Test
+
+- ✅ **Happy paths** - Normal user workflows
+- ✅ **Error conditions** - Network failures, validation errors
+- ✅ **Edge cases** - Empty states, boundary values
+- ✅ **User interactions** - Clicks, form submissions, navigation
+- ✅ **State changes** - Loading states, data updates
+- ✅ **Accessibility** - Keyboard navigation, screen reader support
+
+### What NOT to Test
+
+- ❌ **Third-party libraries** - Already tested by maintainers
+- ❌ **Generated code** - Auto-generated types, configs
+- ❌ **Pure styling** - CSS classes without behavior
+- ❌ **Type definitions** - Interfaces and type-only exports
+
+## 🔐 RBAC Testing Patterns
+
+### Provider Testing
+
+```typescript
+describe('RBACProvider', () => {
+  it('requires organisation context when configured', () => {
+    const { result } = renderHook(() => useRBAC());
+    
+    expect(() => result.current.requireOrganisationContext()).toThrow(
+      'Organisation context is required'
+    );
+  });
+
+  it('refreshes permissions when event changes', async () => {
+    const { result } = renderHook(() => useRBAC());
+    
+    act(() => {
+      result.current.setSelectedEventId('new-event-id');
+    });
+    
+    await waitFor(() => {
+      expect(result.current.rbacLoading).toBe(false);
+    });
+  });
+});
+```
+
+### Permission Hook Testing
+
+```typescript
+describe('useHasPermission', () => {
+  it('returns true when user has required permission', async () => {
+    setupRBACMock([
+      { permission_type: 'read:users', role_name: 'viewer' }
+    ]);
+    
+    const { result } = renderHook(() => 
+      useHasPermission('user-123', scope, 'read:users')
+    );
+    
+    await waitFor(() => {
+      expect(result.current.hasPermission).toBe(true);
+    });
+  });
+});
+```
+
+## 🎨 Component-Specific Patterns
+
+### DataTable Testing Strategy
+
+DataTable subcomponents intentionally have low unit test coverage because they're comprehensively tested through integration tests. This is **correct and intentional**.
+
+```typescript
+// ✅ Good - Integration test for DataTable workflows
+describe('DataTable - Complete Workflow', () => {
+  it('allows editing, sorting, and filtering data', async () => {
+    const user = userEvent.setup();
+    
+    render(<DataTable data={mockData} onSave={mockSave} />);
+    
+    // Test editing
+    await user.click(screen.getByRole('button', { name: 'Edit' }));
+    await user.type(screen.getByRole('textbox'), 'Updated Value');
+    await user.click(screen.getByRole('button', { name: 'Save' }));
+    
+    // Test sorting
+    await user.click(screen.getByRole('columnheader', { name: 'Name' }));
+    
+    // Test filtering
+    await user.type(screen.getByPlaceholderText('Filter...'), 'search term');
+    
+    expect(mockSave).toHaveBeenCalledWith(expectedData);
+  });
+});
+```
+
+### Service Hook Testing
+
+```typescript
+describe('useEventService', () => {
+  it('throws error when used outside provider', () => {
+    expect(() => {
+      renderHook(() => useEventService());
+    }).toThrow('useEventService must be used within EventServiceProvider');
+  });
+
+  it('subscribes to service updates and cleans up', () => {
+    const unsubscribe = vi.fn();
+    const mockService = {
+      subscribe: vi.fn(() => unsubscribe)
+    };
+
+    const { unmount } = renderHook(() => useEventService(), {
+      wrapper: ({ children }) => (
+        <EventServiceContext.Provider value={{ eventService: mockService }}>
+          {children}
+        </EventServiceContext.Provider>
+      )
+    });
+
+    expect(mockService.subscribe).toHaveBeenCalled();
+    
+    unmount();
+    expect(unsubscribe).toHaveBeenCalled();
+  });
+});
+```
+
+## ⚡ Performance & Memory
+
+### Memory Leak Prevention
+
+```typescript
+describe('Component with Async Operations', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    // Prevent memory leaks
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    cleanup();
+    vi.clearAllMocks();
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+
+  it('handles cleanup properly', async () => {
+    // Test implementation
+  });
+});
+```
+
+### Async Testing Guidelines
+
+```typescript
+// ✅ Good - Appropriate timeouts based on operation speed
+await waitFor(() => {
+  expect(result.current.isLoading).toBe(false);
+}, { timeout: 100, interval: 10 }); // Fast operations
+
+await waitFor(() => {
+  expect(result.current.data).toBeDefined();
+}, { timeout: 5000 }); // Slow operations only
+```
+
+## 🔧 Test Configuration
+
+### Vitest Configuration
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    environmentOptions: {
+      jsdom: {
+        pretendToBeVisual: true, // Enables getComputedStyle
+        resources: 'usable'      // Enables resource loading
+      }
+    },
+    coverage: {
+      thresholds: {
+        lines: 82,
+        branches: 80,
+        functions: 80,
+        statements: 82
+      }
+    }
+  }
+});
+```
+
+### Test Utilities Setup
+
+```typescript
+// test-utils.tsx
+export function renderWithProviders(
+  ui: React.ReactElement,
+  options: { organisationId?: string } = {}
+) {
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <OrganisationProvider organisationId={options.organisationId}>
+        <RBACProvider>
+          {children}
+        </RBACProvider>
+      </OrganisationProvider>
+    );
+  }
+  
+  return render(ui, { wrapper: Wrapper, ...options });
+}
+```
+
+## 🚀 Running Tests
+
+### Commands
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test -- Button.test.tsx
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run tests with timeout (prevents hanging)
+timeout 60 npm test
+```
+
+### Debugging
+
+```typescript
+// Debug output
+screen.debug();
+
+// Debug specific element
+screen.debug(screen.getByRole('button'));
+
+// Log available queries
+screen.logTestingPlaygroundURL();
+```
+
+## 📋 Pre-Merge Checklist
+
+- [ ] All tests pass without `it.only` or `test.skip`
+- [ ] Coverage thresholds are met
+- [ ] Tests use semantic queries (avoid test IDs)
+- [ ] Async operations use proper waiting patterns
+- [ ] Mocks are cleaned up in `afterEach`
+- [ ] Tests focus on behavior, not implementation
+- [ ] Error scenarios are covered
+- [ ] Tests are colocated with source files
+
+## 🎯 Test Categories & Tags
+
+Use explicit tags for test organization:
+
+```typescript
+describe('[unit] useDebounce', () => {
+  it('delays function execution', () => {});
+});
+
+describe('[component] Button', () => {
+  it('renders with correct styling', () => {});
+});
+
+describe('[integration] User Registration', () => {
+  it('completes full signup flow', () => {});
+});
+```
+
+## 📚 Resources
+
+### Documentation
+- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)
+- [Vitest Documentation](https://vitest.dev/)
+- [Jest DOM Matchers](https://github.com/testing-library/jest-dom)
+
+### Internal Guides
+- [Documentation Standard](../../docs/DOCUMENTATION_STANDARD.md)
+- [Memory Performance Analysis](../../../MEMORY_PERFORMANCE_ANALYSIS.md)
+- [Test Failure Analysis](../../../TEST_FAILURE_ANALYSIS.md)
+
+---
+
+## 🎖️ Excellence Indicators
+
+A world-class test suite demonstrates:
+
+- **Comprehensive Coverage** - All critical paths tested
+- **Behavioral Focus** - Tests what users experience
+- **Maintainable Structure** - Easy to update and extend
+- **Fast Execution** - Quick feedback loops
+- **Clear Intent** - Tests serve as living documentation
+- **Reliable Results** - Consistent across environments
+- **Accessibility Awareness** - Tests include a11y considerations
+
+Remember: **Tests are not just about catching bugs—they're about building confidence, enabling refactoring, and documenting expected behavior for future developers.**

package/src/__tests__/helpers/test-utils.tsx

@@ -192,13 +192,14 @@ const createQueryBuilder = () => {
     sharedQueryBuilder = {
       select: vi.fn(() => sharedQueryBuilder),
       eq: vi.fn(() => sharedQueryBuilder),
+      in: vi.fn(() => Promise.resolve({ data: [], error: null })),
       single: vi.fn(() => Promise.resolve({ data: { id: 'test-app-id' }, error: null })),
       maybeSingle: vi.fn(() => Promise.resolve({ data: null, error: null })),
       order: vi.fn(() => sharedQueryBuilder),
       limit: vi.fn(() => Promise.resolve({ data: [], error: null })),
       insert: vi.fn(() => Promise.resolve({ data: null, error: null })),
-      update: vi.fn(() => Promise.resolve({ data: null, error: null })),
-      delete: vi.fn(() => Promise.resolve({ data: null, error: null })),
+      update: vi.fn(() => sharedQueryBuilder),
+      delete: vi.fn(() => sharedQueryBuilder),
     };
   }
   return sharedQueryBuilder;