@jmruthers/pace-core 0.4.1 → 0.5.1

package/src/__tests__/integration/UserProfile.test.tsx

@@ -0,0 +1,128 @@
+/**
+ * @file User Profile Integration Tests
+ * @description Example integration test patterns
+ */
+
+import React from 'react';
+import { screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderWithProviders } from '../helpers/test-utils';
+import { testData } from '../fixtures/mocks';
+
+// Mock components for demonstration
+const UserProfile = ({ userId }: { userId: string }) => {
+  const [user, setUser] = React.useState<any>(null);
+  const [loading, setLoading] = React.useState(true);
+  const [error, setError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    // Simulate API call
+    const fetchUser = async () => {
+      try {
+        setLoading(true);
+        const userData = testData.users.find(u => u.id === userId);
+        if (userData) {
+          setUser(userData);
+        } else {
+          setError('User not found');
+        }
+      } catch (err) {
+        setError('Failed to fetch user');
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchUser();
+  }, [userId]);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+  if (!user) return <div>No user found</div>;
+
+  return (
+    <div data-testid="user-profile">
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+      <button onClick={() => setUser({ ...user, name: 'Updated Name' })}>
+        Update Name
+      </button>
+    </div>
+  );
+};
+
+describe('User Profile Integration Tests', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Data Loading', () => {
+    it('loads and displays user data', async () => {
+      renderWithProviders(<UserProfile userId="1" />);
+      
+      // The component loads data synchronously in this mock, so we just check the final state
+      await waitFor(() => {
+        expect(screen.getByText('John Doe')).toBeInTheDocument();
+      });
+      
+      expect(screen.getByText('john@example.com')).toBeInTheDocument();
+    });
+
+    it('handles user not found', async () => {
+      renderWithProviders(<UserProfile userId="999" />);
+      
+      await waitFor(() => {
+        expect(screen.getByText('Error: User not found')).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe('User Interactions', () => {
+    it('allows updating user name', async () => {
+      const user = userEvent.setup();
+      renderWithProviders(<UserProfile userId="1" />);
+      
+      await waitFor(() => {
+        expect(screen.getByText('John Doe')).toBeInTheDocument();
+      });
+      
+      await user.click(screen.getByText('Update Name'));
+      
+      expect(screen.getByText('Updated Name')).toBeInTheDocument();
+      expect(screen.queryByText('John Doe')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Component State Management', () => {
+    it('maintains state across re-renders', async () => {
+      const { rerender } = renderWithProviders(<UserProfile userId="1" />);
+      
+      await waitFor(() => {
+        expect(screen.getByText('John Doe')).toBeInTheDocument();
+      });
+      
+      rerender(<UserProfile userId="1" />);
+      
+      expect(screen.getByText('John Doe')).toBeInTheDocument();
+    });
+  });
+});
+
+// Example of testing with different user IDs
+describe('User Profile - Different Users', () => {
+  const testCases = [
+    { userId: '1', expectedName: 'John Doe' },
+    { userId: '2', expectedName: 'Jane Smith' },
+  ];
+
+  testCases.forEach(({ userId, expectedName }) => {
+    it(`displays correct data for user ${userId}`, async () => {
+      renderWithProviders(<UserProfile userId={userId} />);
+      
+      await waitFor(() => {
+        expect(screen.getByText(expectedName)).toBeInTheDocument();
+      });
+    });
+  });
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,71 @@
+/**
+ * @file Test Setup Configuration
+ * @description Global test setup, mocks, and utilities
+ */
+
+import '@testing-library/jest-dom';
+import { vi } from 'vitest';
+import { cleanup } from '@testing-library/react';
+
+// Global test setup
+beforeEach(() => {
+  // Clear all mocks before each test
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  // Clean up DOM after each test
+  cleanup();
+});
+
+// Mock console methods to reduce noise in tests
+global.console = {
+  ...console,
+  // Uncomment to suppress console.log in tests
+  // log: vi.fn(),
+  // warn: vi.fn(),
+  // error: vi.fn(),
+};
+
+// Mock IntersectionObserver
+global.IntersectionObserver = vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn(),
+}));
+
+// Mock ResizeObserver
+global.ResizeObserver = vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn(),
+}));
+
+// Mock matchMedia
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: vi.fn().mockImplementation(query => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  })),
+});
+
+// Mock scrollTo
+Object.defineProperty(window, 'scrollTo', {
+  writable: true,
+  value: vi.fn(),
+});
+
+// Mock getComputedStyle
+Object.defineProperty(window, 'getComputedStyle', {
+  writable: true,
+  value: vi.fn().mockImplementation(() => ({
+    getPropertyValue: vi.fn().mockReturnValue(''),
+  })),
+});

package/src/__tests__/templates/accessibility.test.template.tsx

@@ -0,0 +1,279 @@
+
+/**
+ * @file Template for accessibility tests
+ * Copy this file and replace ComponentName with your actual component
+ * 
+ * Instructions:
+ * 1. Copy this file to your component's __tests__ folder
+ * 2. Rename to YourComponent.accessibility.test.tsx
+ * 3. Replace all instances of "ComponentName" with your actual component name
+ * 4. Uncomment and fix the import paths below
+ * 5. Customize the tests for your component's accessibility requirements
+ */
+
+// Uncomment and update these imports for your component:
+// import React from 'react';
+// import { render, screen, within } from '@testing-library/react';
+// import userEvent from '@testing-library/user-event';
+// import { describe, it, expect, vi, beforeEach } from 'vitest';
+// import { ComponentName } from '../ComponentName';
+// import { renderWithProviders } from '../../utils/renderHelpers';
+
+/*
+describe('ComponentName Accessibility Tests', () => {
+  const user = userEvent.setup();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Semantic Structure', () => {
+    it('has proper semantic HTML', () => {
+      renderWithProviders(<ComponentName>Content</ComponentName>);
+      
+      // Check for proper semantic elements
+      expect(screen.getByRole('main')).toBeInTheDocument();
+      // or: expect(screen.getByRole('button')).toBeInTheDocument();
+      // or: expect(screen.getByRole('textbox')).toBeInTheDocument();
+    });
+
+    it('has proper heading hierarchy', () => {
+      renderWithProviders(<ComponentName title="Main Title" subtitle="Subtitle" />);
+      
+      const mainHeading = screen.getByRole('heading', { level: 1 });
+      const subHeading = screen.getByRole('heading', { level: 2 });
+      
+      expect(mainHeading).toHaveTextContent('Main Title');
+      expect(subHeading).toHaveTextContent('Subtitle');
+    });
+  });
+
+  describe('ARIA Attributes', () => {
+    it('has proper ARIA labels', () => {
+      renderWithProviders(<ComponentName aria-label="Component description" />);
+      
+      const component = screen.getByLabelText('Component description');
+      expect(component).toBeInTheDocument();
+    });
+
+    it('has proper ARIA roles', () => {
+      renderWithProviders(<ComponentName role="dialog" />);
+      
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
+    });
+
+    it('uses ARIA describedby for additional information', () => {
+      renderWithProviders(
+        <ComponentName 
+          aria-describedby="help-text"
+          helperText="This is helpful information"
+        />
+      );
+      
+      const component = screen.getByRole('main'); // adjust role as needed
+      const helpText = screen.getByText('This is helpful information');
+      
+      expect(component).toHaveAttribute('aria-describedby', 'help-text');
+      expect(helpText).toHaveAttribute('id', 'help-text');
+    });
+
+    it('announces state changes', async () => {
+      renderWithProviders(<ComponentName />);
+      
+      const button = screen.getByRole('button');
+      await user.click(button);
+      
+      // Check for live region announcements
+      const status = screen.getByRole('status');
+      expect(status).toHaveAttribute('aria-live', 'polite');
+    });
+  });
+
+  describe('Keyboard Navigation', () => {
+    it('supports tab navigation', async () => {
+      renderWithProviders(
+        <div>
+          <ComponentName />
+          <button>Next focusable element</button>
+        </div>
+      );
+
+      const firstElement = screen.getByRole('button', { name: /component/i });
+      const secondElement = screen.getByRole('button', { name: /next focusable/i });
+
+      firstElement.focus();
+      expect(firstElement).toHaveFocus();
+
+      await user.tab();
+      expect(secondElement).toHaveFocus();
+    });
+
+    it('supports Enter and Space key activation', async () => {
+      const handleClick = vi.fn();
+      renderWithProviders(<ComponentName onClick={handleClick} />);
+
+      const element = screen.getByRole('button');
+      element.focus();
+
+      await user.keyboard('[Enter]');
+      expect(handleClick).toHaveBeenCalledTimes(1);
+
+      await user.keyboard('[Space]');
+      expect(handleClick).toHaveBeenCalledTimes(2);
+    });
+
+    it('supports arrow key navigation for menus', async () => {
+      renderWithProviders(<ComponentName type="menu" />);
+
+      const menu = screen.getByRole('menu');
+      const menuItems = within(menu).getAllByRole('menuitem');
+
+      menuItems[0].focus();
+      expect(menuItems[0]).toHaveFocus();
+
+      await user.keyboard('[ArrowDown]');
+      expect(menuItems[1]).toHaveFocus();
+
+      await user.keyboard('[ArrowUp]');
+      expect(menuItems[0]).toHaveFocus();
+    });
+
+    it('traps focus in modal dialogs', async () => {
+      renderWithProviders(<ComponentName isModal open />);
+
+      const dialog = screen.getByRole('dialog');
+      const focusableElements = within(dialog).getAllByRole('button');
+
+      // Focus should be trapped within modal
+      focusableElements[0].focus();
+      
+      // Tab through all focusable elements
+      for (let i = 1; i < focusableElements.length; i++) {
+        await user.tab();
+        expect(focusableElements[i]).toHaveFocus();
+      }
+
+      // Should wrap back to first element
+      await user.tab();
+      expect(focusableElements[0]).toHaveFocus();
+    });
+
+    it('supports Escape key to close modals', async () => {
+      const handleClose = vi.fn();
+      renderWithProviders(<ComponentName isModal open onClose={handleClose} />);
+
+      await user.keyboard('[Escape]');
+      expect(handleClose).toHaveBeenCalled();
+    });
+  });
+
+  describe('Screen Reader Support', () => {
+    it('provides meaningful text alternatives for images', () => {
+      renderWithProviders(<ComponentName image="/test.jpg" alt="Descriptive alt text" />);
+      
+      const image = screen.getByRole('img');
+      expect(image).toHaveAttribute('alt', 'Descriptive alt text');
+    });
+
+    it('uses proper form labels', () => {
+      renderWithProviders(<ComponentName type="form" />);
+      
+      const input = screen.getByLabelText('Input Label');
+      expect(input).toBeInTheDocument();
+    });
+
+    it('announces loading states', () => {
+      renderWithProviders(<ComponentName isLoading />);
+      
+      const loadingIndicator = screen.getByRole('status');
+      expect(loadingIndicator).toHaveAttribute('aria-live', 'polite');
+      expect(loadingIndicator).toHaveTextContent(/loading/i);
+    });
+
+    it('announces error states', () => {
+      renderWithProviders(<ComponentName error="Something went wrong" />);
+      
+      const errorAlert = screen.getByRole('alert');
+      expect(errorAlert).toHaveAttribute('aria-live', 'assertive');
+      expect(errorAlert).toHaveTextContent('Something went wrong');
+    });
+  });
+
+  describe('Color and Contrast', () => {
+    it('does not rely solely on color for information', () => {
+      renderWithProviders(<ComponentName status="error" />);
+      
+      // Should have text indicator, not just color
+      expect(screen.getByText(/error/i)).toBeInTheDocument();
+    });
+
+    it('maintains focus indicators', async () => {
+      renderWithProviders(<ComponentName />);
+      
+      const element = screen.getByRole('button');
+      element.focus();
+      
+      // Focus should be visible (actual contrast testing would require visual testing tools)
+      expect(element).toHaveFocus();
+    });
+  });
+
+  describe('Form Accessibility', () => {
+    it('associates form controls with labels', () => {
+      renderWithProviders(<ComponentName type="form" />);
+      
+      const input = screen.getByLabelText('Required Field');
+      expect(input).toHaveAttribute('required');
+      expect(input).toHaveAttribute('aria-required', 'true');
+    });
+
+    it('provides validation feedback', async () => {
+      renderWithProviders(<ComponentName type="form" />);
+      
+      const input = screen.getByLabelText('Email');
+      await user.type(input, 'invalid-email');
+      
+      const errorMessage = await screen.findByRole('alert');
+      expect(errorMessage).toHaveTextContent(/invalid email/i);
+      expect(input).toHaveAttribute('aria-describedby', expect.stringContaining('error'));
+    });
+
+    it('groups related form controls', () => {
+      renderWithProviders(<ComponentName type="form" />);
+      
+      const fieldset = screen.getByRole('group');
+      const legend = within(fieldset).getByText('Contact Information');
+      
+      expect(fieldset).toContainElement(legend);
+    });
+  });
+
+  describe('Dynamic Content', () => {
+    it('announces dynamic content changes', async () => {
+      renderWithProviders(<ComponentName />);
+      
+      const button = screen.getByRole('button', { name: /load more/i });
+      await user.click(button);
+      
+      // Check for announcement of new content
+      const announcement = await screen.findByRole('status');
+      expect(announcement).toHaveTextContent(/content loaded/i);
+    });
+
+    it('maintains focus after content updates', async () => {
+      renderWithProviders(<ComponentName />);
+      
+      const trigger = screen.getByRole('button');
+      trigger.focus();
+      
+      await user.click(trigger);
+      
+      // Focus should remain on trigger or move to logical next element
+      expect(document.activeElement).toBe(trigger);
+    });
+  });
+});
+*/
+
+// This file is a template - copy and uncomment the code above to use it
+export {};

package/src/__tests__/templates/component.test.template.tsx

@@ -0,0 +1,144 @@
+/**
+ * @file Component Test Template
+ * @description Template for creating component tests
+ * @usage Copy this template and replace ComponentName with your component
+ */
+
+import React from 'react';
+import { screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ComponentName } from '../../components/ComponentName/ComponentName';
+import { renderWithProviders } from '../helpers/test-utils';
+
+describe('ComponentName Component', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // Basic rendering tests
+  describe('Rendering', () => {
+    it('renders with default props', () => {
+      renderWithProviders(<ComponentName />);
+      expect(screen.getByRole('generic')).toBeInTheDocument();
+    });
+
+    it('renders with custom props', () => {
+      renderWithProviders(<ComponentName customProp="value" />);
+      expect(screen.getByRole('generic')).toBeInTheDocument();
+    });
+
+    it('renders with children', () => {
+      renderWithProviders(
+        <ComponentName>
+          <span>Child content</span>
+        </ComponentName>
+      );
+      expect(screen.getByText('Child content')).toBeInTheDocument();
+    });
+  });
+
+  // Event handling tests
+  describe('Event Handling', () => {
+    it('handles click events', async () => {
+      const handleClick = vi.fn();
+      const user = userEvent.setup();
+      
+      renderWithProviders(<ComponentName onClick={handleClick} />);
+      
+      await user.click(screen.getByRole('generic'));
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('handles keyboard events', async () => {
+      const handleKeyDown = vi.fn();
+      const user = userEvent.setup();
+      
+      renderWithProviders(<ComponentName onKeyDown={handleKeyDown} />);
+      
+      screen.getByRole('generic').focus();
+      await user.keyboard('{Enter}');
+      expect(handleKeyDown).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  // State management tests
+  describe('State Management', () => {
+    it('handles controlled state', () => {
+      const { rerender } = renderWithProviders(
+        <ComponentName value="initial" />
+      );
+      
+      expect(screen.getByDisplayValue('initial')).toBeInTheDocument();
+      
+      rerender(<ComponentName value="updated" />);
+      expect(screen.getByDisplayValue('updated')).toBeInTheDocument();
+    });
+
+    it('handles uncontrolled state', () => {
+      renderWithProviders(<ComponentName defaultValue="default" />);
+      expect(screen.getByDisplayValue('default')).toBeInTheDocument();
+    });
+  });
+
+  // Accessibility tests
+  describe('Accessibility', () => {
+    it('has proper ARIA attributes', () => {
+      renderWithProviders(<ComponentName aria-label="Test component" />);
+      expect(screen.getByRole('generic')).toHaveAttribute('aria-label', 'Test component');
+    });
+
+    it('is keyboard accessible', () => {
+      renderWithProviders(<ComponentName />);
+      expect(screen.getByRole('generic')).not.toHaveAttribute('tabindex', '-1');
+    });
+
+    it('supports screen readers', () => {
+      renderWithProviders(<ComponentName />);
+      // Add specific screen reader tests here
+    });
+  });
+
+  // Error handling tests
+  describe('Error Handling', () => {
+    it('handles invalid props gracefully', () => {
+      // @ts-expect-error Testing invalid prop
+      renderWithProviders(<ComponentName invalidProp="test" />);
+      expect(screen.getByRole('generic')).toBeInTheDocument();
+    });
+
+    it('displays error states', () => {
+      renderWithProviders(<ComponentName error="Something went wrong" />);
+      expect(screen.getByText('Something went wrong')).toBeInTheDocument();
+    });
+  });
+
+  // Integration tests
+  describe('Integration', () => {
+    it('works with other components', () => {
+      renderWithProviders(
+        <div>
+          <ComponentName />
+          <ComponentName />
+        </div>
+      );
+      
+      expect(screen.getAllByRole('generic')).toHaveLength(2);
+    });
+
+    it('works with forms', async () => {
+      const handleSubmit = vi.fn((e) => e.preventDefault());
+      const user = userEvent.setup();
+      
+      renderWithProviders(
+        <form onSubmit={handleSubmit}>
+          <ComponentName />
+          <button type="submit">Submit</button>
+        </form>
+      );
+      
+      await user.click(screen.getByRole('button', { name: 'Submit' }));
+      expect(handleSubmit).toHaveBeenCalledTimes(1);
+    });
+  });
+});