trent_larson/crowd-funder-for-time-pwa
4
1
Fork 2
Code Issues Pull Requests 22 Releases 5 Wiki Activity

feat(testing): add comprehensive unit testing and mocks MDC

Browse Source 
- Establishes universal testing standards using Vitest + JSDOM
- Defines three-tier mock architecture (Simple/Standard/Complex)
- Documents comprehensive test patterns and coverage requirements
- Includes centralized test utilities and best practices
- Provides self-improvement feedback loop for continuous enhancement
- Follows established MDC patterns and documentation standards

Closes testing documentation gap and provides reusable guide for other projects
This commit is contained in:
Matthew Raymer
2025-08-21 11:17:17 +00:00
parent ee35719cd5
commit e2c812a5a6
1 changed files with 714 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

714
.cursor/rules/unit_testing_mocks.mdc Normal file
View File

@@ -0,0 +1,714 @@
```json
{
"coaching_level": "standard",
"socratic_max_questions": 2,
"verbosity": "normal",
"timebox_minutes": null,
"format_enforcement": "strict"
}
```
# Unit Testing & Mocks — Universal Development Guide
**Author**: Matthew Raymer
**Date**: 2025-08-21T09:40Z
**Status**: 🎯 **ACTIVE** - Comprehensive testing standards
## Overview
This guide establishes **unified unit testing and mocking standards** for Vue
and React projects, ensuring consistent, maintainable test patterns using
Vitest, JSDOM, and component testing utilities. All tests follow F.I.R.S.T.
principles with comprehensive mock implementations.
## Scope and Goals
**Scope**: Applies to all unit tests, mock implementations, and testing
infrastructure in any project workspace.
**Goal**: One consistent testing approach with comprehensive mock coverage,
100% test coverage for simple components, and maintainable test patterns.
## Non‑Negotiables (DO THIS)
- **MUST** use Vitest + JSDOM for unit testing; **DO NOT** use Jest or other
frameworks
- **MUST** implement comprehensive mock levels (Simple, Standard, Complex) for
all components
- **MUST** achieve 100% line coverage for simple components (<100 lines)
- **MUST** follow F.I.R.S.T. principles: Fast, Independent, Repeatable,
Self-validating, Timely
- **MUST** use centralized test utilities from `src/test/utils/`
## Testing Infrastructure
### **Core Technologies**
- **Vitest**: Fast unit testing framework with Vue/React support
- **JSDOM**: Browser-like environment for Node.js testing
- **@vue/test-utils**: Vue component testing utilities
- **TypeScript**: Full type safety for tests and mocks
### **Configuration Files**
- `vitest.config.ts` - Vitest configuration with JSDOM environment
- `src/test/setup.ts` - Global test configuration and mocks
- `src/test/utils/` - Centralized testing utilities
### **Global Mocks**
```typescript
// Required browser API mocks
ResizeObserver, IntersectionObserver, localStorage, sessionStorage,
matchMedia, console methods (reduced noise)
```
## Mock Implementation Standards
### **Mock Architecture Levels**
#### **1. Simple Mock (Basic Testing)**
```typescript
// Minimal interface compliance
class ComponentSimpleMock {
// Essential props and methods only
// Basic computed properties
// No complex behavior
}
```
#### **2. Standard Mock (Integration Testing)**
```typescript
// Full interface compliance
class ComponentStandardMock {
// All props, methods, computed properties
// Realistic behavior simulation
// Helper methods for test scenarios
}
```
#### **3. Complex Mock (Advanced Testing)**
```typescript
// Enhanced testing capabilities
class ComponentComplexMock extends ComponentStandardMock {
// Mock event listeners
// Performance testing hooks
// Error scenario simulation
// Accessibility testing support
}
```
### **Mock Component Structure**
Each mock component provides:
- Same interface as original component
- Simplified behavior for testing
- Helper methods for test scenarios
- Computed properties for state validation
### **Enhanced Mock Architecture Validation** ✅ **NEW**
The three-tier mock architecture (Simple/Standard/Complex) has been successfully
validated through real-world implementation:
#### **Tier 1: Simple Mock**
```typescript
class ComponentSimpleMock {
// Basic interface compliance
// Minimal implementation for simple tests
// Fast execution for high-volume testing
}
```
#### **Tier 2: Standard Mock**
```typescript
class ComponentStandardMock {
// Full interface implementation
// Realistic behavior simulation
// Helper methods for common scenarios
}
```
#### **Tier 3: Complex Mock**
```typescript
class ComponentComplexMock {
// Enhanced testing capabilities
// Validation and error simulation
// Advanced state management
// Performance testing support
}
```
#### **Factory Function Pattern**
```typescript
// Specialized factory functions for common use cases
export const createComponentMock = () =>
new ComponentStandardMock({ type: 'default' })
export const createSpecializedMock = () =>
new ComponentComplexMock({
options: { filter: 'active', sort: 'name' }
})
```
### **Mock Usage Examples**
```typescript
export default class ComponentMock {
// Props simulation
props: ComponentProps
// Computed properties
get computedProp(): boolean {
return this.props.condition
}
// Mock methods
mockMethod(): void {
// Simulate behavior
}
// Helper methods
getCssClasses(): string[] {
return ['base-class', 'conditional-class']
}
}
```
## Test Patterns
### **Component Testing Template**
```typescript
import { mount } from '@vue/test-utils'
import { createComponentWrapper } from '@/test/utils/componentTestUtils'
describe('ComponentName', () => {
let wrapper: VueWrapper<any>
const mountComponent = (props = {}) => {
return mount(ComponentName, {
props: { ...defaultProps, ...props }
})
}
beforeEach(() => {
wrapper = mountComponent()
})
afterEach(() => {
wrapper?.unmount()
})
describe('Component Rendering', () => {
it('should render correctly', () => {
expect(wrapper.exists()).toBe(true)
})
})
})
```
### **Mock Integration Testing**
```typescript
import ComponentMock from '@/test/__mocks__/Component.mock'
it('should work with mock component', () => {
const mock = new ComponentMock()
expect(mock.shouldShow).toBe(true)
})
```
### **Event Testing**
```typescript
it('should emit event when triggered', async () => {
await wrapper.find('button').trigger('click')
expect(wrapper.emitted('event-name')).toBeTruthy()
})
```
### **Prop Validation**
```typescript
it('should accept all required props', () => {
wrapper = mountComponent()
expect(wrapper.vm.propName).toBeDefined()
})
```
## Test Categories
### **Required Coverage Areas**
1. **Component Rendering** - Existence, structure, conditional rendering
2. **Component Styling** - CSS classes, responsive design, framework
integration
3. **Component Props** - Required/optional prop handling, type validation
4. **User Interactions** - Click events, form inputs, keyboard navigation
5. **Component Methods** - Method existence, functionality, return values
6. **Edge Cases** - Empty/null props, rapid interactions, state changes
7. **Error Handling** - Invalid props, malformed data, graceful degradation
8. **Accessibility** - Semantic HTML, ARIA attributes, keyboard navigation
9. **Performance** - Render time, memory leaks, rapid re-renders
10. **Integration** - Parent-child interaction, dependency injection
### **Error Handling Testing**
```typescript
const invalidPropCombinations = [
null, undefined, 'invalid', 0, -1, {}, [],
() => {}, NaN, Infinity
]
invalidPropCombinations.forEach(invalidProp => {
it(`should handle invalid prop: ${invalidProp}`, () => {
wrapper = mountComponent({ prop: invalidProp })
expect(wrapper.exists()).toBe(true)
// Verify graceful handling
})
})
```
## Centralized Test Utilities
### **Component Testing Utilities**
```typescript
import {
createComponentWrapper,
createTestDataFactory,
testLifecycleEvents,
testComputedProperties,
testWatchers,
testPerformance,
testAccessibility,
testErrorHandling
} from '@/test/utils/componentTestUtils'
// Component wrapper factory
const wrapperFactory = createComponentWrapper(
Component,
defaultProps,
globalOptions
)
// Test data factory
const createTestProps = createTestDataFactory({
prop1: 'default',
prop2: true
})
```
### **Test Data Factories**
```typescript
import {
createMockContact,
createMockProject,
createMockUser
} from '@/test/factories/contactFactory'
const testContact = createMockContact({
id: 'test-1',
name: 'Test User'
})
```
## Coverage Standards
### **Coverage Standards by Component Complexity**
| Component Complexity | Line Coverage | Branch Coverage | Function Coverage |
|---------------------|---------------|-----------------|-------------------|
| **Simple (<100 lines)** | 100% | 100% | 100% |
| **Medium (100-300 lines)** | 95% | 90% | 100% |
| **Complex (300+ lines)** | 90% | 85% | 100% |
### **Current Coverage Status**
- **Simple Components**: Ready for implementation
- **Medium Components**: Ready for expansion
- **Complex Components**: Ready for expansion
- **Overall Coverage**: Varies by project implementation
### **Test Infrastructure Requirements**
- **Test Framework**: Vitest + JSDOM recommended
- **Component Testing**: Vue Test Utils integration
- **Mock Architecture**: Three-tier system (Simple/Standard/Complex)
- **Test Categories**: 10 comprehensive categories
- **Coverage Goals**: 100% for simple components, 90%+ for complex
## Testing Philosophy
### **Defensive Programming Validation**
- **Real-world edge case protection** against invalid API responses
- **System stability assurance** preventing cascading failures
- **Production readiness** ensuring graceful error handling
### **Comprehensive Error Scenarios**
- **Invalid input testing** with 10+ different invalid prop combinations
- **Malformed data testing** with various corrupted data structures
- **Extreme value testing** with boundary conditions and edge cases
- **Concurrent error testing** with rapid state changes
### **Benefits Beyond Coverage**
1. **Defensive Programming Validation** - Components handle unexpected data
gracefully
2. **Real-World Resilience** - Tested against actual failure scenarios
3. **Developer Confidence** - Safe to refactor and extend components
4. **Production Stability** - Reduced support tickets and user complaints
## Advanced Testing Patterns
### **Performance Testing** ✅ **NEW**
- Render time benchmarks
- Memory leak detection
- Rapid re-render efficiency
- Component cleanup validation
#### **Advanced Performance Testing Patterns**
```typescript
// Memory leak detection
it('should not cause memory leaks during prop changes', async () => {
const initialMemory = (performance as any).memory?.usedJSHeapSize || 0
for (let i = 0; i < 100; i++) {
await wrapper.setProps({
queryParams: { iteration: i.toString() }
})
}
const finalMemory = (performance as any).memory?.usedJSHeapSize || 0
const memoryIncrease = finalMemory - initialMemory
// Memory increase should be reasonable (less than 10MB)
expect(memoryIncrease).toBeLessThan(10 * 1024 * 1024)
})
// Rapid re-render efficiency
it('should handle rapid re-renders efficiently', async () => {
const start = performance.now()
for (let i = 0; i < 50; i++) {
await wrapper.setProps({
entityType: i % 2 === 0 ? 'type1' : 'type2',
queryParams: { index: i.toString() }
})
}
const end = performance.now()
expect(end - start).toBeLessThan(500) // 500ms threshold for 50 updates
})
```
### **Snapshot Testing** ✅ **NEW**
- DOM structure validation
- CSS class regression detection
- Accessibility attribute consistency
- Visual structure verification
#### **Snapshot Testing Implementation**
```typescript
describe('Snapshot Testing', () => {
it('should maintain consistent DOM structure', () => {
expect(wrapper.html()).toMatchSnapshot()
})
it('should maintain consistent structure with different props', () => {
wrapper = mountComponent({ type: 'alternative' })
expect(wrapper.html()).toMatchSnapshot()
})
it('should maintain consistent structure with query params', () => {
wrapper = mountComponent({
queryParams: { filter: 'active', sort: 'name' }
})
expect(wrapper.html()).toMatchSnapshot()
})
})
```
### **Mock Integration Testing** ✅ **NEW**
- Mock component validation
- Factory function testing
- Mock behavior verification
- Integration with testing utilities
#### **Mock Integration Testing Patterns**
```typescript
describe('Mock Integration Testing', () => {
it('should work with simple mock', () => {
const mock = new ComponentSimpleMock()
expect(mock.navigationRoute).toEqual({
name: 'default',
query: {}
})
})
it('should work with standard mock', () => {
const mock = new ComponentStandardMock({
type: 'special',
name: 'test'
})
expect(mock.getType()).toBe('special')
expect(mock.getName()).toBe('test')
})
it('should work with complex mock', () => {
const mock = new ComponentComplexMock({
type: 'advanced',
options: { filter: 'active' }
})
expect(mock.isValidState()).toBe(true)
expect(mock.getValidationErrors()).toEqual([])
})
it('should work with factory functions', () => {
const defaultMock = createComponentMock()
const specializedMock = createSpecializedMock()
expect(defaultMock.getType()).toBe('default')
expect(specializedMock.getOptions()).toHaveProperty('filter')
})
})
```
## Project Implementation Tracking
### **Setting Up Project-Specific Tracking**
Each project should maintain its own tracking file to monitor testing progress
and coverage metrics. This keeps the universal MDC clean while providing a
template for project implementation.
#### **Recommended Project Tracking Structure**
```tree
src/test/
├── README.md # Testing documentation
├── PROJECT_COVERAGE_TRACKING.md # Project-specific progress tracking
├── __mocks__/ # Mock implementations
├── utils/ # Test utilities
└── [test files]
```
#### **Project Tracking File Template**
Create a `PROJECT_COVERAGE_TRACKING.md` file with:
- **Current Coverage Status**: Component-by-component breakdown
- **Implementation Progress**: Phase completion status
- **Test Infrastructure Status**: Framework setup and metrics
- **Next Steps**: Immediate priorities and long-term goals
- **Lessons Learned**: Project-specific insights and best practices
#### **Example Project Tracking Sections**
```markdown
# [Project Name] Testing Coverage Tracking
## Current Coverage Status
- Simple Components: X/Y at 100% coverage
- Medium Components: X/Y ready for expansion
- Complex Components: X/Y planned
## Implementation Progress
- Phase 1: Simple Components ✅ COMPLETE
- Phase 2: Medium Components 🔄 IN PROGRESS
- Phase 3: Complex Components 🔄 PLANNED
## Test Infrastructure Status
- Total Tests: X tests passing
- Test Files: X files
- Mock Files: X implementations
- Overall Coverage: X% (focused on simple components)
```
### **Integration with Universal MDC**
- **MDC provides**: Testing patterns, mock architecture, best practices
- **Project tracking provides**: Implementation status, coverage metrics,
progress
- **Separation ensures**: MDC remains reusable, project data stays local
- **Template approach**: Other projects can copy and adapt the structure
### **Benefits of This Approach**
1. **Universal Reusability**: MDC works for any project
2. **Project Visibility**: Clear tracking of implementation progress
3. **Template Reuse**: Easy to set up tracking in new projects
4. **Clean Separation**: No project data polluting universal guidance
5. **Scalability**: Multiple projects can use the same MDC
## Best Practices
### **Test Organization**
1. **Group related tests** using `describe` blocks
2. **Use descriptive test names** that explain the scenario
3. **Keep tests focused** on one specific behavior
4. **Use helper functions** for common setup
### **Mock Design**
1. **Maintain interface compatibility** with original components
2. **Provide helper methods** for common test scenarios
3. **Include computed properties** for state validation
4. **Document mock behavior** clearly
### **Coverage Goals**
1. **100% line coverage** for simple components
2. **100% branch coverage** for conditional logic
3. **100% function coverage** for all methods
4. **Edge case coverage** for error scenarios
### **Lessons Learned from Implementation** ✅ **NEW**
#### **1. Performance Testing Best Practices**
- **Memory leak detection**: Use `performance.memory.usedJSHeapSize` for
memory profiling
- **Render time benchmarking**: Set realistic thresholds (100ms for single
render, 500ms for 50 updates)
- **Rapid re-render testing**: Test with 50+ prop changes to ensure
stability
#### **2. Snapshot Testing Implementation**
- **DOM structure validation**: Use `toMatchSnapshot()` for consistent
structure verification
- **Prop variation testing**: Test snapshots with different prop combinations
- **Regression prevention**: Snapshots catch unexpected DOM changes
#### **3. Mock Integration Validation**
- **Mock self-testing**: Test that mocks work correctly with testing
utilities
- **Factory function testing**: Validate specialized factory functions
- **Mock behavior verification**: Ensure mocks simulate real component
behavior
#### **4. Edge Case Coverage**
- **Null/undefined handling**: Test with `null as any` and `undefined`
props
- **Extreme values**: Test with very long strings and large numbers
- **Rapid changes**: Test with rapid prop changes to ensure stability
#### **5. Accessibility Testing**
- **Semantic structure**: Verify proper HTML elements and hierarchy
- **Component attributes**: Check component-specific attributes
- **Text content**: Validate text content and trimming
## Future Improvements
### **Implemented Enhancements**
1. ✅ **Error handling** - Component error states and exception handling
2. ✅ **Performance testing** - Render time benchmarks and memory leak
detection
3. ✅ **Integration testing** - Parent-child component interaction and
dependency injection
4. ✅ **Snapshot testing** - DOM structure validation and CSS class
regression detection
5. ✅ **Accessibility compliance** - ARIA attributes and semantic structure
validation
### **Future Enhancements**
1. **Visual regression testing** - Automated UI consistency checks
2. **Cross-browser compatibility** testing
3. **Service layer integration** testing
4. **End-to-end component** testing
5. **Advanced performance** profiling
### **Coverage Expansion**
1. **Medium complexity components** (100-300 lines)
2. **Complex components** (300+ lines)
3. **Service layer testing**
4. **Utility function testing**
5. **API integration testing**
## Troubleshooting
### **Common Issues**
1. **Import errors**: Check path aliases in `vitest.config.ts`
2. **Mock not found**: Verify mock file exists and exports correctly
3. **Test failures**: Check for timing issues with async operations
4. **Coverage gaps**: Add tests for uncovered code paths
### **Debug Tips**
1. **Use `console.log`** in tests for debugging
2. **Check test output** for detailed error messages
3. **Verify component props** are being passed correctly
4. **Test one assertion at a time** to isolate issues
---
**Status**: Active testing standards
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: Vitest, JSDOM, Vue Test Utils
**Stakeholders**: Development team, QA team
## Competence Hooks
- *Why this works*: Three-tier mock architecture provides flexibility,
comprehensive test categories ensure thorough coverage, performance testing
catches real-world issues early
- *Common pitfalls*: Not testing mocks themselves, missing edge case
coverage, ignoring performance implications
- *Next skill unlock*: Implement medium complexity component testing with
established patterns
- *Teach-back*: Explain how the three-tier mock architecture supports
different testing needs
## Collaboration Hooks
- **Reviewers**: Testing team, component developers, architecture team
- **Sign-off checklist**: All simple components at 100% coverage, mock
utilities documented, test patterns established, coverage expansion plan
approved
## Assumptions & Limits
- Assumes Vue/React component architecture
- Requires Vitest + JSDOM testing environment
- Mock complexity scales with component complexity
- Performance testing requires browser-like environment
## References
- [Vitest Documentation](https://vitest.dev/)
- [Vue Test Utils](https://test-utils.vuejs.org/)
- [JSDOM](https://github.com/jsdom/jsdom)
- [Testing Best Practices](https://testing-library.com/docs/guiding-principles)
- **Sign-off checklist**: All simple components at 100% coverage, mock
utilities documented, test patterns established, coverage expansion plan
approved