# Coverage Gap Analysis
Debtmap provides precise line-level coverage gap reporting to help you understand exactly which lines of code lack test coverage, rather than relying on misleading function-level percentages.
## Understanding Coverage Gaps
A **coverage gap** represents the portion of a function that is not executed during tests. Traditional tools report this as a simple percentage (e.g., "50% covered"), but this can be misleading:
- A 100-line function with 1 uncovered line shows "99% covered" - sounds great!
- A 10-line function with 1 uncovered line shows "90% covered" - sounds worse, but is actually better
Debtmap improves on this by:
1. Reporting the actual number of uncovered lines
2. Showing which specific lines are uncovered
3. Calculating the gap as a percentage of instrumented lines (not total lines)
4. Providing visual severity indicators based on gap size
## Precise vs Estimated Gaps
Debtmap uses different precision levels depending on available coverage data:
### Precise Gaps (Line-Level Data Available)
When LCOV coverage data is available, debtmap provides exact line-level reporting:
```
Business logic - 1 line uncovered (11% gap) - line 52
Complex calculation - 4 lines uncovered (20% gap) - lines 10-12, 15
```
**Benefits:**
- Exact line numbers for uncovered code
- Accurate gap percentage based on instrumented lines
- Compact line range formatting (e.g., "10-12, 15, 20-21")
- Distinguishes between code that can't be instrumented vs uncovered code
**How it works:**
- Debtmap reads LCOV coverage data from your test runs
- Matches functions by file path and name
- Extracts precise uncovered line numbers
- Calculates percentage as: `(uncovered_lines / instrumented_lines) * 100`
### Estimated Gaps (Function-Level Data Only)
When only function-level coverage percentages are available:
```
Data processing - ~50% gap (estimated, ~25 lines)
Helper function - ~100% gap (estimated, 15 lines)
Utility - ~3% gap (mostly covered)
```
**Characteristics:**
- Estimates uncovered line count from percentage
- Uses tilde (~) prefix to indicate estimation
- Special cases:
- ≥99% gap → "~100% gap"
- <5% gap → "mostly covered"
- Otherwise → "~X% gap (estimated, ~Y lines)"
**How it works:**
- Falls back when LCOV data unavailable or function not found
- Calculates: `estimated_uncovered = total_lines * (gap_percentage / 100)`
- Useful for quick overview but less actionable than precise gaps
### Unknown Coverage
When no coverage data is available:
```
Untested module - Coverage data unavailable (42 lines)
```
This typically occurs when:
- No coverage collection has been run
- File not included in coverage report
- Coverage data file path mismatch
## Gap Severity Indicators
Debtmap uses visual indicators to quickly identify the severity of coverage gaps:
| 🟡 | 1-25% | LOW | Minor gaps, mostly covered |
| 🟠 | 26-50% | MODERATE | Significant gaps, needs attention |
| 🔴 | 51-75% | HIGH | Major gaps, high priority |
| 🔴🔴 | 76-100% | CRITICAL | Severe gaps, critical priority |
These indicators appear in debtmap's priority output to help you quickly identify which functions need testing most urgently.
### Severity Calculation
Gap severity is based on the percentage of uncovered code:
```rust
fn get_severity(gap_percentage: f64) -> &'static str {
match gap_percentage {
p if p <= 25.0 => "🟡 LOW",
p if p <= 50.0 => "🟠 MODERATE",
p if p <= 75.0 => "🔴 HIGH",
_ => "🔴🔴 CRITICAL"
}
}
```
This works for both precise and estimated gaps, ensuring consistent severity classification across your codebase.
## Example Output
### High Verbosity Mode
```
Priority 1: Authentication Logic (CRITICAL)
File: src/auth/login.rs:45
Coverage Gap: 2 lines uncovered (89% gap) 🔴🔴 - lines 67, 89
Complexity: Cyclomatic 8, Cognitive 12
Impact: High-risk business logic with critical coverage gaps
Priority 2: Data Validation (HIGH)
File: src/validation/rules.rs:120
Coverage Gap: 15 lines uncovered (65% gap) 🔴 - lines 145-152, 167-173
Complexity: Cyclomatic 5, Cognitive 8
Impact: Complex validation logic needs comprehensive testing
Priority 3: Helper Function (MODERATE)
File: src/utils/helpers.rs:30
Coverage Gap: ~45% gap (estimated, ~12 lines) 🟠
Complexity: Cyclomatic 3, Cognitive 4
Impact: Moderate complexity with estimated coverage gaps
```
### Standard Mode
```
1. Authentication Logic (src/auth/login.rs:45)
Gap: 2 lines uncovered (89%) 🔴🔴 [lines 67, 89]
2. Data Validation (src/validation/rules.rs:120)
Gap: 15 lines uncovered (65%) 🔴 [lines 145-152, 167-173]
3. Helper Function (src/utils/helpers.rs:30)
Gap: ~45% (estimated) 🟠
```
## Integration with Coverage Tools
### Generating LCOV Data
For precise gap reporting, generate LCOV coverage data with your test framework:
**Rust (using cargo-tarpaulin):**
```bash
cargo tarpaulin --out Lcov --output-dir ./coverage
```
**Python (using pytest-cov):**
```bash
pytest --cov=mypackage --cov-report=lcov:coverage/lcov.info
```
**JavaScript (using Jest):**
```bash
jest --coverage --coverageReporters=lcov
```
### Configuring Debtmap
Point debtmap to your coverage data:
```bash
debtmap analyze . --lcov ./coverage/lcov.info
```
Or in `.debtmap.toml`:
```toml
[coverage]
lcov_path = "./coverage/lcov.info"
```
## Best Practices
### 1. Use Precise Gaps When Possible
Always generate LCOV data for actionable coverage insights:
- Precise line numbers help you quickly locate untested code
- Accurate percentages prevent over/under-estimating gaps
- Line ranges show if gaps are concentrated or scattered
### 2. Focus on High Severity Gaps First
Prioritize based on severity indicators:
1. 🔴🔴 CRITICAL (76-100%) - Address immediately
2. 🔴 HIGH (51-75%) - Schedule for next sprint
3. 🟠 MODERATE (26-50%) - Address when convenient
4. 🟡 LOW (1-25%) - Acceptable for some code
### 3. Consider Context
Gap severity should be weighted by:
- **Function role**: Business logic vs utilities
- **Complexity**: High complexity + high gap = top priority
- **Change frequency**: Frequently changed code needs better coverage
- **Risk**: Security, data integrity, financial calculations
### 4. Track Progress Over Time
Run debtmap regularly to track coverage improvements:
```bash
# Weekly coverage check
debtmap analyze . --lcov ./coverage/lcov.info > weekly-gaps.txt
```
Compare reports to see gap reduction progress.
## Troubleshooting
### "Coverage data unavailable" for all functions
**Cause**: Debtmap can't find or parse LCOV file
**Solutions**:
- Verify `--lcov` points to a valid LCOV file
- Ensure LCOV file was generated recently
- Check file permissions (readable by debtmap)
- Validate LCOV format: `head -20 ./coverage/lcov.info`
### Line numbers don't match source code
**Cause**: Source code changed since coverage was generated
**Solutions**:
- Re-run tests with coverage collection
- Ensure clean build before coverage run
- Commit code before running coverage
### Estimated gaps for functions with LCOV data
**Cause**: Function name or path mismatch
**Solutions**:
- Check function names match exactly (case-sensitive)
- Verify file paths are consistent (relative vs absolute)
- Use verbose output for diagnostics: `debtmap analyze . --lcov ./coverage/lcov.info -vv`
### Missing functions in coverage report
**Cause**: Functions not instrumented or filtered out
**Solutions**:
- Check coverage tool configuration
- Ensure test execution reaches those functions
- Verify functions aren't in excluded paths
## Related Topics
- [Coverage Integration](coverage-integration.md) - Detailed coverage tool setup
- [Tiered Prioritization](tiered-prioritization.md) - How coverage gaps affect priority
- [Scoring Strategies](scoring-strategies.md) - Coverage weight in debt scoring
- [Metrics Reference](metrics-reference.md) - All coverage-related metrics