CoverageRatchet 0.10.0-alpha.1

CoverageRatchet

Per-file code coverage enforcement that only goes up. CoverageRatchet reads your Cobertura XML coverage reports, compares each file against its threshold, and helps prevent coverage from regressing.

How It Works

1. Your test suite generates a Cobertura XML coverage report (most .NET coverage tools support this format).
2. CoverageRatchet reads the report and compares each file's line and branch coverage against its threshold.
3. check fails the build if any file drops below its threshold.
4. ratchet (the default command) updates thresholds to match current coverage -- thresholds only go up, not down.
5. loosen sets thresholds to whatever coverage is right now, so check passes immediately.

The default threshold for every file is 100% line and branch coverage. Files that can't easily reach 100% (like CLI entry points) can get per-file overrides with a documented reason.

Installation

dotnet tool install -g CoverageRatchet

Usage

Ratchet (default)

Just run coverageratchet with no arguments to ratchet thresholds upward:

coverageratchet

This recursively searches for a coverage.cobertura.xml file, compares each file against its threshold, and tightens thresholds where coverage has improved. Exit codes:

You can also run it explicitly as coverageratchet ratchet.

Check coverage (CI)

coverageratchet check

Exits with code 0 if all files meet their thresholds, 1 if any file is below.

Loosen thresholds

If you need check to pass right now (e.g., after a big refactor that dropped coverage), loosen sets every file's threshold to its current actual coverage:

coverageratchet loosen

This always exits 0. Files that were already at 100% don't get an override. New overrides get the reason "loosened automatically".

Export coverage as JSON (for CI)

coverageratchet check-json [config-path] [output-path]

Writes machine-readable coverage results. Exit code matches check (non-zero if any file fails). Used by CI workflows to upload coverage data as an artifact.

Sync thresholds from CI

coverageratchet loosen-from-ci [config-path]

Pushes current code, polls CI, and if coverage fails:

1. Downloads the coverage-thresholds artifact
2. Merges CI platform thresholds into local config (splitting non-platform entries if needed)
3. Commits, pushes, and re-polls CI

Requires gh CLI and jj (or git).

Custom config path

coverageratchet check path/to/my-config.json
coverageratchet ratchet path/to/my-config.json
coverageratchet loosen path/to/my-config.json

Configuration

CoverageRatchet uses a JSON config file (default: coverage-ratchet.json in the current directory).

Example coverage-ratchet.json

{
  "overrides": {
    "Program.fs": {
      "line": 85.5,
      "branch": 77.0,
      "reason": "CLI entry point -- exit calls are not coverable"
    },
    "Api.fs": {
      "line": 92.38,
      "branch": 73.33,
      "reason": "Reflection branches generated by compiler"
    }
  }
}

Config fields

Files not listed in overrides must have 100% line and branch coverage.

Example Output

  Program.fs: line 87.2% >= 85.5% PASS | branch 80.0% >= 77.0% PASS
  Sync.fs:    line 100%  >= 100%  PASS | branch 100%  >= 100%  PASS
  Api.fs:     line 90.0% >= 92.38% FAIL | branch 75.0% >= 73.33% PASS

Typical CI Setup

1. Run your tests with coverage enabled (e.g., dotnet test --collect:"XPlat Code Coverage")
2. Run coverageratchet check to enforce thresholds
3. Run coverageratchet locally after improving tests to lock in coverage gains

License

MIT