coverage-analyzer

name	coverage-analyzer
description	Analyze test coverage with detailed metrics, identify gaps, and generate comprehensive reports. Use when measuring code coverage, finding untested code, or validating coverage thresholds.
allowed-tools	Read, Bash, Grep, Glob

Coverage Analyzer Skill

Purpose

This skill provides comprehensive test coverage analysis, gap identification, threshold validation, and detailed reporting to ensure code quality and adequate test coverage across the codebase.

When to Use

• Measuring test coverage for a module or project
• Identifying untested code and coverage gaps
• Validating coverage meets threshold (≥ 80%)
• Generating coverage reports for review
• Analyzing coverage trends over time
• Finding missing branch coverage

Coverage Analysis Workflow

1. Basic Coverage Measurement

Run Tests with Coverage:

# Install pytest-cov if not installed
pip install pytest-cov

# Basic coverage measurement
pytest --cov=src tests/

# Coverage with terminal report
pytest --cov=src --cov-report=term tests/

# Coverage with missing lines
pytest --cov=src --cov-report=term-missing tests/

# Coverage for specific module
pytest --cov=src.tools.feature tests/

Quick Coverage Check:

# Show percentage only
pytest --cov=src --cov-report=term tests/ | grep TOTAL

# Check if coverage meets threshold
pytest --cov=src --cov-fail-under=80 tests/

# Quiet mode with coverage
pytest --cov=src --cov-report=term -q tests/

Deliverable: Basic coverage metrics

---

2. Detailed Coverage Analysis

Generate Detailed Reports:

# HTML coverage report (most detailed)
pytest --cov=src --cov-report=html tests/
# Open htmlcov/index.html in browser

# XML coverage report (for CI/CD)
pytest --cov=src --cov-report=xml tests/

# JSON coverage report
pytest --cov=src --cov-report=json tests/

# Multiple report formats
pytest --cov=src \
  --cov-report=html \
  --cov-report=xml \
  --cov-report=term-missing \
  tests/

Analyze Coverage by Module:

# Show coverage for each file
pytest --cov=src --cov-report=term tests/

# Coverage with line numbers
pytest --cov=src --cov-report=term-missing tests/

# Annotated source files
pytest --cov=src --cov-report=annotate tests/
# Creates .py,cover files with coverage annotations

Deliverable: Detailed coverage reports

---

3. Coverage Gap Identification

Find Untested Code:

# Show missing lines
pytest --cov=src --cov-report=term-missing tests/

# Show missing branches
pytest --cov=src --cov-branch --cov-report=term-missing tests/

# Generate HTML report to visualize gaps
pytest --cov=src --cov-report=html tests/
# Open htmlcov/index.html to see line-by-line coverage

Identify Low Coverage Modules:

# Run coverage and parse output
pytest --cov=src --cov-report=term tests/ | grep -v "100%"

# Find files below 80% coverage
pytest --cov=src --cov-report=term tests/ | awk '$NF ~ /%/ && $NF+0 < 80'

# Sort by coverage percentage
pytest --cov=src --cov-report=term tests/ | sort -k4 -n

Analyze Coverage by Test Type:

# Coverage from unit tests only
pytest --cov=src --cov-report=term tests/unit/

# Coverage from integration tests only
pytest --cov=src --cov-report=term tests/integration/

# Combined coverage
pytest --cov=src --cov-report=term tests/unit/ tests/integration/

# Incremental coverage (append mode)
pytest --cov=src --cov-append --cov-report=term tests/unit/
pytest --cov=src --cov-append --cov-report=term tests/integration/

Deliverable: Coverage gap analysis

---

4. Branch Coverage Analysis

Measure Branch Coverage:

# Enable branch coverage
pytest --cov=src --cov-branch --cov-report=term-missing tests/

# Branch coverage with HTML report
pytest --cov=src --cov-branch --cov-report=html tests/

# Show partial branches
pytest --cov=src --cov-branch --cov-report=term-missing tests/ | grep "!->"

Analyze Conditional Coverage:

# Find untested conditionals
pytest --cov=src --cov-branch --cov-report=term-missing tests/ | grep "if"

# Check switch/case coverage
pytest --cov=src --cov-branch --cov-report=term-missing tests/ | grep "case"

Deliverable: Branch coverage metrics

---

5. Coverage Threshold Validation

Validate Minimum Coverage:

# Fail if coverage below 80%
pytest --cov=src --cov-fail-under=80 tests/

# Fail if coverage below 90%
pytest --cov=src --cov-fail-under=90 tests/

# Check with specific threshold and report
pytest --cov=src --cov-fail-under=80 --cov-report=term-missing tests/

Per-Module Thresholds:

# Core logic: 90% minimum
pytest --cov=src.core --cov-fail-under=90 tests/

# Utilities: 85% minimum
pytest --cov=src.utils --cov-fail-under=85 tests/

# Interfaces: 80% minimum
pytest --cov=src.interfaces --cov-fail-under=80 tests/

Deliverable: Threshold validation report

---

6. Coverage Configuration

Configure .coveragerc:

# .coveragerc
[run]
source = src
omit =
    tests/*
    */__init__.py
    */venv/*
    */.venv/*
    */migrations/*

branch = True

[report]
exclude_lines =
    # Default pragmas
    pragma: no cover

    # Don't complain about missing debug-only code
    def __repr__
    def __str__

    # Don't complain if tests don't hit defensive assertion code
    raise AssertionError
    raise NotImplementedError

    # Don't complain if non-runnable code isn't run
    if __name__ == .__main__.:
    if TYPE_CHECKING:

    # Don't complain about abstract methods
    @abstractmethod

precision = 2
show_missing = True

[html]
directory = htmlcov

[xml]
output = coverage.xml

Configure pyproject.toml:

# pyproject.toml
[tool.coverage.run]
source = ["src"]
omit = [
    "tests/*",
    "*/__init__.py",
    "*/venv/*",
    "*/.venv/*",
]
branch = true

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

[tool.coverage.html]
directory = "htmlcov"

[tool.coverage.xml]
output = "coverage.xml"

Deliverable: Coverage configuration

---

7. Coverage Reporting

Generate Coverage Reports:

# Terminal report
pytest --cov=src --cov-report=term tests/

# Terminal report with missing lines
pytest --cov=src --cov-report=term-missing tests/

# HTML report for detailed analysis
pytest --cov=src --cov-report=html tests/

# XML report for CI/CD integration
pytest --cov=src --cov-report=xml tests/

# JSON report for programmatic access
pytest --cov=src --cov-report=json tests/

# All reports
pytest --cov=src \
  --cov-report=term-missing \
  --cov-report=html \
  --cov-report=xml \
  --cov-report=json \
  tests/

Coverage Summary Report:

# Coverage Report

## Overall Coverage: 87%

### By Module
| Module | Coverage | Missing Lines |
|--------|----------|---------------|
| src.core | 95% | 45-47, 89 |
| src.utils | 88% | 12-15, 67-70 |
| src.interfaces | 82% | 23, 56-58 |
| src.models | 100% | - |

### Critical Gaps
1. Error handling in `src.core.process()` (lines 45-47)
2. Edge case validation in `src.utils.validate()` (lines 67-70)
3. Exception paths in `src.interfaces.execute()` (lines 56-58)

### Recommendations
- Add tests for error conditions in core module
- Improve edge case coverage in utilities
- Test exception handling in interfaces

### Status
✅ Overall coverage: 87% (target: 80%)
✅ Core business logic: 95% (target: 90%)
✅ Utilities: 88% (target: 85%)
✅ All thresholds met

Deliverable: Comprehensive coverage reports

---

8. Coverage Trend Analysis

Track Coverage Over Time:

# Generate coverage badge
pip install coverage-badge
coverage-badge -o coverage.svg

# Save coverage history
pytest --cov=src --cov-report=json tests/
mv coverage.json coverage-$(date +%Y%m%d).json

# Compare coverage between runs
coverage json
python -c "import json; print(json.load(open('coverage.json'))['totals']['percent_covered'])"

Coverage Diff:

# Coverage for current branch
pytest --cov=src --cov-report=json tests/
cp coverage.json coverage-current.json

# Coverage for main branch
git checkout main
pytest --cov=src --cov-report=json tests/
cp coverage.json coverage-main.json

# Compare
diff <(jq '.totals.percent_covered' coverage-main.json) \
     <(jq '.totals.percent_covered' coverage-current.json)

Deliverable: Coverage trends and comparisons

---

Coverage Analysis Patterns

Quick Coverage Check

# Fast coverage check during development
pytest --cov=src --cov-report=term-missing -q tests/unit/

Comprehensive Coverage Analysis

# Full coverage analysis with all reports
pytest --cov=src \
  --cov-branch \
  --cov-report=html \
  --cov-report=xml \
  --cov-report=term-missing \
  --cov-fail-under=80 \
  tests/

CI/CD Coverage Check

# Coverage check for CI/CD pipeline
pytest --cov=src \
  --cov-report=xml \
  --cov-report=term \
  --cov-fail-under=80 \
  tests/

Coverage Gap Investigation

# Find and analyze coverage gaps
pytest --cov=src --cov-report=html tests/
# Open htmlcov/index.html
# Click on files with low coverage
# Review highlighted untested lines

---

Coverage Metrics and Thresholds

Coverage Targets

By Module Type:

• Core Business Logic: ≥ 90%
• Services/APIs: ≥ 85%
• Utilities/Helpers: ≥ 85%
• Models/DTOs: ≥ 90%
• Interfaces/Contracts: ≥ 80%
• CLI/Main: ≥ 70%

By Coverage Type:

• Line Coverage: ≥ 80%
• Branch Coverage: ≥ 75%
• Function Coverage: ≥ 85%

Overall Project:

• Minimum: 80%
• Target: 85%
• Excellent: 90%+

Acceptable Exclusions

# Acceptable to exclude from coverage
def __repr__(self):  # pragma: no cover
    return f"Object({self.id})"

if __name__ == "__main__":  # pragma: no cover
    main()

if TYPE_CHECKING:  # pragma: no cover
    from typing import Optional

@abstractmethod
def interface_method(self):  # pragma: no cover
    pass

def debug_helper():  # pragma: no cover
    # Debug code not run in production
    pass

---

Coverage Analysis Checklist

Pre-Analysis

• Tests are running and passing
• pytest-cov installed
• Coverage configuration set (.coveragerc or pyproject.toml)
• Exclusions configured properly

Analysis

• Line coverage calculated
• Branch coverage calculated
• Coverage by module analyzed
• Coverage gaps identified
• Critical gaps prioritized

Threshold Validation

• Overall coverage ≥ 80%
• Core business logic ≥ 90%
• Utilities ≥ 85%
• No critical code untested
• Branch coverage ≥ 75%

Reporting

• Terminal report generated
• HTML report generated (for detailed review)
• XML report generated (for CI/CD)
• Coverage summary documented
• Gaps documented with recommendations

---

Common Coverage Commands

Quick Reference

# Basic coverage
pytest --cov=src tests/

# Coverage with gaps
pytest --cov=src --cov-report=term-missing tests/

# Coverage with threshold
pytest --cov=src --cov-fail-under=80 tests/

# Branch coverage
pytest --cov=src --cov-branch --cov-report=term-missing tests/

# HTML report
pytest --cov=src --cov-report=html tests/

# Full analysis
pytest --cov=src \
  --cov-branch \
  --cov-report=html \
  --cov-report=term-missing \
  --cov-fail-under=80 \
  tests/

---

Coverage Analysis Troubleshooting

Coverage Tool Not Found

# Install pytest-cov
pip install pytest-cov

# Verify installation
pytest --version
pip show pytest-cov

Incorrect Coverage (Too Low/High)

# Check source configuration
cat .coveragerc
cat pyproject.toml

# Verify source parameter
pytest --cov=src tests/  # Correct
pytest --cov tests/      # Wrong - testing test code

# Clear coverage cache
rm -rf .coverage htmlcov/
pytest --cov=src tests/

Missing Files in Coverage

# Check omit configuration
grep -A5 "\[run\]" .coveragerc

# Verify files are imported
pytest --cov=src --cov-report=term tests/ | grep "filename"

# Check test imports
grep -r "^import\|^from" tests/

Branch Coverage Not Working

# Enable branch coverage
pytest --cov=src --cov-branch tests/

# Check configuration
grep "branch" .coveragerc

# Verify branches exist
grep -r "if\|else\|elif" src/

---

Integration with Test Runner Specialist

Input: Completed test execution with coverage enabled Process: Analyze coverage, identify gaps, validate thresholds Output: Coverage report with gap analysis and recommendations Next Step: Report to test-runner-specialist for decision

---

Coverage Analysis Best Practices

Development

• Check coverage frequently during TDD
• Aim for >90% coverage on new code
• Review coverage reports locally
• Fix coverage gaps before committing

Pre-Commit

• Verify coverage meets threshold
• Review coverage diff vs main branch
• Ensure new code is well tested
• Check branch coverage for complex logic

CI/CD

• Generate coverage reports for every build
• Fail build if coverage below threshold
• Track coverage trends over time
• Archive coverage reports

Review

• Focus on critical paths first
• Prioritize business logic coverage
• Don't chase 100% coverage unnecessarily
• Exclude unreachable code appropriately

---

Coverage Gap Prioritization

High Priority (Fix Immediately)

• Core business logic uncovered
• Error handling paths untested
• Security-critical code uncovered
• Data validation missing tests
• API endpoints without tests

Medium Priority (Fix Soon)

• Utilities with <80% coverage
• Branch coverage gaps in logic
• Edge cases not tested
• Configuration parsing untested

Low Priority (Fix When Possible)

• Representation methods (repr, str)
• Debug/logging code
• CLI help text
• Non-critical utilities

Acceptable to Exclude

• Abstract methods
• TYPE_CHECKING blocks
• if name == "main"
• Platform-specific code not running in CI
• Deprecated code scheduled for removal

---

Supporting Resources

• pytest-cov documentation: https://pytest-cov.readthedocs.io
• coverage.py documentation: https://coverage.readthedocs.io
• Coverage best practices: https://testing.googleblog.com
• Sample .coveragerc: In project root

---

Success Metrics

• Coverage calculated accurately
• Overall coverage ≥ 80%
• Critical code coverage ≥ 90%
• Coverage gaps identified
• Reports generated successfully
• Thresholds validated
• Recommendations provided