Ruby SimpleCov "Coverage Below Minimum" Fails the Build in CI

SimpleCov enforced a minimum coverage threshold and the measured coverage fell below it. Either coverage genuinely dropped, or per-worker results were not merged so SimpleCov only saw a fraction of the suite.

What this error means

CI fails at the end of the test run with "Coverage (X%) is below the expected minimum coverage (Y%)". Sometimes the number is implausibly low because parallel workers reported separately instead of merging.

SimpleCov failed with exit 2 due to a coverage related error
Line coverage (47.2%) is below the expected minimum coverage (90.0%).

Common causes

Parallel worker results not merged

With parallel_tests each worker writes its own resultset. Without merging, SimpleCov evaluates one worker’s partial coverage and reports a falsely low number under the threshold.

A genuine coverage regression

New code without tests, or removed tests, legitimately drops coverage below the configured minimum_coverage.

How to fix it

Merge results across parallel workers

Enable result merging and use a collation step so SimpleCov sees the whole suite.

# spec_helper / simplecov setup
SimpleCov.use_merging true
SimpleCov.merge_timeout 3600
# with parallel_tests, collate after the run
bundle exec rake parallel:spec
bundle exec rake simplecov:collate

Address a real coverage drop

1. Open the SimpleCov HTML report to see which files lost coverage.
2. Add tests for the newly uncovered code, or adjust the threshold deliberately.
3. Confirm the threshold reflects merged, whole-suite coverage, not one worker.

How to prevent it

• Merge SimpleCov results across parallel workers before evaluating the threshold.
• Review the coverage report when the minimum fails rather than just lowering it.
• Keep the minimum aligned with the full merged suite.

Related guides