foxhunt/COVERAGE_EDGE_CASES_QUICK_REFERENCE.md

Coverage Edge Cases - Quick Reference Guide

Last Updated: 2025-10-15 Status: ✅ Production Ready (100% test pass rate)

---

Quick Test Execution

# Run original test suite (29 tests)
bash scripts/test_coverage_enforcement.sh

# Run edge case tests (48 tests)
bash scripts/test_coverage_edge_cases.sh

# Run coverage enforcement (full analysis)
bash scripts/enforce_coverage.sh

---

Edge Cases Covered

1. Floating-Point Comparisons ✅

Issue: Bash can't compare decimals like 59.9 < 60 Solution: Use bc -l for all comparisons

# Correct way to compare coverage values
if (( $(echo "$coverage < $threshold" | bc -l) )); then
    echo "Below threshold"
fi

Tests: 7 boundary conditions (59.9, 60.0, 60.1, 74.9, 75.0, 0.0, 100.0)

---

2. Missing Dependencies ✅

Issue: Script crashes if jq/bc not installed Solution: Pre-flight checks with instructions

Error Messages:

Error: jq not found
Install with: sudo apt-get install jq (Ubuntu/Debian) or brew install jq (macOS)

Error: bc not found
Install with: sudo apt-get install bc (Ubuntu/Debian) or brew install bc (macOS)

Tests: 3 dependency checks (cargo-llvm-cov, jq, bc)

---

3. Empty Coverage Reports ✅

Issue: Null values crash JSON parsing Solution: Detect null and fallback to LCOV

local lines_covered=$(jq '.data[0].totals.lines.covered' "$COVERAGE_JSON" 2>/dev/null || echo "null")

if [ "$lines_covered" == "null" ]; then
    # Fallback to LCOV or summary
fi

Tests: 1 null handling test

---

4. Division by Zero ✅

Issue: Crash when dividing by zero lines Solution: Check divisor before calculation

if [ "$lines_total" -gt 0 ] 2>/dev/null; then
    COVERAGE_PERCENT=$(echo "scale=2; ($lines_covered * 100) / $lines_total" | bc -l)
fi

Tests: 2 zero division tests

---

5. Invalid Module Coverage ✅

Issue: Non-numeric values crash comparisons Solution: Regex validation + default to 0.0

if [ -z "$pkg_coverage" ] || ! [[ "$pkg_coverage" =~ ^[0-9.]+$ ]]; then
    print_message "$YELLOW" "Warning: Could not extract coverage for $package, defaulting to 0.0%"
    pkg_coverage="0.0"
fi

Tests: 6 production module validation tests

---

Test Results Summary

Test Suite	Tests	Pass	Fail	Status
Original	29	29	0	✅ 100%
Edge Cases	48	48	0	✅ 100%
Total	77	77	0	✅ 100%

---

Common Issues & Solutions

"bc: command not found"

# Ubuntu/Debian
sudo apt-get install bc

# macOS
brew install bc

---

"jq: command not found"

# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq

---

Coverage extraction fails

Symptom: "Error: Could not extract coverage percentage from any source"

Solution:

1. Run tests manually: cargo test --workspace
2. Check compilation: cargo check --workspace
3. Verify llvm-cov: cargo llvm-cov --version
4. Re-run: bash scripts/enforce_coverage.sh

---

Module coverage shows 0.0%

Symptom: "Warning: Could not extract coverage for X, defaulting to 0.0%"

Solution:

1. Check if module has tests: cargo test -p <module>
2. Verify test syntax: cargo check --tests -p <module>
3. Add tests if missing (see TDD guidelines)

---

Coverage Thresholds

Module Type	Threshold	Status
Production (trading_engine, risk, api_gateway)	75%	FAIL below, WARN < 75%
Core (config, common, data)	60%	FAIL below, WARN < 75%
Supporting (tests, utilities)	60%	FAIL below, WARN < 75%

---

File Locations

foxhunt/
├── scripts/
│   ├── enforce_coverage.sh              # Main enforcement script
│   ├── test_coverage_enforcement.sh     # Original tests (29)
│   └── test_coverage_edge_cases.sh      # Edge case tests (48)
├── .github/workflows/
│   └── coverage.yml                     # CI/CD integration
└── WAVE_2_AGENT_17_COVERAGE_EDGE.md     # Full documentation

---

Edge Case Test Categories

1. Floating-Point Comparison (7 tests)

   • Boundary conditions: 59.9, 60.0, 60.1
   • Target thresholds: 74.9, 75.0
   • Edge values: 0.0, 100.0

2. Missing Dependencies (3 tests)

   • cargo-llvm-cov detection
   • jq availability
   • bc installation

3. Empty Reports (1 test)

   • Null value handling

4. Malformed JSON (1 test)

   • jq error detection

5. Division by Zero (2 tests)

   • Zero divisor protection
   • Valid divisor verification

6. Module Validation (6 tests)

   • Production module identification
   • Threshold assignment

7. Large Values (3 tests)

   • Coverage >= 100%

8. Negative Values (2 tests)

   • Negative coverage detection

9. JSON Structure (6 tests)

   • Required field validation
   • Schema correctness

10. bc Availability (3 tests)

    • Installation check
    • Floating-point division
    • Comparison logic

11. Error Handling (2 tests)

    • set -euo pipefail
    • Exit codes

12. Output Files (3 tests)

    • JSON report
    • HTML report
    • Module report

13. Color Output (5 tests)

    • ANSI color variables

14. Workspace Parsing (2 tests)

    • cargo metadata
    • jq extraction

15. Timeout Handling (2 tests)

    • 600-second limit
    • Timeout parameter

---

Best Practices

1. Always Use bc -l

# ✅ Correct
if (( $(echo "$a < $b" | bc -l) )); then

# ❌ Wrong (fails for decimals)
if [ "$a" -lt "$b" ]; then

---

2. Check for Null Before Using

# ✅ Correct
local value=$(jq '.field' file.json 2>/dev/null || echo "null")
if [ "$value" == "null" ]; then
    # Handle error
fi

# ❌ Wrong (crashes on null)
local value=$(jq '.field' file.json)

---

3. Validate Numeric Values

# ✅ Correct
if ! [[ "$value" =~ ^[0-9.]+$ ]]; then
    echo "Invalid numeric value"
    value="0.0"
fi

# ❌ Wrong (no validation)
coverage="$value"

---

4. Protect Against Division by Zero

# ✅ Correct
if [ "$divisor" -gt 0 ] 2>/dev/null; then
    result=$(echo "scale=2; $dividend / $divisor" | bc -l)
fi

# ❌ Wrong (crashes on zero)
result=$(echo "$dividend / $divisor" | bc)

---

CI/CD Integration

GitHub Actions Usage

- name: Run Coverage Tests
  run: |
    bash scripts/test_coverage_enforcement.sh
    bash scripts/test_coverage_edge_cases.sh

- name: Enforce Coverage
  run: bash scripts/enforce_coverage.sh
  env:
    MIN_COVERAGE: 60
    TARGET_COVERAGE: 75

---

Maintenance

Adding New Edge Case Tests

1. Edit scripts/test_coverage_edge_cases.sh
2. Add test function: test_new_edge_case()
3. Call from main() function
4. Run: bash scripts/test_coverage_edge_cases.sh
5. Update this document with new test count

Updating Thresholds

1. Edit scripts/enforce_coverage.sh:
   • MIN_COVERAGE=60
   • TARGET_COVERAGE=75
   • PRODUCTION_COVERAGE=75
2. Update .github/workflows/coverage.yml
3. Update README.md badge thresholds

---

Performance

• Edge Case Tests: ~2 seconds for 48 tests
• Enforcement Script: 2-10 minutes (depends on test suite size)
• Overhead: +50ms for enhanced error handling (negligible)

---

References

• Full Report: WAVE_2_AGENT_17_COVERAGE_EDGE.md
• Original Guide: COVERAGE_QUICK_REFERENCE.md
• TDD Guide: TDD_QUICK_REFERENCE.md

---

Status: ✅ Production Ready Test Pass Rate: 100% (77/77) Last Validated: 2025-10-15