SimpleCov

Code coverage for Ruby

• Source Code
• API documentation
• Configuration
• Changelog
• Rubygem
• Continuous Integration

SimpleCov is a code coverage analysis tool for Ruby. It uses Ruby's built-in Coverage library to gather coverage data, but makes processing the results much easier by providing a clean API to filter, group, merge, format, and display them — a complete coverage suite you can set up in just a couple of lines.

SimpleCov tracks covered Ruby code; gathering coverage for templating solutions like ERB, Slim, and Haml is not supported (though see Eval coverage for ERB).

In most cases you'll want overall coverage results spanning all of your tests — unit tests, Cucumber features, and so on. SimpleCov handles this automatically by caching and merging results as it generates reports, so a report reflects coverage across your whole test suite and gives you a truer picture of your blank spots.

SimpleCov bundles two formatters that need no extra gems: the default HTML formatter (which renders the browsable report) and a JSON formatter. Both were once separate gems (simplecov-html and simplecov_json_formatter) but are now built into SimpleCov and configured automatically when you launch it.

Getting started

1. Add SimpleCov to your Gemfile and bundle install:

   gem 'simplecov', require: false, group: :test
   

2. Load and launch SimpleCov at the very top of your test helper — test/test_helper.rb, spec/spec_helper.rb, rails_helper.rb, Cucumber's features/support/env.rb, or whatever setup file your framework uses. SimpleCov doesn't care which framework you run in; it just watches what code executes and reports on it, so the same two lines work everywhere:

   require 'simplecov'
   SimpleCov.start
   
   # Previous content of test helper now starts here
   

   Important: SimpleCov.start must run before any of your application code is required — otherwise SimpleCov (and the underlying Coverage library) can't track those files. This bites hardest with tools that keep your app loaded between runs, like Spring; see the Spring section.

   SimpleCov must run in the process you want to analyze. When you test a server process (e.g. a JSON API) from a separate test process (e.g. via Selenium) and want to see all code the rails server executes — not just code in your test files — require SimpleCov in the server process. For Rails, add this near the top of bin/rails, below the shebang and after config/boot is required:

   if ENV['RAILS_ENV'] == 'test'
     require 'simplecov'
     SimpleCov.start 'rails'
   end
   

3. Run your full test suite to see your application's coverage.

4. Open the HTML report in your default browser:

   simplecov open
   

   (The bundled simplecov CLI picks the right opener for your platform — open on macOS, xdg-open on Linux/BSD, start on Windows. Pass --report PATH to open a non-default location. See Command-line interface for the full set of subcommands.)

5. Optionally, keep coverage results out of Git:

   echo coverage >> .gitignore
   

For Rails applications, SimpleCov ships a built-in rails profile that sets up groups for your Controllers, Models, Helpers, and Libraries:

require 'simplecov'
SimpleCov.start 'rails'

Example output

Coverage results report, fully browsable locally with sorting and much more:

Source file coverage details view:

Configuration

Configuration settings can be applied in three equivalent formats:

• Directly in your start block (the most common way):

  SimpleCov.start do
    some_config_option 'foo'
  end
  

• As direct setters:

  SimpleCov.some_config_option 'foo'
  

• In a configure block — useful when you don't want to start coverage immediately, or want to add configuration later:

  SimpleCov.configure do
    some_config_option 'foo'
  end
  

See the Configuration API documentation for the full list of options.

Using .simplecov for centralized config

If you merge multiple test-suite results (e.g. RSpec and Cucumber) into a single report, you'd otherwise have to repeat your filters / groups / profile in every test helper. To avoid that, place a .simplecov file at your project root with the shared configuration; each test helper then requires SimpleCov and explicitly starts it:

# .simplecov — configuration only
SimpleCov.load_profile 'rails'
SimpleCov.skip 'lib/generators'
SimpleCov.group 'Models', 'app/models'

# spec/spec_helper.rb
require 'simplecov'
SimpleCov.start

# features/support/env.rb
require 'simplecov'
SimpleCov.start

This is recommended whenever you merge frameworks that rely on each other, like Cucumber and RSpec.

[!NOTE] Calling SimpleCov.start directly from .simplecov is deprecated. Tracking still begins for backward compatibility, but a one-time deprecation warning fires; a future release will require the explicit SimpleCov.start from a test helper. Migrating prevents a long-standing bug where .simplecov auto-loaded in a Rakefile or Rails' Bundler.require would leave an empty parent-process report that overwrites the test subprocess's good one. See #581.

Changing the report location

By default the report ends up in SimpleCov.root / SimpleCov.coverage_dir. For out-of-tree build setups (CMake/CTest, Bazel, etc.) — where the build directory is elsewhere on the filesystem and you don't want the report under the source root — set SimpleCov.coverage_path directly:

SimpleCov.start do
  root '/source/checkout'
  coverage_path '/tmp/build/coverage'
end

Setting coverage_path explicitly pins the destination — subsequent changes to root or coverage_dir don't move it. The directory is created if it doesn't already exist.

Running coverage only on demand

The Ruby STDLIB Coverage library is very fast (on a ~10-minute Rails suite the slowdown is only a couple of seconds), so SimpleCov's policy is to generate coverage on every run — it costs you almost nothing and you always have the latest results. There's therefore no built-in on-demand switch, but you can add one with an ENV conditional:

SimpleCov.start if ENV["COVERAGE"]

Then coverage runs only when you ask for it:

COVERAGE=true rake test

Migrating from the legacy configuration API

The configuration API was redesigned to use a smaller set of consistent verbs. The legacy methods continue to work but emit deprecation warnings that name their replacement; the table below is the canonical migration map.

Legacy	New	Notes
add_filter "lib/legacy"	skip "lib/legacy"	Identical matcher grammar (string = path-segment substring; Regexp; block; Array). No behavior change.
add_group "Models", "app/models"	group "Models", "app/models"	Identical matcher grammar. No behavior change.
track_files "lib/**/*.rb"	cover "lib/**/*.rb"	cover includes unloaded files (the legacy track_files behavior) and restricts the report to the matching set. To keep the old additive-only behavior, pass every directory you want reported: cover "lib/**/*.rb", "app/**/*.rb".
use_merging false	merging false	Same value, same behavior.
enable_for_subprocesses true	merge_subprocesses true	Same value, same behavior.
enable_coverage_for_eval	enable_coverage :eval	Eval coverage now folds into the same call you use to enable :line/:branch/:method: enable_coverage :branch, :eval.
print_error_status (reader)	print_errors	Reader only. The print_error_status= writer still works without a warning, but print_errors true/print_errors false is the new spelling.
minimum_coverage_by_file line: 70, 'app/x.rb' => 100	coverage(:line) { minimum_per_file 70; minimum_per_file 100, only: 'app/x.rb' }	The coverage block fixes the criterion, so per-path overrides are plain percentages with an only: target instead of a hash mixing Symbol / String / Regexp keys. See Per-criterion thresholds.
minimum_coverage_by_group 'Models' => { line: 90 }	coverage(:line) { minimum_per_group 90, only: 'Models' }	Same uniform shape as minimum_per_file.

Brand-new in the redesigned API (no legacy method to migrate from):

Method	Purpose
cover "lib/**/*.rb"	Positive scope (allowlist). Multiple calls union; strings are globs. See above for the relationship with track_files.
no_default_skips	Clear every previously-installed filter — defaults and anything earlier in the block — so subsequent skips start clean.
formatter false / formatters []	Opt out of formatting entirely. Workers in big parallel CI runs only need their .resultset.json for a