DOCSEARCHbyAlgolia
Submit Docs

SimpleCov Documentation

repository·main·Indexed 26 days ago

https://github.com/simplecov-ruby/simplecov

A code coverage analysis tool for Ruby that leverages the built-in Coverage library. SimpleCov provides a high-level API to filter, group, merge, and format coverage results into HTML or JSON reports. It supports multiple coverage criteria including line, branch, method, oneshot_line, and eval coverage, and includes built-in profiles for Rails applications.

Tokens
15.9K
Snippets
54
Records
100
Agent score
84%

What's inside SimpleCov

  1. Run a test suite with coverage using `simplecov run`

    main

    If your project does not have a test_helper.rb hook calling SimpleCov.start, you can use simplecov run to execute your test command with SimpleCov pre-loaded. This sets RUBYOPT=-rsimplecov/autostart for the process and all its subprocesses (like parallel workers). If a .simplecov config already exists, the autostart shim will defer to it and avoid double-starting.

    $ simplecov run bundle exec rspec
$ simplecov run -- bundle exec rake test
$ simplecov run ruby my_test.rb

  3. Use regex filters for file removal

    main
    Starting from version 0.15.0, you can use regular expressions as filters to remove specific files from your coverage output. Note that in version 0.16.0, string filters stopped being automatically treated as regular expressions; if you require regex behavior, you must use a dedicated regex filter.

  4. Configure SimpleCov for Knapsack Pro Queue Mode

    main
    To use SimpleCov with Knapsack Pro Queue Mode for parallel test splitting on CI, you must provide the CI node index number to SimpleCov.command_name within the KnapsackPro::Hooks::Queue.before_queue hook.

  5. Use .simplecov for centralized configuration

    main

    To avoid repeating filters, groups, or profiles across multiple test suites (e.g., RSpec and Cucumber), place a .simplecov file in your project root. Each test helper should then require SimpleCov and explicitly call SimpleCov.start.

    Note: Do not call SimpleCov.start inside the .simplecov file itself, as this is deprecated and can cause bugs in Rakefiles or Rails environments. Use .simplecov for configuration only.

    # .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

  6. Observe spawned subprocesses

    main

    To cover scripts launched via Process.spawn, Open3.popen, etc., create a .simplecov_spawn.rb file in your project root to handle the setup. Then, launch your script by requiring this file using the ruby -r flag.

    # .simplecov_spawn.rb
require 'simplecov'
SimpleCov.command_name 'spawn'
SimpleCov.at_fork.call(Process.pid)
SimpleCov.start
    # Launching the script
PTY.spawn('ruby -r./.simplecov_spawn my_script.rb')

  7. Integrate SimpleCov with Atom, Sublime, or Vim

    main

    SimpleCov supports graphical integrations for several text editors to visualize test coverage directly within your development environment:

    • Atom: Use the coverage package by Philip Giuliani to add a coverage overview to the editor.
    • Sublime Text: Use the SimpleCov package by sentience to enable live coverage highlighting, status bar information, and coverage summaries.
    • Vim: Use cadre by Judson Lester, which includes a SimpleCov formatter that emits Vim script to mark up code files with coverage data.

  8. Run coverage only on demand

    main

    SimpleCov does not have a built-in on-demand switch, but you can implement one using an environment variable conditional in your test helper:

    SimpleCov.start if ENV["COVERAGE"]

    To run coverage, execute your tests with the variable set:

    COVERAGE=true rake test

  9. Use SimpleCov with Spring

    main

    Spring can cause misreported coverage due to eager-loading issues. Use one of the following solutions:

    Option 1: Explicitly call eager load in your test_helper.rb or spec_helper.rb immediately after SimpleCov.start:

    require 'simplecov'
SimpleCov.start 'rails'
Rails.application.eager_load!

    Option 2: Disable Spring when running coverage:

    DISABLE_SPRING=1 rake test

    Option 3: Remove Spring from your Gemfile.

  10. Configure centralized configuration via .simplecov

    main
    As of version 0.5.0, you can place your SimpleCov configuration in a .simplecov file located in your application root. This file is automatically read when you require 'simplecov', allowing you to share groups and filters across multiple test suites easily. You can place your entire SimpleCov.start (...) block inside this file.

  11. Ignore or skip specific code blocks

    main

    Use magic comments to disable coverage for specific spans of code. The available categories are line, branch, and method. You can combine them with commas or omit them to target all three.

    Directives:

    • # simplecov:disable [category]
    • # simplecov:enable [category]

    Rules:

    • Inline directives (on the same line as code) only affect that specific line.
    • Block directives remain in effect until a matching # simplecov:enable is found or the file ends.
    • Directives inside string literals or heredocs are ignored.

    Warning: The older # :nocov: toggle is deprecated and will be removed in a future release.

    # simplecov:disable line
def skipped_lines
  never_reached
end
# simplecov:enable line

# simplecov:disable branch, method legacy adapter, scheduled for removal
class LegacyAdapter
  def call(value)
    value ? :yes : :no
  end
end
# simplecov:enable

raise "absurd" # simplecov:disable

  12. Load SimpleCov without default settings

    main

    If you want to prevent SimpleCov from applying its default preconfigurations, you can either:

    1. Require simplecov/no_defaults instead of the standard simplecov.
    2. Set the SIMPLECOV_NO_DEFAULTS environment variable.

    This feature was introduced in version 0.8.0.

    require 'simplecov/no_defaults'