aitbc/apps/docs/TEST_COVERAGE_REQUIREMENTS.md

AITBC Microservices Test Coverage Requirements

This document outlines the test coverage requirements for the AITBC microservices architecture.

Overview

Each microservice should maintain adequate test coverage to ensure reliability and facilitate future development. Test coverage should be measured and tracked as part of the CI/CD pipeline.

Test Coverage Targets

Minimum Requirements

• Unit Tests: 70% line coverage minimum
• Integration Tests: 50% line coverage minimum
• Overall Coverage: 60% line coverage minimum per service

Ideal Targets

• Unit Tests: 80% line coverage
• Integration Tests: 70% line coverage
• Overall Coverage: 75% line coverage per service

Service-Specific Requirements

GPU Service

Unit Test Coverage Requirements:

• Domain models (GPUArchitecture, GPURegistry, ConsumerGPUProfile, EdgeGPUMetrics, GPUBooking, GPUReview): 80%
• Service layer (EdgeGPUService): 75%
• API endpoints: 70%

Integration Test Coverage Requirements:

• Database operations: 70%
• API endpoint integration: 60%
• Service dependencies: 50%

Critical Path Tests:

• Consumer GPU profile listing
• Edge GPU metrics creation
• GPU discovery (async)
• Inference optimization (async)

Marketplace Service

Unit Test Coverage Requirements:

• Domain models (MarketplaceOffer, MarketplaceBid, GlobalMarketplaceOffer, GlobalMarketplaceTransaction, etc.): 75%
• Service layer (MarketplaceService): 70%
• API endpoints: 65%

Integration Test Coverage Requirements:

• Database operations: 70%
• API endpoint integration: 60%
• Service dependencies: 50%

Critical Path Tests:

• Offer creation and retrieval
• Bid creation and retrieval
• Marketplace analytics

Trading Service

Unit Test Coverage Requirements:

• Domain models (TradeRequest, TradeMatch, TradeNegotiation, TradeAgreement, TradeSettlement, TradeFeedback, TradingAnalytics): 75%
• Service layer (TradingService): 70%
• API endpoints: 65%

Integration Test Coverage Requirements:

• Database operations: 70%
• API endpoint integration: 60%
• Service dependencies: 50%

Critical Path Tests:

• Trade request creation
• Trade matching logic
• Agreement creation
• Settlement processing

Governance Service

Unit Test Coverage Requirements:

• Domain models (GovernanceProfile, Proposal, Vote, DaoTreasury, TransparencyReport): 75%
• Service layer (GovernanceService): 70%
• API endpoints: 65%

Integration Test Coverage Requirements:

• Database operations: 70%
• API endpoint integration: 60%
• Service dependencies: 50%

Critical Path Tests:

• Proposal creation
• Vote casting
• Proposal execution
• Treasury management

API Gateway

Unit Test Coverage Requirements:

• Routing logic: 80%
• Service registry: 75%
• Proxy functionality: 70%

Integration Test Coverage Requirements:

• Gateway to service routing: 70%
• Load balancing: 50%
• Error handling: 60%

Critical Path Tests:

• Health check routing
• Service registry updates
• Request proxying to each service
• Unknown route handling

Test Types

Unit Tests

Purpose: Test individual functions and methods in isolation.

Requirements:

• Mock external dependencies (database, external APIs)
• Test edge cases and error conditions
• Test validation logic
• Test business logic

Example Coverage Areas:

• Domain model validation
• Service method logic
• Utility functions
• Helper methods

Integration Tests

Purpose: Test interactions between components.

Requirements:

• Use test databases
• Test database operations
• Test API endpoint integration
• Test service-to-service communication

Example Coverage Areas:

• Database CRUD operations
• API request/response handling
• Service dependency resolution
• Transaction management

End-to-End Tests

Purpose: Test complete workflows across services.

Requirements:

• Test critical user journeys
• Test gateway routing
• Test service orchestration
• Test error propagation

Example Coverage Areas:

• Complete trade flow (request → match → negotiate → agree → settle)
• Complete proposal flow (create → vote → execute)
• Gateway routing to all services

Test Execution

Running Tests

Run all tests for a service:

cd apps/<service-name>
pytest tests/

Run with coverage:

pytest tests/ --cov=src --cov-report=html --cov-report=term

Run specific test file:

pytest tests/test_main.py

Run specific test:

pytest tests/test_main.py::test_health_check

CI/CD Integration

Tests should run automatically in CI/CD pipeline:

1. On Pull Request: Run all tests with coverage reporting
2. On Merge to Main: Run all tests with coverage reporting and enforce minimum coverage
3. Nightly: Run full test suite including end-to-end tests

Coverage Enforcement

Minimum coverage thresholds should be enforced in CI:

[tool.coverage.run]
source = "src"

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise AssertionError",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
    "@abstractmethod",
]

[tool.coverage.fail_under]
minimum = 60

Coverage Reporting

Coverage Reports

Coverage reports should be generated in multiple formats:

• HTML: For detailed analysis (coverage/html/index.html)
• Terminal: For quick summary
• XML: For CI/CD integration

Coverage Tracking

Coverage should be tracked over time to identify trends:

• Track coverage by service
• Track coverage by module
• Track coverage by test type
• Identify declining coverage

Best Practices

Test Organization

• Organize tests by module/functionality
• Use descriptive test names
• Keep tests independent
• Use fixtures for common setup

Test Data

• Use factories for test data creation
• Use in-memory databases for unit tests
• Use test database for integration tests
• Clean up test data after each test

Mocking

• Mock external dependencies
• Use pytest-mock for mocking
• Mock database calls in unit tests
• Use real database in integration tests

Async Testing

• Use pytest-asyncio for async tests
• Mark async tests with @pytest.mark.asyncio
• Test async service methods
• Test async database operations

Coverage Exclusions

The following can be excluded from coverage calculations:

• Type checking blocks (if TYPE_CHECKING:)
• Abstract methods
• Representation methods (__repr__)
• Test files themselves
• Configuration files
• Migration scripts

Next Steps

1. Add coverage reporting to CI/CD pipeline
2. Set up coverage tracking dashboard
3. Review coverage reports regularly
4. Increase coverage targets as codebase matures
5. Add end-to-end tests for critical workflows