The simplecov-rspec Gem

simplecov-rspec is a Ruby gem that integrates SimpleCov with RSpec. SimpleCov (>= 1.0) already enforces minimum_coverage for line, branch, and method coverage and fails the build when a threshold is missed. This gem layers three things on top that SimpleCov doesn't do on its own:

1. Suppresses coverage failures when RSpec is run in dry-run mode (e.g. from an IDE).
2. Lists (or summarizes) the individual uncovered lines, branches, and methods.
3. Lets all of the above be overridden from the environment, for CI.

When simplecov-rspec is used, RSpec will report an error if the percent of test coverage falls below a defined threshold:

Coverage report generated for RSpec to /Projects/example_project/coverage. 284 / 286 LOC (99.3%) covered.

Line coverage (99.3%) is below the expected minimum coverage (100.00%).

If configured to list the items that were not covered by tests, RSpec will additionally output:

2 lines are not covered by tests:
  ./lib/example_project.rb:74
  ./lib/example_project.rb:75

• Installation
• Getting started
  • Basic setup
  • Listing uncovered items
  • Configuration block
  • Configuration from environment variables
• Development
• Contributing
  • Commit message guidelines
  • Pull request guidelines
• License
• Code of conduct

Installation

To install the gem, add to the following line to your application's gemspec OR Gemfile:

gemspec:

  spec.add_development_dependency "simplecov-rspec", '~> 1.0'

Gemfile:

gem "simplecov-rspec", "~> 1.0", groups: [:development, :test]

and then run bundle install

If bundler is not being used to manage dependencies, install the gem by executing:

gem install simplecov-rspec

Getting started

To use simplecov-rspec, follow these steps:

1. Add require 'simplecov-rspec' to your spec_helper.rb.
2. Replace SimpleCov.start with SimpleCov::RSpec.start in your spec_helper.rb, ensuring this line appears before requiring your project files.

Here is an example spec_helper.rb. Your spec helper may include other code in addition to these:

require 'simplecov-rspec'

SimpleCov::RSpec.start

require 'my_project'

This will configure RSpec to fail when test coverage falls below 100%.

That is it!

Basic setup

To initialize simplecov-rspec with defaults, add the following to your spec_helper.rb:

require 'simplecov-rspec'

SimpleCov::RSpec.start

This is equivalent to starting with the following options:

SimpleCov::RSpec.start(
    minimum_coverage: { line: 100 },
    fail_on_low_coverage: true,
    list_uncovered: false,
    list_uncovered_detail: true
)

minimum_coverage is the minimum percent of lines (and, optionally, branches and methods) covered by tests, enforced by SimpleCov itself.

To require less than 100% line coverage:

SimpleCov::RSpec.start(minimum_coverage: 90)

To also require branch (and/or method) coverage, pass a Hash. Any criterion named here is automatically enabled via SimpleCov.enable_coverage:

SimpleCov::RSpec.start(minimum_coverage: { line: 100, branch: 90 })

Listing uncovered items

To list the individual lines, branches, and/or methods that are not covered, set list_uncovered. It accepts :all, a single criterion, or an Array of criteria — independent of what minimum_coverage enforces:

SimpleCov::RSpec.start(minimum_coverage: { line: 100, branch: 90 }, list_uncovered: :all)

1 line is not covered by tests:
  ./lib/example_project.rb:74

1 branch is not covered by tests:
  ./lib/example_project.rb:82 (else branch)

For a quieter CI log, set list_uncovered_detail: false to print only the count per criterion, along with a hint on how to see the details:

SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_detail: false)

2 lines are not covered by tests.
1 branch is not covered by tests.

Run with LIST_UNCOVERED_DETAIL=true to see the uncovered lines and branches.

Configuration block

A configuration block can be given to the start method to further configure SimpleCov:

# Initialize SimpleCov with a specific formatter
SimpleCov::RSpec.start { formatter SimpleCov::Formatter::LcovFormatter }

This block is passed on to SimpleCov.start. See Configuring SimpleCov for details.

Configuration from environment variables

Environment variables can be used to configure simplecov-rspec. These environment variables take precedence over the values passed to SimpleCov::RSpec.start.

• COVERAGE_THRESHOLD: Sets the minimum line coverage threshold (0-100). Overrides minimum_coverage[:line].
• COVERAGE_THRESHOLD_BRANCH: Sets the minimum branch coverage threshold (0-100), and enables branch coverage. Overrides minimum_coverage[:branch].
• COVERAGE_THRESHOLD_METHOD: Sets the minimum method coverage threshold (0-100), and enables method coverage. Overrides minimum_coverage[:method].
• FAIL_ON_LOW_COVERAGE: Controls whether tests fail if coverage is below the threshold. Set to 'true', 'yes', 'on', or '1' (case insensitive) to enable.
• LIST_UNCOVERED: Controls which criteria to list uncovered items for. Set to 'all', 'true', 'yes', 'on', or '1' to report every criterion; 'false', 'no', 'off', or '0' to report none; or a comma-separated list, e.g. line,branch.
• LIST_UNCOVERED_DETAIL: Controls whether uncovered items are listed individually, or just summarized as a count per criterion. Set to 'true', 'yes', 'on', or '1' (case insensitive) to show individual items.

For example, here is a bash script to run tests in an infinite loop while writing test output to fail.txt:

while true; do FAIL_ON_LOW_COVERAGE=false rspec >> fail.txt; done

In a CI system, you might want to set LIST_UNCOVERED=all in order to list uncovered lines, branches, and methods on a platform other than the one you use for local development.

Development

If you want to contribute or experiment with the gem, follow these steps to set up your development environment:

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run linting, tests, etc. just like the CI build. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/main-branch/simplecov-rspec. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Commit message guidelines

All commit messages must follow the Conventional Commits standard. This helps us maintain a clear and structured commit history, automate versioning, and generate changelogs effectively.

To ensure compliance, this project includes:

• A git commit-msg hook that validates your commit messages before they are accepted.

To activate the hook, you must have node installed and run npm install.

• A GitHub Actions workflow that will enforce the Conventional Commit standard as part of the continuous integration pipeline.

Any commit message that does not conform to the Conventional Commits standard will cause the workflow to fail and not allow the PR to be merged.

Pull request guidelines

All pull requests must be merged using rebase merges. This ensures that commit messages from the feature branch are preserved in the release branch, keeping the history clean and meaningful.

License

The gem is available as open source under the terms of the MIT License.

Code of conduct

Everyone interacting in the Simplecov::Rspec project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.