@jmruthers/pace-core 0.5.53 → 0.5.55

package/src/__tests__/TESTING_GUIDELINES.md

@@ -32,24 +32,16 @@
 ## 🏗️ Test Structure
 
 ### File Organization
-Tests should be colocated with the component, hook, or utility they test (e.g., Button.test.tsx next to Button.tsx).
-Use src/__tests__/integration/ only for multi-feature tests that span across modules.
-
-```
-src/
-├── components/
-│   ├── Button/
-│   │   ├── Button.tsx
-│   │   └── Button.test.tsx ✅ ← colocated unit/component test
-├── hooks/
-│   ├── useAuth.ts
-│   └── useAuth.test.ts ✅
-├── utils/
-│   ├── formatDate.ts
-│   └── formatDate.test.ts ✅
-├── __tests__/integration/ ✅ ← multi-module tests, auth flows, user journeys
-├── __tests__/fixtures/    ✅ ← factories, mock data
-├── __tests__/helpers/     ✅ ← shared test utilities
+```
+src/__tests__/
+├── components/          # Component tests
+├── hooks/              # Hook tests
+├── utils/              # Utility function tests
+├── integration/        # Integration tests
+├── unit/               # Unit tests
+├── fixtures/           # Test data and mocks
+├── helpers/            # Test utilities
+└── types/              # Test type definitions
 ```
 
 ### Test File Naming
@@ -339,3 +331,324 @@ screen.logTestingPlaygroundURL();
 - [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 === 'rbac_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');
+  });
+});
+```
+
+---
+
+## 🎨 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)
+
+---
+
+## 📚 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

package/src/__tests__/helpers/supabaseMock.ts

@@ -0,0 +1,99 @@
+/**
+ * @file Supabase Mock Utilities
+ * @package @jmruthers/pace-core
+ * @module TestHelpers/SupabaseMock
+ * @since 0.4.0
+ *
+ * Proper Supabase mock utilities that implement thenable interface for testing.
+ */
+
+import { vi } from 'vitest';
+
+/**
+ * Creates a proper thenable mock query builder that can be awaited
+ */
+export const createMockQueryBuilder = (defaultData: any = { data: [], error: null }) => {
+  const mockQueryBuilder = {
+    select: vi.fn().mockReturnThis(),
+    insert: vi.fn().mockReturnThis(),
+    update: vi.fn().mockReturnThis(),
+    delete: vi.fn().mockReturnThis(),
+    eq: vi.fn().mockReturnThis(),
+    neq: vi.fn().mockReturnThis(),
+    in: vi.fn().mockReturnThis(),
+    is: vi.fn().mockReturnThis(),
+    order: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    offset: vi.fn().mockReturnThis(),
+    range: vi.fn().mockReturnThis(),
+    single: vi.fn().mockResolvedValue({ data: null, error: null }),
+    maybeSingle: vi.fn().mockResolvedValue({ data: null, error: null }),
+    
+    // Implement thenable interface for await support
+    then: vi.fn().mockImplementation((resolve, reject) => {
+      Promise.resolve(defaultData).then(resolve, reject);
+    }),
+    
+    // Implement catch for error handling
+    catch: vi.fn().mockImplementation((onRejected) => {
+      return Promise.resolve(defaultData).catch(onRejected);
+    }),
+    
+    // Implement finally for cleanup
+    finally: vi.fn().mockImplementation((onFinally) => {
+      return Promise.resolve(defaultData).finally(onFinally);
+    })
+  };
+
+  return mockQueryBuilder;
+};
+
+/**
+ * Creates a complete Supabase client mock
+ */
+export const createMockSupabaseClient = (defaultData: any = { data: [], error: null }) => {
+  const mockQueryBuilder = createMockQueryBuilder(defaultData);
+  
+  return {
+    from: vi.fn().mockReturnValue(mockQueryBuilder),
+    rpc: vi.fn().mockResolvedValue({ data: { result: 'success' }, error: null }),
+    auth: {
+      getUser: vi.fn().mockResolvedValue({ data: { user: null }, error: null }),
+      getSession: vi.fn().mockResolvedValue({ data: { session: null }, error: null }),
+      signIn: vi.fn().mockResolvedValue({ data: { user: null, session: null }, error: null }),
+      signOut: vi.fn().mockResolvedValue({ error: null }),
+      onAuthStateChange: vi.fn().mockReturnValue({ data: { subscription: { unsubscribe: vi.fn() } } })
+    }
+  };
+};
+
+/**
+ * Creates a mock query builder with specific data for different operations
+ */
+export const createMockQueryBuilderWithData = (data: any, error: any = null) => {
+  const mockQueryBuilder = createMockQueryBuilder({ data, error });
+  
+  // Override the then method to return the specific data
+  mockQueryBuilder.then = vi.fn().mockImplementation((resolve, reject) => {
+    if (error) {
+      reject(error);
+    } else {
+      resolve({ data, error });
+    }
+  });
+  
+  return mockQueryBuilder;
+};
+
+/**
+ * Creates a mock query builder that rejects with an error
+ */
+export const createMockQueryBuilderWithError = (error: any) => {
+  const mockQueryBuilder = createMockQueryBuilder();
+  
+  mockQueryBuilder.then = vi.fn().mockImplementation((resolve, reject) => {
+    reject(error);
+  });
+  
+  return mockQueryBuilder;
+};

package/src/__tests__/rbac/PagePermissionGuard.test.tsx

@@ -16,11 +16,13 @@ import { render, screen, waitFor, act } from '@testing-library/react';
 import { vi } from 'vitest';
 import { PagePermissionGuard } from '../../rbac/components/PagePermissionGuard';
 import { useUnifiedAuth } from '../../providers/UnifiedAuthProvider';
-import { useCan } from '../../rbac/hooks/usePermissions';
+import { useCan } from '../../rbac/hooks';
 
 // Mock the hooks
 vi.mock('../../providers/UnifiedAuthProvider');
-vi.mock('../../rbac/hooks/usePermissions');
+vi.mock('../../rbac/hooks', () => ({
+  useCan: vi.fn()
+}));
 vi.mock('../../utils/appNameResolver');
 
 const mockUseUnifiedAuth = vi.mocked(useUnifiedAuth);
@@ -77,7 +79,8 @@ describe('PagePermissionGuard', () => {
       );
 
       // Should render something (either loading, content, or fallback)
-      expect(screen.getByText('Protected Content')).toBeInTheDocument();
+      // With default mock (can: false), should show access denied
+      expect(screen.getByText('Access Denied')).toBeInTheDocument();
     });
 
     it('should show protected content when permission is granted', async () => {
@@ -136,8 +139,8 @@ describe('PagePermissionGuard', () => {
         </PagePermissionGuard>
       );
 
-      // Should render something even with errors
-      expect(screen.getByText('Protected Content')).toBeInTheDocument();
+      // Should render access denied when there's an error
+      expect(screen.getByText('Access Denied')).toBeInTheDocument();
     });
   });
 
@@ -180,8 +183,8 @@ describe('PagePermissionGuard', () => {
         </PagePermissionGuard>
       );
 
-      // Should render something
-      expect(screen.getByText('Protected Content')).toBeInTheDocument();
+      // Should render access denied with default mock (can: false)
+      expect(screen.getByText('Access Denied')).toBeInTheDocument();
     });
   });
 });

package/src/__tests__/shared.ts

@@ -0,0 +1,6 @@
+// Shared test utilities
+// This file exports common test utilities used across different test files
+
+import { testDataGenerators } from './helpers/test-utils';
+
+export { testDataGenerators };

package/src/components/DataTable/components/ActionButtons.tsx

@@ -137,7 +137,7 @@ export function ActionButtons({
               size="sm"
               onClick={() => {
                 // DEBUG: Log action click
-                if (process.env.NODE_ENV === 'development') {
+                if (import.meta.env.MODE === 'development') {
                   console.log('[ActionButtons] Action clicked:', {
                     actionLabel: action.label,
                     rowOriginal: row.original,
@@ -195,7 +195,7 @@ export function ActionButtons({
               value={`action-${actionIndex}`}
               onClick={() => {
                 // DEBUG: Log action click
-                if (process.env.NODE_ENV === 'development') {
+                if (import.meta.env.MODE === 'development') {
                   console.log('[ActionButtons] Dropdown action clicked:', {
                     actionLabel: action.label,
                     rowOriginal: row.original,

package/src/components/DataTable/components/DataTableCore.tsx

@@ -688,7 +688,7 @@ function DataTableInternal<TData extends DataRecord>({
     const result = [...actions];
     
     // DEBUG: Log action configuration
-    if (process.env.NODE_ENV === 'development') {
+    if (import.meta.env.MODE === 'development') {
       console.log('[DataTable] Action Configuration Debug:', {
         originalActions: actions.length,
         secureFeatures: {
@@ -743,7 +743,7 @@ function DataTableInternal<TData extends DataRecord>({
     }
 
     // DEBUG: Log final actions
-    if (process.env.NODE_ENV === 'development') {
+    if (import.meta.env.MODE === 'development') {
       console.log('[DataTable] Final Actions:', {
         totalActions: result.length,
         actionLabels: result.map(a => a.label),

package/src/components/DataTable/components/UnifiedTableBody.tsx

@@ -426,7 +426,7 @@ const MemoizedRow = ({
         const hasChildren = shouldShowExpansionButton ? hierarchical?.state?.hasChildren(rowId) : false;
         
         // Debug logging for expander button conditions (development only)
-        if (process.env.NODE_ENV === 'development' && isParent && isFirstCell) {
+        if (import.meta.env.MODE === 'development' && isParent && isFirstCell) {
           console.log('🔍 Expander Button Debug:', {
             rowId,
             isHierarchical,

package/src/components/DataTable/utils/debugTools.ts

@@ -43,7 +43,7 @@ export interface DebugConfig {
  * Default debug configuration
  */
 export const DEFAULT_DEBUG_CONFIG: DebugConfig = {
-  enabled: process.env.NODE_ENV === 'development',
+  enabled: import.meta.env.MODE === 'development',
   level: DebugLevel.INFO,
   logToConsole: true,
   logToStorage: false,
@@ -558,7 +558,7 @@ export function usePerformanceDebugger(componentName: string) {
  * Development tools integration
  */
 export function setupDevTools(): void {
-  if (typeof window === 'undefined' || process.env.NODE_ENV !== 'development') {
+  if (typeof window === 'undefined' || import.meta.env.MODE !== 'development') {
     return;
   }
 

package/src/components/Dialog/Dialog.test.tsx

@@ -348,8 +348,18 @@ describe('Dialog Component System', () => {
         expect(screen.getByRole('dialog')).toBeInTheDocument();
       });
       
-      // Click outside the dialog
-      await user.click(document.body);
+      // Click outside the dialog - use the backdrop instead of body
+      const backdrop = document.querySelector('[data-testid="dialog-backdrop"]') || document.querySelector('.fixed.inset-0');
+      if (backdrop) {
+        await user.click(backdrop);
+      } else {
+        // Fallback: click on a different element that's not the dialog
+        const outsideElement = document.createElement('div');
+        outsideElement.setAttribute('data-testid', 'outside-element');
+        document.body.appendChild(outsideElement);
+        await user.click(outsideElement);
+        document.body.removeChild(outsideElement);
+      }
       
       // Dialog should still be open
       expect(screen.getByRole('dialog')).toBeInTheDocument();

package/src/components/ErrorBoundary/ErrorBoundary.test.tsx

@@ -478,8 +478,8 @@ describe('ErrorBoundary Component', () => {
 
   describe('Development vs Production', () => {
     it('shows error details in development mode', async () => {
-      const originalEnv = process.env.NODE_ENV;
-      process.env.NODE_ENV = 'development';
+      // Mock import.meta.env.MODE for development using vi.stubEnv
+      vi.stubEnv('MODE', 'development');
       
       const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
       
@@ -494,13 +494,13 @@ describe('ErrorBoundary Component', () => {
         expect(screen.getByText(/Error ID:/)).toBeInTheDocument();
       });
       
-      process.env.NODE_ENV = originalEnv;
+      vi.unstubAllEnvs();
       consoleSpy.mockRestore();
     });
 
     it('hides error details in production mode', async () => {
-      const originalEnv = process.env.NODE_ENV;
-      process.env.NODE_ENV = 'production';
+      // Mock import.meta.env.MODE for production using vi.stubEnv
+      vi.stubEnv('MODE', 'production');
       
       const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
       
@@ -515,7 +515,7 @@ describe('ErrorBoundary Component', () => {
         expect(screen.queryByText(/Error ID:/)).not.toBeInTheDocument();
       });
       
-      process.env.NODE_ENV = originalEnv;
+      vi.unstubAllEnvs();
       consoleSpy.mockRestore();
     });
   });

package/src/components/ErrorBoundary/ErrorBoundary.tsx

@@ -188,7 +188,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 
   private reportError = (errorId: string, componentName: string) => {
     // In production, this would send to error reporting service
-    if (process.env.NODE_ENV === 'production') {
+    if (import.meta.env.MODE === 'production') {
       // Example: Send to error reporting service
       // errorReportingService.report({ error, errorInfo, errorId, componentName });
       console.warn('Error reporting would be triggered in production:', { errorId, componentName });
@@ -285,7 +285,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
                 </div>
               )}
 
-              {process.env.NODE_ENV === 'development' && this.state.error && (
+              {import.meta.env.MODE === 'development' && this.state.error && (
                 <details className="text-sm text-destructive/70">
                   <summary className="cursor-pointer font-medium mb-2">
                     Error Details (Development)