Skip to content

TESTING.md

Latest commit

 

History

History
251 lines (189 loc) · 7.48 KB

TESTING.md

File metadata and controls

251 lines (189 loc) · 7.48 KB

Testing Guidelines & Anti-Cluttering Standards

🚨 CRITICAL: Anti-Test-Cluttering Guidelines

This project maintains strict anti-cluttering standards to prevent test file proliferation while ensuring comprehensive coverage and quality.

📊 Current Test Status

⚠️ TESTING AGENT: Update this section with latest metrics after every test suite run

  • Total Tests: 1017 tests
  • Test Success: 1017/1017 (100% success rate)
  • Coverage: 79.57% overall (86.15% services, 90.25% components, 94.47% utils)
  • Test Files: 35 consolidated files
  • Last Updated: 2025-07-30 06:57:19 - Production-ready quality maintained
  • Quality Status: EXCELLENT - Zero failures, comprehensive coverage across all modules

🛡️ Test File Organization Rules

✅ CORRECT: One Comprehensive File per Component/Service

✅ GOOD - Consolidated approach:
- githubService.test.ts     (50 tests - ALL functionality)
- gitlabService.test.ts     (33 tests - ALL functionality)  
- MarkdownViewer.test.tsx   (38 tests - ALL functionality)
- TodoSidebar.test.tsx      (39 tests - ALL functionality)

❌ WRONG: Multiple Specialized Files (NEVER DO THIS)

❌ BAD - Cluttered approach that was eliminated:
- githubService.test.ts
- githubService.core.test.ts
- githubService.edge-cases.test.ts
- githubService.integration.test.ts
- githubService.errorHandling.test.ts
- githubService.folderFiltering.test.ts
[...and 10 more files testing the same service]

🔥 Anti-Patterns That Cause Test Cluttering

NEVER create these types of files:

  • Component.draft.test.tsx → Add draft tests to Component.test.tsx
  • Component.strategy.test.tsx → Add strategy tests to Component.test.tsx
  • Component.quick.test.tsx → Add quick tests to Component.test.tsx
  • service.integration.test.ts → Add integration tests to service.test.ts
  • service.errorHandling.test.ts → Add error tests to service.test.ts

Rule: If you're tempted to create X.something.test.ts, add those tests to X.test.ts instead.

🎯 Coverage Improvement Methodology

Systematic Approach (Proven +12% Improvement)

  1. Initial Analysis
npm run test:coverage -- --testTimeout=300000
  1. Target Low-Hanging Fruit (85-95% coverage files)
# Focus on files with small gaps, avoid complex service logic
# Example targets: utility functions, error handling, edge cases
  1. Strategic Implementation
# Test individual files to verify improvements
npm test src/utils/__tests__/[targetFile].test.ts
  1. Verify & Document
# Always verify coverage improvement
npm run test:coverage -- --testTimeout=300000

Coverage Targets by File Type

  • Services: Target 80-95% (complex caching logic may limit)
  • Components: Target 70-90% (UI edge cases are acceptable gaps)
  • Utils: Target 90-100% (pure functions should be fully testable)

📋 Test Quality Standards

Mandatory Requirements

  • ✅ 100% Test Success: All tests must pass before commit
  • ✅ No Duplicated Logic: Tests for same functionality go in same file
  • ✅ Comprehensive Error Handling: Cover error paths and edge cases
  • ✅ Production Patterns: Test real-world usage scenarios

File Naming Convention

# Component Tests
src/components/__tests__/ComponentName.test.tsx

# Service Tests  
src/services/__tests__/serviceName.test.ts

# Utility Tests
src/utils/__tests__/utilityName.test.ts

# Integration Tests (if needed)
src/__tests__/IntegrationName.test.tsx

Test Organization Within Files

describe('ComponentName', () => {
  // 🎯 Core functionality first
  describe('Core Functionality', () => {
    it('should handle primary use case', () => {});
    it('should handle secondary use case', () => {});
  });
  
  // 🛡️ Error handling second  
  describe('Error Handling', () => {
    it('should handle API errors gracefully', () => {});
    it('should handle invalid inputs', () => {});
  });
  
  // 🔧 Edge cases last
  describe('Edge Cases', () => {
    it('should handle empty state', () => {});
    it('should handle boundary conditions', () => {});
  });
});

🔧 Development Commands

Local Development

npm test                     # Interactive test runner (watch mode)
npm run test:coverage        # Full coverage report  
npm test [specific-file]     # Test individual file

Coverage Analysis

# Use proper timeout for accurate results
npm run test:coverage -- --testTimeout=300000

CI/CD Commands

npm install
npm run test:coverage
npm run build

🏆 Quality Standards

Mandatory Requirements

  • 100% Test Success: All tests must pass before any commit
  • Consolidated Structure: One comprehensive file per component/service
  • Production Patterns: Test real-world usage scenarios and error paths
  • Comprehensive Coverage: Target 80%+ with focus on critical paths
  • No Test Cluttering: Strictly follow anti-patterns prevention rules

Quality Indicators

  • Coverage Distribution: Services (80-95%), Components (70-90%), Utils (90-100%)
  • File Organization: Consolidated approach prevents cluttering
  • Test Reliability: Stable, deterministic tests with proper mocking
  • Error Handling: Comprehensive coverage of failure scenarios

🚨 When Adding New Tests

Decision Framework

Before creating a new test file, ask:

1. Does [Component/Service].test.tsx already exist?
   → YES: Add tests there
   → NO: Create [Component/Service].test.tsx

2. Are you testing the same component/service?
   → YES: Add to existing file  
   → NO: Create new file with proper naming

3. Would this create duplication?
   → YES: Consolidate into existing file
   → NO: Proceed with new tests

Expansion Guidelines

// ✅ GOOD: Add tests to existing comprehensive file
describe('ExistingComponent', () => {
  // Existing tests...
  
  // 🆕 Add new functionality tests here
  describe('New Feature', () => {
    it('should handle new feature correctly', () => {});
  });
});

// ❌ BAD: Don't create ExistingComponent.newFeature.test.tsx

📚 References

📋 Testing Agent Responsibilities

Status Maintenance (CRITICAL)

The testing-agent MUST update the "Current Test Status" section after every test suite operation:

  1. Run npm run test:coverage -- --testTimeout=300000
  2. Update all metrics in the status section
  3. Include timestamp and quality assessment
  4. Ensure accuracy of all reported numbers

Quality Assurance

  • Maintain 100% test success rate
  • Follow anti-cluttering guidelines strictly
  • Ensure comprehensive error handling coverage
  • Fix any TypeScript or ESLint issues immediately

🎯 Bottom Line

These guidelines maintain testing excellence by:

  • Preventing test file proliferation through strict anti-cluttering rules
  • Ensuring comprehensive coverage while maintaining quality standards
  • Providing clear decision frameworks for test organization
  • Maintaining production-ready reliability with consistent standards

Follow these guidelines to prevent test cluttering and maintain excellence!