biz-bud/docs/coverage-configuration.md

Coverage Configuration Guide

This document explains the coverage reporting configuration for the Business Buddy project.

Overview

The project uses pytest-cov for code coverage measurement with comprehensive reporting options configured in pyproject.toml.

Configuration

Coverage Collection ([tool.coverage.run])

• Source: src/biz_bud - Measures coverage for all source code
• Branch Coverage: Enabled to track both statement and branch coverage
• Parallel Execution: Supports parallel test execution with xdist
• Omitted Files:
  • Test files (*/tests/*, */test_*.py, */conftest.py)
  • Init files (*/__init__.py)
  • Entry points (webapp.py, CLI files)
  • Database migrations

Coverage Reporting ([tool.coverage.report])

• Show Missing: Displays line numbers for uncovered code
• Precision: 2 decimal places for coverage percentages
• Skip Empty: Excludes empty files from reports
• Comprehensive Exclusions:
  • Type checking blocks (if TYPE_CHECKING:)
  • Debug code (if DEBUG:, if __debug__:)
  • Platform-specific code
  • Error handling patterns
  • Abstract methods and protocols

Report Formats

1. Terminal: --cov-report=term-missing:skip-covered
2. HTML: htmlcov/index.html with context information
3. XML: coverage.xml for CI/CD integration
4. JSON: coverage.json for programmatic access

Usage

Running Tests with Coverage

# Run all tests with coverage
make test

# Run specific test with coverage
pytest tests/path/to/test.py --cov=src/biz_bud --cov-report=html

# Run without coverage (faster for development)
pytest tests/path/to/test.py --no-cov

Coverage Reports

# Generate HTML report
pytest --cov=src/biz_bud --cov-report=html

# View HTML report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

# Generate XML report for CI
pytest --cov=src/biz_bud --cov-report=xml

# Generate JSON report
pytest --cov=src/biz_bud --cov-report=json

Coverage Thresholds

• Minimum Coverage: 70% (configurable via --cov-fail-under)
• Branch Coverage: Required for thorough testing
• Context Tracking: Enabled to track which tests cover which code

Best Practices

1. Write Tests First: Aim for high coverage through TDD
2. Focus on Critical Paths: Prioritize coverage for core business logic
3. Use Exclusion Pragmas: Mark intentionally untested code with # pragma: no cover
4. Review Coverage Reports: Use HTML reports to identify missed edge cases
5. Monitor Trends: Track coverage changes in CI/CD

Exclusion Patterns

The configuration excludes common patterns that don't need testing:

• Type checking imports (if TYPE_CHECKING:)
• Debug statements (if DEBUG:, if __debug__:)
• Platform-specific code (if sys.platform)
• Abstract methods (@abstract, raise NotImplementedError)
• Error handling boilerplate (except ImportError:)

Integration with CI/CD

The XML and JSON reports are designed for integration with:

• GitHub Actions: Upload coverage to services like Codecov
• SonarQube: Import coverage data for quality gates
• IDE Integration: Many IDEs can display coverage inline

Troubleshooting

Common Issues

1. No Data Collected: Ensure source paths match actual file locations
2. Parallel Test Issues: Coverage data may need combining with coverage combine
3. Missing Files: Check that files are imported during test execution
4. Low Coverage: Review exclusion patterns and test completeness

Debug Commands

# Check coverage configuration
python -m coverage debug config

# Combine parallel coverage data
python -m coverage combine

# Erase coverage data
python -m coverage erase

Files

• Configuration: pyproject.toml ([tool.coverage.*] sections)
• Data File: .coverage (temporary, in .gitignore)
• HTML Reports: htmlcov/ directory (in .gitignore)
• XML Report: coverage.xml (in .gitignore)
• JSON Report: coverage.json (in .gitignore)