@jmruthers/pace-core 0.5.114 → 0.5.116

package/src/__tests__/TEST_STANDARD.md

@@ -329,6 +329,19 @@ expect(screen.getByText('Visible content')).toBeInTheDocument();
 expect(screen.queryByText('Hidden content')).not.toBeInTheDocument();
 ```
 
+### 2. Skipped Tests Without Documentation
+
+```typescript
+// ❌ Bad - Skipped test without explanation
+it.skip('should navigate with keyboard', () => {});
+
+// ✅ Good - Skipped test with clear documentation
+// TODO: Enable when keyboard navigation is implemented
+// See: https://github.com/org/repo/issues/123
+// Expected: Q2 2025
+it.skip('should navigate with keyboard', () => {});
+```
+
 ### 2. Brittle Selectors
 
 ```typescript
@@ -530,9 +543,24 @@ await waitFor(() => {
 
 await waitFor(() => {
   expect(result.current.data).toBeDefined();
-}, { timeout: 5000 }); // Slow operations only
+}, { timeout: 2000 }); // Most async operations (2-3 seconds)
+
+// ⚠️ Only use 5+ seconds for truly slow operations
+await waitFor(() => {
+  expect(result.current.data).toBeDefined();
+}, { timeout: 5000 }); // Network calls, complex computations only
 ```
 
+**Timeout Guidelines**:
+- **Fast operations** (< 100ms): `timeout: 100-500`
+- **Standard async** (100ms-2s): `timeout: 2000-3000`
+- **Slow operations** (2s+): `timeout: 5000+` (with documentation)
+
+**Avoid**:
+- ❌ Using 5-6 second timeouts for mock operations that resolve immediately
+- ❌ Using `waitFor` for synchronous operations
+- ❌ Unnecessary delays in mock implementations
+
 ## 🔧 Test Configuration
 
 ### Vitest Configuration
@@ -618,7 +646,7 @@ screen.logTestingPlaygroundURL();
 
 ## 📋 Pre-Merge Checklist
 
-- [ ] All tests pass without `it.only` or `test.skip`
+- [ ] All tests pass without `it.only` or `test.skip` (see Skipped Test Policy below)
 - [ ] Coverage thresholds are met
 - [ ] Tests use semantic queries (avoid test IDs)
 - [ ] Async operations use proper waiting patterns
@@ -626,6 +654,7 @@ screen.logTestingPlaygroundURL();
 - [ ] Tests focus on behavior, not implementation
 - [ ] Error scenarios are covered
 - [ ] Tests are colocated with source files
+- [ ] Timeout values are appropriate (see Performance Guidelines below)
 
 ## 🎯 Test Categories & Tags
 
@@ -672,3 +701,216 @@ A world-class test suite demonstrates:
 - **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.**
+
+---
+
+## 🔄 Skipped Test Policy
+
+### When to Skip Tests
+
+**✅ Appropriate Reasons**:
+- Feature is planned but not yet implemented
+- Test documents future feature requirements
+- Feature is blocked by dependencies
+- Test is for experimental/optional feature
+
+**❌ Inappropriate Reasons**:
+- Test is flaky (fix the test instead)
+- Test is slow (optimize instead)
+- Feature is deprecated (remove test)
+- Test is temporarily broken (fix immediately)
+
+### Requirements for Skipped Tests
+
+1. **Clear Documentation**: Add comment explaining why test is skipped
+2. **Reference Tracking**: Link to feature issue or ticket
+3. **Expected Timeline**: Include expected implementation date (if known)
+4. **Quarterly Review**: Review skipped tests quarterly to determine if still relevant
+
+### Example
+
+```typescript
+// TODO: Enable when keyboard navigation is implemented
+// See: https://github.com/org/repo/issues/123
+// Expected: Q2 2025
+it.skip('should navigate between headers with arrow keys', async () => {
+  // Test implementation
+});
+```
+
+### Skipped Test Review Process
+
+1. **Quarterly Audit**: Review all skipped tests
+2. **Decision Matrix**:
+   - Feature implemented → Enable test
+   - Feature cancelled → Remove test
+   - Feature deferred → Update timeline
+   - Still relevant → Keep skipped with updated timeline
+3. **Documentation**: Update test comments with current status
+
+---
+
+## 📊 Coverage Gap Remediation
+
+### Coverage Thresholds
+
+| Category | 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** | 80% | Yes | Quality baseline |
+
+### Identifying Coverage Gaps
+
+1. **Run Coverage Report**:
+   ```bash
+   npm test -- --coverage
+   ```
+
+2. **Review Coverage Report**:
+   - Check per-file coverage percentages
+   - Identify files below thresholds
+   - Review uncovered lines/branches
+
+3. **Prioritize Gaps**:
+   - **Critical**: RBAC, auth, services
+   - **High**: Business logic, hooks
+   - **Medium**: UI components, utilities
+   - **Low**: Type definitions, simple utilities
+
+### Remediation Process
+
+1. **Analyze Gap**: Understand what's not covered
+2. **Create Test Plan**: Determine test type (unit, integration)
+3. **Write Tests**: Follow TEST_STANDARD.md patterns
+4. **Verify Coverage**: Run coverage report to confirm improvement
+5. **Document**: Add comments for complex test scenarios
+
+### Coverage Improvement Checklist
+
+- [ ] Identify files below thresholds
+- [ ] Prioritize critical paths
+- [ ] Create test plan for each file
+- [ ] Write tests following TEST_STANDARD.md
+- [ ] Verify coverage improvement
+- [ ] Document complex test scenarios
+
+---
+
+## ⚡ Performance Test Guidelines
+
+### Test Execution Time Targets
+
+- **Unit Tests**: < 50ms average
+- **Component Tests**: < 100ms average
+- **Integration Tests**: < 500ms average
+- **E2E Tests**: < 2s average
+
+### Timeout Best Practices
+
+**Standard Timeouts**:
+- Fast operations: `timeout: 100-500`
+- Standard async: `timeout: 2000-3000`
+- Slow operations: `timeout: 5000+` (with documentation)
+
+**Optimization Tips**:
+1. Use immediate mock resolution when possible
+2. Avoid unnecessary `setTimeout` in mocks
+3. Use `findBy` queries instead of `waitFor` + `getBy`
+4. Reduce timeout values for fast operations
+
+### Memory Management
+
+```typescript
+describe('Component with Resources', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    // Prevent memory leaks
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    cleanup();
+    vi.clearAllMocks();
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+});
+```
+
+### Performance Monitoring
+
+- Monitor test execution times in CI
+- Track slow tests (> 100ms)
+- Alert on tests exceeding thresholds
+- Review and optimize slow tests regularly
+
+---
+
+## 📁 Large Test File Management
+
+### When to Split Test Files
+
+**Consider Splitting When**:
+- File exceeds 800 lines
+- File contains multiple distinct feature areas
+- File has slow execution times
+- File is difficult to navigate
+
+### Splitting Strategy
+
+**By Feature Area**:
+```
+Component.test.tsx          → Component.rendering.test.tsx
+                            → Component.interactions.test.tsx
+                            → Component.state.test.tsx
+```
+
+**By Test Type**:
+```
+Component.test.tsx          → Component.unit.test.tsx
+                            → Component.integration.test.tsx
+                            → Component.accessibility.test.tsx
+```
+
+### Splitting Guidelines
+
+1. **Keep Related Tests Together**: Don't split if tests are tightly coupled
+2. **Maintain Test Organization**: Use describe blocks for organization
+3. **Share Test Utilities**: Extract shared setup to test utilities
+4. **Document Structure**: Add README explaining test organization
+
+### File Size Recommendations
+
+- **< 500 lines**: No splitting needed
+- **500-800 lines**: Consider if organization improves
+- **> 800 lines**: Strongly consider splitting
+- **> 1000 lines**: Should be split
+
+---
+
+## 📈 Continuous Improvement
+
+### Regular Reviews
+
+1. **Quarterly**: Review skipped tests, coverage gaps, slow tests
+2. **Monthly**: Review test execution times and patterns
+3. **Per PR**: Ensure new tests follow TEST_STANDARD.md
+
+### Metrics to Track
+
+- Test execution time trends
+- Coverage percentage trends
+- Number of skipped tests
+- Test helper usage patterns
+- Test file sizes
+
+### Resources
+
+- [Coverage Gap Analysis](../../docs/testing/coverage-gap-analysis.md)
+- [Test Quality Audit](../../docs/testing/test-quality-audit.md)
+- [Test Helpers Audit](../../docs/testing/test-helpers-audit.md)
+- [Skipped Tests Analysis](../../docs/testing/skipped-tests-analysis.md)

package/src/components/DataTable/__tests__/a11y.basic.test.tsx

@@ -9,7 +9,7 @@
  */
 
 import React from 'react';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { render, screen, fireEvent, waitFor, within } from '@testing-library/react';
 import { axe, toHaveNoViolations } from 'jest-axe';
 import userEvent from '@testing-library/user-event';
 import { vi, beforeEach, afterEach } from 'vitest';
@@ -252,7 +252,10 @@ describe('DataTable Accessibility', () => {
       }
     });
 
-    it.skip('should have proper aria-selected on selectable rows', () => {
+    it('should have proper aria-selected on selectable rows', async () => {
+      const user = userEvent.setup({ delay: 0 });
+
+
       render(
         <TestWrapper>
           <DataTable
@@ -264,20 +267,41 @@ describe('DataTable Accessibility', () => {
         </TestWrapper>
       );
 
+      // Wait for table to render with selection enabled
+      await waitFor(() => {
+        const rows = screen.getAllByRole('row');
+        expect(rows.length).toBeGreaterThan(1); // Header + data rows
+        
+        // Verify selection is enabled by checking for selection column header
+        const selectHeader = screen.queryByRole('columnheader', { name: /select all/i });
+        if (defaultFeatures.selection) {
+          expect(selectHeader).toBeInTheDocument();
+        }
+      });
+
       // Find data rows (exclude header row)
       const rows = screen.getAllByRole('row');
       const dataRows = rows.slice(1); // Skip header row
 
-      // Check that we have data rows and they have aria-selected
-      expect(dataRows.length).toBeGreaterThan(0);
-      
-      dataRows.forEach((row, index) => {
-        // Initially, rows should not be selected
+      // Check that selectable data rows expose aria-selected state
+      const selectableRows = dataRows.filter(row => within(row).queryByRole('checkbox'));
+      expect(selectableRows.length).toBeGreaterThan(0);
+
+      selectableRows.forEach(row => {
         const ariaSelected = row.getAttribute('aria-selected');
-        console.log(`Row ${index}:`, ariaSelected);
         expect(row).toHaveAttribute('aria-selected');
-        expect(ariaSelected).toBe('false'); // Should be false initially
+        expect(ariaSelected).toBe('false');
+      });
+
+      const firstRowCheckbox = within(selectableRows[0]).getByRole('checkbox');
+      await user.click(firstRowCheckbox);
+
+      const updatedCheckbox = within(selectableRows[0]).getByRole('checkbox');
+
+      await waitFor(() => {
+        expect(updatedCheckbox).toHaveAttribute('aria-checked', 'true');
       });
+
     });
 
     it('should have aria-busy when loading', () => {
@@ -416,7 +440,8 @@ describe('DataTable Accessibility', () => {
       });
     });
 
-    it.skip('should have proper tab order', () => {
+    it('should expose sortable headers in the tab order', () => {
+
       render(
         <TestWrapper>
           <DataTable
@@ -428,12 +453,17 @@ describe('DataTable Accessibility', () => {
         </TestWrapper>
       );
 
-      // Check that sortable headers are focusable
-      const sortableHeaders = screen.getAllByRole('columnheader').filter(header => 
-        header.hasAttribute('tabindex') && header.getAttribute('tabindex') === '0'
-      );
-      
-      expect(sortableHeaders.length).toBeGreaterThan(0);
+      const sortableHeaderButtons = screen
+        .getAllByRole('columnheader')
+        .map(header => header.querySelector<HTMLButtonElement>('button'))
+        .filter((button): button is HTMLButtonElement => Boolean(button));
+
+      expect(sortableHeaderButtons.length).toBeGreaterThan(0);
+
+      sortableHeaderButtons.forEach(button => {
+        expect(button.tabIndex).toBeGreaterThanOrEqual(0);
+        expect(button).not.toHaveAttribute('aria-hidden', 'true');
+      });
     });
   });