SimpleCov is a code coverage tool for Ruby

What SimpleCov does

SimpleCov is a code coverage analysis tool for Ruby. It uses Ruby's built-in Coverage library to gather coverage data, but it makes the results far easier to work with by providing a clean API to filter, group, merge, format, and display them. The README says you can get a full coverage setup running in a couple of lines of code.

SimpleCov tracks the Ruby code that your tests exercise. In most cases you want one overall number that spans every part of your suite, from unit tests to integration tests. SimpleCov handles this by caching and merging results as it builds reports, so the final report reflects coverage across the whole test suite and gives a truer picture of where your blind spots are.

SimpleCov bundles two formatters. The default HTML formatter renders the browsable report, and a JSON formatter is also included. Both used to be separate gems, simplecov-html and simplecov_json_formatter, but they are now built in and configured automatically when you launch SimpleCov. A wide range of alternate formatters are distributed as separate gems.

Getting started in a few lines

The first step is to add SimpleCov to your Gemfile and run bundle install. The README suggests placing it in the test group with require disabled.

require 'simplecov'
SimpleCov.start

# Previous content of test helper now starts here

You load and launch SimpleCov at the very top of your test helper, whether that is test/test_helper.rb, spec/spec_helper.rb, rails_helper.rb, or Cucumber's features/support/env.rb. SimpleCov does not care which framework you run; it simply watches what code executes and reports on it, so the same two lines work everywhere.

The README is firm that SimpleCov.start must run before any of your application code is required. Otherwise SimpleCov and the Coverage library underneath it cannot track those files. This bites hardest with tools that keep your app loaded between runs, such as Spring. For a server process tested from a separate test process, you require SimpleCov in the server process itself. For Rails, you add it near the top of bin/rails.

After that, you run your full test suite and open the HTML report. The bundled simplecov CLI picks the right opener for your platform: open on macOS, xdg-open on Linux or BSD, and start on Windows. You can pass --report PATH to open a non-default location. It is also common to keep coverage results out of Git by adding the coverage directory to .gitignore. For Rails, a built-in rails profile sets up groups for your Controllers, Models, Helpers, and Libraries.

require 'simplecov'
SimpleCov.start 'rails'

Configuration at a glance

Configuration lives in your start block, or in a .simplecov file at the project root when several suites share it. The API is built around a small set of consistent verbs: formatters are picked by name, thresholds live in a per-criterion coverage block where scope is a uniform per: argument, and misses can be capped as absolute counts rather than ratios.

SimpleCov.start do
  enable_coverage :branch            # track branches as well as lines
  cover "{app,lib}/**/*.rb"          # report on these files, even if never loaded
  skip "app/legacy"                  # ...but leave these out
  group "Models", "app/models"       # organize the report into groups

  coverage :line do
    minimum      90                  # fail the suite below 90% line coverage
    maximum_drop 1                   # ...or when coverage drops more than 1%
    maximum_missed 5, per: :file     # no file may carry more than 5 uncovered lines
  end

  coverage :branch, minimum: 80, ignore: :implicit_else
end

Everything you used before keeps working. Legacy spellings warn and name their replacement, and once you have migrated, deprecations :raise turns any old spelling that creeps back in into an error.

Tracking which test covers each line

Ordinary coverage tells you whether a line ran, not what ran it. The track_tests option records the other half of the story. RSpec examples and Minitest tests are wrapped automatically. In the HTML report, covered lines that no test actually executed, because they only ran at load time or during suite setup, drain to a distinct tint. This way coverage that merely loads code stops standing in for coverage that tests it, and clicking a line's badge lists the tests that cover it.

The same recording answers from the terminal. Running simplecov tests against a file and line, such as lib/simplecov/result.rb:42, returns the test that covers it, for example spec/result_spec.rb:42. The output is one test id per line and nothing else, so it pipes straight into a runner.

Coverage of just your change, and of production

An overall number moves slowly on a mature codebase, but the question of whether the code in a given change is tested has a crisp answer. The simplecov patch command reads the git diff against a base ref and scores only the lines you touched. A --minimum flag turns it into a gate, so a project that cannot lift its overall number in one pull request can still require that everything it adds is covered. The simplecov affected command uses a track_tests recording to select the tests that touch your changed code and hand them to the runner.

SimpleCov can also measure production code usage, which is the surest way to find dead code. Oneshot coverage runs that experiment for every line at once: a line reports its first execution and nothing after, so a live process records what real traffic uses with minimal performance impact. The simplecov dead-code command then crosses that recording with the test report. Code neither tests nor traffic touch is safe to delete.

Views, per-file ratchets, and history

View templates run real logic, and SimpleCov can bring them into the report through cover_views, measured with eval coverage for ERB, Haml, and Slim. Templates appear as ordinary files in the report, grouped under Views by the rails profile, and a template no test renders shows up at zero percent instead of being quietly missing.

On a legacy codebase a single per-file minimum is not very useful, so simplecov ratchet writes a checked-in baseline that gives each file its own floor at the coverage it has already reached. Floors only ever tighten, so touching a legacy file drags its coverage upward and it can never slide back. Alongside the floors, every successful run appends to coverage/.history.json, so you have a recorded trend rather than just the last number. The simplecov history command draws it as sparklines, and drop_baseline :median judges drops against the recorded median.

The command line toolbelt

The simplecov CLI has grown from a report opener into a set of tools. simplecov watch re-runs on save and live-reloads the served report. simplecov show prints annotated source in the terminal. simplecov status reports whether the report is fresh and for which commit. simplecov uncovered --missing lists the worst files with the exact line ranges to test. simplecov badge --output writes a shields.io style SVG without needing a badge service.

With a track_tests recording in the report, watch re-runs only the tests that touch the files you changed, which turns the report into something you keep open while writing the test. There is also shell tab completion, a man page, and a real --help on every command.

Editorial conclusion

SimpleCov is a Ruby code coverage tool that builds on the language's built-in Coverage library and adds a clean API for filtering, grouping, merging, formatting, and displaying results. It merges data across your whole suite, ships HTML and JSON formatters out of the box, and exposes a CLI that can focus on a single change, hunt dead code in production, or track coverage history. For Ruby teams that want coverage tied to individual tests and gated per pull request, it offers a pragmatic, well-documented path.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. simplecov-ruby/simplecov on GitHub