Using Codecov Patch Coverage to Prevent Coverage Debt

Why Patch Coverage Matters

Global coverage can hide untested changes. Patch coverage reports only the lines that changed in the PR, so you can enforce tests for new code while leaving legacy modules untouched.

How Codecov Calculates Patch Coverage

Codecov uploads your coverage report (LCOV, Cobertura XML, or JSON). In the background it compares the report from the feature branch with the base branch, identifies the diff, and calculates the percentage of those new lines that were exercised by your test suite.

Configuring a Status Check

Place a .codecov.yml in the repository root. The status_checks section lets you define a patch check. A sample configuration:

# .codecov.yml
status_checks:
  patch:
    path: "/"
    status: fail
    threshold: 90%
  global:
    path: "/"
    status: fail
    threshold: 70%

Practical CI Example – GitHub Actions

Below is a minimal workflow that runs tests, generates an LCOV report, and uploads it to Codecov. The fetch-depth: 0 is essential for the diff calculation.

name: Test & Upload Coverage
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test -- --coverage --reporter=lcov

      - name: Upload to Codecov
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

Common Pitfalls & Limits

• Boilerplate Changes – If you modify large config files that are hard to test, a high patch threshold can block the PR.
• Refactor Noise – Pure refactors without logic change are still counted as new lines; ensure tests cover the new structure.
• Report Quality – Patch coverage is only as accurate as the coverage report; missing edge‑case paths may inflate the metric.

Verifying the Setup

1. Add the .codecov.yml to the branch.
2. Create a PR that adds a function without a test.
3. Check the Codecov UI – you should see a “Patch Coverage” badge below the overall coverage.
4. Confirm that the CI status check fails if the patch coverage is below 90%.

When to Use Patch Coverage

Use it when you want to guard against coverage debt in new features but are unwilling to force a full refactor of legacy code. It’s especially useful in large monorepos where legacy modules cannot be covered quickly.