@jmruthers/pace-core 0.4.1 → 0.5.1

package/src/__tests__/TESTING_GUIDELINES.md

@@ -0,0 +1,341 @@
+# 🧪 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)
+
+## 🎯 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
+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
+```
+
+### 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
+
+## 🚀 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)

package/src/__tests__/fixtures/mocks.ts

@@ -0,0 +1,93 @@
+/**
+ * @file Test Mocks and Fixtures
+ * @description Centralized mocks and test data
+ */
+
+import { vi } from 'vitest';
+
+// API Mocks
+export const apiMocks = {
+  success: (data: any) => Promise.resolve({ data, status: 200 }),
+  error: (message = 'API Error') => Promise.reject(new Error(message)),
+  loading: () => new Promise(() => {}), // Never resolves
+};
+
+// React Query Mocks
+export const queryMocks = {
+  useQuery: vi.fn(),
+  useMutation: vi.fn(),
+  useQueryClient: vi.fn(),
+};
+
+// Router Mocks
+export const routerMocks = {
+  useNavigate: vi.fn(),
+  useLocation: vi.fn(() => ({ pathname: '/', search: '', hash: '', state: null })),
+  useParams: vi.fn(() => ({})),
+};
+
+// Local Storage Mock
+export const localStorageMock = {
+  getItem: vi.fn(),
+  setItem: vi.fn(),
+  removeItem: vi.fn(),
+  clear: vi.fn(),
+};
+
+// Window Mocks
+export const windowMocks = {
+  matchMedia: vi.fn(() => ({
+    matches: false,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+  })),
+  scrollTo: vi.fn(),
+  getComputedStyle: vi.fn(() => ({
+    getPropertyValue: vi.fn().mockReturnValue(''),
+  })),
+};
+
+// Test Data
+export const testData = {
+  users: [
+    { id: '1', name: 'John Doe', email: 'john@example.com' },
+    { id: '2', name: 'Jane Smith', email: 'jane@example.com' },
+  ],
+  
+  products: [
+    { id: '1', name: 'Product 1', price: 10.99 },
+    { id: '2', name: 'Product 2', price: 19.99 },
+  ],
+  
+  events: [
+    { id: '1', title: 'Event 1', date: '2024-01-01' },
+    { id: '2', title: 'Event 2', date: '2024-01-02' },
+  ],
+};
+
+// Mock Functions
+export const mockFunctions = {
+  console: {
+    log: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+  
+  timers: {
+    setTimeout: vi.fn(),
+    clearTimeout: vi.fn(),
+    setInterval: vi.fn(),
+    clearInterval: vi.fn(),
+  },
+  
+  fetch: vi.fn(),
+  
+  // Custom mock creators
+  createMock: <T extends (...args: any[]) => any>(implementation?: T) => {
+    return vi.fn(implementation) as T & ReturnType<typeof vi.fn>;
+  },
+  
+  createAsyncMock: <T extends (...args: any[]) => Promise<any>>(implementation?: T) => {
+    return vi.fn(implementation) as T & ReturnType<typeof vi.fn>;
+  },
+};

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

@@ -0,0 +1,145 @@
+/**
+ * @file Component Test Utilities
+ * @description Specialized utilities for component testing
+ */
+
+import { render, screen, RenderResult } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { vi } from 'vitest';
+import { renderWithProviders } from './test-utils';
+
+// Component test patterns
+export const componentTestPatterns = {
+  // Test component renders without crashing
+  testRenders: (Component: React.ComponentType<any>, props = {}) => {
+    return () => {
+      renderWithProviders(<Component {...props} />);
+      expect(screen.getByRole('generic')).toBeInTheDocument();
+    };
+  },
+  
+  // Test component handles props correctly
+  testProps: (Component: React.ComponentType<any>, testCases: Array<{
+    name: string;
+    props: Record<string, any>;
+    expectedBehavior: () => void;
+  }>) => {
+    return testCases.map(({ name, props, expectedBehavior }) => ({
+      name: `handles ${name}`,
+      test: () => {
+        renderWithProviders(<Component {...props} />);
+        expectedBehavior();
+      },
+    }));
+  },
+  
+  // Test component handles events
+  testEvents: (Component: React.ComponentType<any>, eventTests: Array<{
+    name: string;
+    action: (element: HTMLElement) => Promise<void>;
+    expectedBehavior: () => void;
+  }>) => {
+    return eventTests.map(({ name, action, expectedBehavior }) => ({
+      name: `handles ${name}`,
+      test: async () => {
+        const user = userEvent.setup();
+        renderWithProviders(<Component />);
+        
+        const element = screen.getByRole('button');
+        await action(element);
+        expectedBehavior();
+      },
+    }));
+  },
+  
+  // Test accessibility
+  testAccessibility: (Component: React.ComponentType<any>, props = {}) => {
+    return () => {
+      renderWithProviders(<Component {...props} />);
+      
+      // Basic accessibility checks
+      const element = screen.getByRole('button');
+      expect(element).toBeInTheDocument();
+      expect(element).toBeVisible();
+    };
+  },
+};
+
+// Common component test scenarios
+export const commonScenarios = {
+  // Button component scenarios
+  button: {
+    renders: (Component: React.ComponentType<any>) => [
+      {
+        name: 'renders with text',
+        test: () => {
+          renderWithProviders(<Component>Click me</Component>);
+          expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
+        },
+      },
+      {
+        name: 'handles click events',
+        test: async () => {
+          const handleClick = vi.fn();
+          const user = userEvent.setup();
+          renderWithProviders(<Component onClick={handleClick}>Click me</Component>);
+          
+          await user.click(screen.getByRole('button'));
+          expect(handleClick).toHaveBeenCalledTimes(1);
+        },
+      },
+      {
+        name: 'can be disabled',
+        test: () => {
+          renderWithProviders(<Component disabled>Disabled</Component>);
+          expect(screen.getByRole('button')).toBeDisabled();
+        },
+      },
+    ],
+  },
+  
+  // Form component scenarios
+  form: {
+    renders: (Component: React.ComponentType<any>) => [
+      {
+        name: 'renders form elements',
+        test: () => {
+          renderWithProviders(<Component />);
+          expect(screen.getByRole('form')).toBeInTheDocument();
+        },
+      },
+      {
+        name: 'handles form submission',
+        test: async () => {
+          const handleSubmit = vi.fn();
+          const user = userEvent.setup();
+          renderWithProviders(<Component onSubmit={handleSubmit} />);
+          
+          await user.click(screen.getByRole('button', { name: /submit/i }));
+          expect(handleSubmit).toHaveBeenCalledTimes(1);
+        },
+      },
+    ],
+  },
+};
+
+// Test data factories
+export const createTestData = {
+  button: (overrides = {}) => ({
+    children: 'Test Button',
+    onClick: vi.fn(),
+    ...overrides,
+  }),
+  
+  form: (overrides = {}) => ({
+    onSubmit: vi.fn(),
+    ...overrides,
+  }),
+  
+  user: (overrides = {}) => ({
+    id: '1',
+    name: 'Test User',
+    email: 'test@example.com',
+    ...overrides,
+  }),
+};

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

@@ -0,0 +1,117 @@
+/**
+ * @file Test Utilities
+ * @description Comprehensive testing utilities and helpers
+ */
+
+import React, { ReactElement } from 'react';
+import { render, RenderOptions } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { vi } from 'vitest';
+
+// Mock providers for testing
+const createTestQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        cacheTime: 0,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  });
+
+// Custom render function with providers
+interface CustomRenderOptions extends Omit<RenderOptions, 'wrapper'> {
+  queryClient?: QueryClient;
+  withQueryClient?: boolean;
+}
+
+export function renderWithProviders(
+  ui: ReactElement,
+  options: CustomRenderOptions = {}
+): ReturnType<typeof render> {
+  const {
+    queryClient = createTestQueryClient(),
+    withQueryClient = true,
+    ...renderOptions
+  } = options;
+
+  const Wrapper = ({ children }: { children: React.ReactNode }) => {
+    if (withQueryClient) {
+      return (
+        <QueryClientProvider client={queryClient}>
+          {children}
+        </QueryClientProvider>
+      );
+    }
+    return <>{children}</>;
+  };
+
+  return render(ui, { wrapper: Wrapper, ...renderOptions });
+}
+
+// Re-export everything from testing-library
+export * from '@testing-library/react';
+export { userEvent };
+
+// Mock data generators
+export const mockData = {
+  user: (overrides = {}) => ({
+    id: '1',
+    email: 'test@example.com',
+    name: 'Test User',
+    ...overrides,
+  }),
+  
+  button: (overrides = {}) => ({
+    children: 'Click me',
+    onClick: vi.fn(),
+    ...overrides,
+  }),
+  
+  form: (overrides = {}) => ({
+    onSubmit: vi.fn(),
+    ...overrides,
+  }),
+};
+
+// Common test helpers
+export const testHelpers = {
+  // Wait for async operations
+  waitFor: (callback: () => void, timeout = 1000) => {
+    return new Promise((resolve, reject) => {
+      const startTime = Date.now();
+      
+      const check = () => {
+        try {
+          callback();
+          resolve(undefined);
+        } catch (error) {
+          if (Date.now() - startTime > timeout) {
+            reject(error);
+          } else {
+            setTimeout(check, 10);
+          }
+        }
+      };
+      
+      check();
+    });
+  },
+  
+  // Mock function with better typing
+  createMockFn: <T extends (...args: any[]) => any>(implementation?: T) => {
+    return vi.fn(implementation) as T & ReturnType<typeof vi.fn>;
+  },
+  
+  // Generate test props
+  createTestProps: <T extends Record<string, any>>(defaults: T) => {
+    return (overrides: Partial<T> = {}) => ({
+      ...defaults,
+      ...overrides,
+    });
+  },
+};