SimpleCov

https://www.rubydoc.info/gems/simplecov/0.22.0
Admin
SimpleCov is a code coverage analysis tool for Ruby that measures how much of your code is tested...
Tokens:5,746
Snippets:90
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start SimpleCov Coverage

Source: https://www.rubydoc.info/gems/simplecov

Include this line in your test helper file (e.g., spec_helper.rb, rails_helper.rb, test_helper.rb) to start SimpleCov. It will automatically load and measure your code.

```ruby
SimpleCov.start
puts "SimpleCov started successfully!"

```

--------------------------------

### Configuring SimpleCov with a Rails Profile

Source: https://www.rubydoc.info/gems/simplecov

Start SimpleCov with a 'rails' profile and customize its behavior within a block. This example sets a unique command name for CI environments and configures formatters and tracked files.

```ruby
# spec/spec_helper.rb
require 'simplecov'

SimpleCov.start 'rails' do
  # Disambiguates individual test runs
  command_name "Job #{ENV["TEST_ENV_NUMBER"]}" if ENV["TEST_ENV_NUMBER"]

  if ENV['CI']
    formatter SimpleCov::Formatter::SimpleFormatter
  else
    formatter SimpleCov::Formatter::MultiFormatter.new([
      SimpleCov::Formatter::SimpleFormatter,
      SimpleCov::Formatter::HTMLFormatter
    ])
  end

  track_files "**/*.rb"
end


```

--------------------------------

### Initialize SimpleCov

Source: https://www.rubydoc.info/gems/simplecov

Load and start SimpleCov at the very top of your test helper file before any application code is loaded.

```ruby
require 'simplecov'
SimpleCov.start
```

--------------------------------

### SimpleCov.start

Source: https://www.rubydoc.info/gems/simplecov

Initializes and starts the SimpleCov code coverage tracking. This must be called at the very top of your test helper file.

```APIDOC
## SimpleCov.start

### Description
Starts the SimpleCov coverage tracking. This method should be invoked before any application code is loaded to ensure accurate coverage reporting.

### Method
Ruby Method Call

### Request Example
require 'simplecov'
SimpleCov.start
```

--------------------------------

### Install SimpleCov via Gemfile

Source: https://www.rubydoc.info/gems/simplecov

Add the gem to your project's Gemfile within the test group.

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

--------------------------------

### Branch coverage examples

Source: https://www.rubydoc.info/gems/simplecov

Examples of code structures where branch coverage provides more insight than line coverage.

```ruby
number.odd? ? "odd" : "even"

```

```ruby
return if number.odd?

# more code

```

--------------------------------

### Conditional SimpleCov Start

Source: https://www.rubydoc.info/gems/simplecov

Enables running SimpleCov coverage only on demand by checking an environment variable. This is useful for performance-sensitive scenarios where coverage is not always needed.

```ruby
SimpleCov.start if ENV["COVERAGE"]
```

--------------------------------

### Verify file loading

Source: https://www.rubydoc.info/gems/simplecov

Use a puts statement to debug whether a file is loaded after SimpleCov has started.

```ruby
# my_code.rb
class MyCode

  puts "MyCode is being loaded!"

  def my_method
    # ...
  end
end

```

--------------------------------

### SimpleCov Spawn Configuration

Source: https://www.rubydoc.info/gems/simplecov

Configuration for running SimpleCov against spawned subprocesses using tools like PTY.spawn or Open3.popen. It ensures proper command naming and starts SimpleCov after forking.

```ruby
# .simplecov_spawn.rb
require 'simplecov' # this will also pick up whatever config is in .simplecov
                    # so ensure it just contains configuration, and doesn't call SimpleCov.start.
SimpleCov.command_name 'spawn' # As this is not for a test runner directly, script doesn't have a pre-defined base command_name
SimpleCov.at_fork.call(Process.pid) # Use the per-process setup described previously
SimpleCov.start # only now can we start.
```

--------------------------------

### Define a Regex filter

Source: https://www.rubydoc.info/gems/simplecov

Removes files that start with the specified pattern in their path.

```ruby
SimpleCov.start do
  add_filter %r{^/test/}
end

```

--------------------------------

### Enable SimpleCov for Subprocesses

Source: https://www.rubydoc.info/gems/simplecov

Allows SimpleCov to observe subprocesses started with Process.fork. It modifies Process.fork to append subprocess information to the command name for merging results.

```ruby
SimpleCov.enable_for_subprocesses true
SimpleCov.at_fork do |pid|
  # This needs a unique name so it won't be ovewritten
  SimpleCov.command_name "#{SimpleCov.command_name} (subprocess: #{pid})"
  # be quiet, the parent process will be in charge of output and checking coverage totals
  SimpleCov.print_error_status = false
  SimpleCov.formatter SimpleCov::Formatter::SimpleFormatter
  SimpleCov.minimum_coverage 0
  # start
  SimpleCov.start
end
```

--------------------------------

### Customizing Test Suite Names with SimpleCov

Source: https://www.rubydoc.info/gems/simplecov

Specify `SimpleCov.command_name` in a test file to assign a custom name to the test suite. This is useful for non-standard setups or to ensure unique names for parallel test runs.

```ruby
# test/unit/some_test.rb
SimpleCov.command_name 'test:units'
```

```ruby
# test/functionals/some_controller_test.rb
SimpleCov.command_name "test:functionals"
```

```ruby
# test/integration/some_integration_test.rb
SimpleCov.command_name "test:integration"
```

```ruby
# features/support/env.rb
SimpleCov.command_name "features"
```

--------------------------------

### Configure SimpleCov options

Source: https://www.rubydoc.info/gems/simplecov

Three equivalent ways to apply configuration settings to SimpleCov.

```ruby
SimpleCov.start do
  some_config_option 'foo'
end

```

```ruby
SimpleCov.some_config_option 'foo'

```

```ruby
SimpleCov.configure do
  some_config_option 'foo'
end

```

--------------------------------

### Initialize SimpleCov in Rails server process

Source: https://www.rubydoc.info/gems/simplecov

Add this to the top of bin/rails to track coverage for server processes.

```ruby
if ENV['RAILS_ENV'] == 'test'
  require 'simplecov'
  SimpleCov.start 'rails'
  puts "required simplecov"
end
```

--------------------------------

### Centralize configuration with .simplecov

Source: https://www.rubydoc.info/gems/simplecov

Use a .simplecov file in the project root to share configuration across multiple test suites.

```ruby
# test/test_helper.rb
require 'simplecov'

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

# .simplecov
SimpleCov.start 'rails' do
  # any custom configs like groups and filters can be here at a central place
end

```

--------------------------------

### Load and Use Custom SimpleCov Profile

Source: https://www.rubydoc.info/gems/simplecov

Demonstrates how to load and use a custom SimpleCov profile ('myprofile') that builds upon an existing profile ('rails') and adds further customization. This is useful for reusing configuration across different test environments.

```ruby
# lib/simplecov_custom_profile.rb
require 'simplecov'
SimpleCov.profiles.define 'myprofile' do
  load_profile 'rails'
  add_filter 'vendor' # Don't include vendored stuff
end
```

```ruby
# features/support/env.rb
require 'simplecov_custom_profile'
SimpleCov.start 'myprofile'
```

```ruby
# test/test_helper.rb
require 'simplecov_custom_profile'
SimpleCov.start 'myprofile'
```

--------------------------------

### Configure Spring for SimpleCov

Source: https://www.rubydoc.info/gems/simplecov

Ensure accurate coverage reporting when using Spring by forcing eager loading.

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

```

```bash
DISABLE_SPRING=1 rake test

```

--------------------------------

### Open coverage report in browser

Source: https://www.rubydoc.info/gems/simplecov

Commands to open the generated HTML coverage report based on the operating system.

```bash
open coverage/index.html
```

```bash
xdg-open coverage/index.html
```

--------------------------------

### Enable JSON formatter

Source: https://www.rubydoc.info/gems/simplecov

Load and configure the JSON formatter for CI or external service reporting.

```ruby
require "simplecov_json_formatter"
SimpleCov.formatter = SimpleCov::Formatter::JSONFormatter

```

--------------------------------

### Initialize SimpleCov for Rails

Source: https://www.rubydoc.info/gems/simplecov

Standard initialization for Rails applications, placed at the top of the test helper.

```ruby
require 'simplecov'
SimpleCov.start 'rails'
```

--------------------------------

### Organize files into groups

Source: https://www.rubydoc.info/gems/simplecov

Categorizes source files into named groups based on path matching or custom logic.

```ruby
SimpleCov.start do
  add_group "Models", "app/models"
  add_group "Controllers", "app/controllers"
  add_group "Long files" do |src_file|
    src_file.lines.count > 100
  end
  add_group "Multiple Files", ["app/models", "app/controllers"] # You can also pass in an array
  add_group "Short files", LineFilter.new(5) # Using the LineFilter class defined in Filters section above
end

```

--------------------------------

### Set minimum coverage thresholds

Source: https://www.rubydoc.info/gems/simplecov

Define the minimum expected coverage percentage; SimpleCov returns a non-zero exit code if the threshold is not met.

```ruby
SimpleCov.minimum_coverage 90
# same as above (the default is to check line coverage)
SimpleCov.minimum_coverage line: 90
# check for a minimum line coverage of 90% and minimum 80% branch coverage
SimpleCov.minimum_coverage line: 90, branch: 80

```

--------------------------------

### Set minimum coverage by file

Source: https://www.rubydoc.info/gems/simplecov

Define minimum coverage requirements on a per-file basis to ensure consistent coverage across the codebase.

```ruby
SimpleCov.minimum_coverage_by_file 80
# same as above (the default is to check line coverage by file)
SimpleCov.minimum_coverage_by_file line: 80
# check for a minimum line coverage by file of 90% and minimum 80% branch coverage
SimpleCov.minimum_coverage_by_file line: 90, branch: 80

```

--------------------------------

### Enable branch coverage

Source: https://www.rubydoc.info/gems/simplecov

Measure branch coverage statistics for CRuby 2.5+.

```ruby
SimpleCov.start do
  enable_coverage :branch
end

```

--------------------------------

### Configure custom formatter

Source: https://www.rubydoc.info/gems/simplecov

Set a custom class to handle the formatting of coverage results.

```ruby
SimpleCov.formatter = SimpleCov::Formatter::HTMLFormatter

```

--------------------------------

### Customize SimpleCov exit behavior

Source: https://www.rubydoc.info/gems/simplecov

Define custom actions to execute when the test suite finishes.

```ruby
SimpleCov.at_exit do
  SimpleCov.result.format!
end

```

--------------------------------

### Configure multiple formatters

Source: https://www.rubydoc.info/gems/simplecov

Use multiple formatters simultaneously by wrapping them in a MultiFormatter.

```ruby
require "simplecov-html"

SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.new([
  SimpleCov::Formatter::HTMLFormatter,
  SimpleCov::Formatter::CSVFormatter,
])

```

--------------------------------

### Clear default root filters

Source: https://www.rubydoc.info/gems/simplecov

Demonstrates clearing default filters to include external files like Rails Engines.

```ruby
SimpleCov.start :rails do
  filters.clear # This will remove the :root_filter and :bundler_filter that come via simplecov's defaults
  add_filter do |src|
    !(src.filename =~ /^#{SimpleCov.root}/) unless src.filename =~ /my_engine/
  end
end

```

--------------------------------

### Define a Block filter

Source: https://www.rubydoc.info/gems/simplecov

Uses a block to evaluate SimpleCov::SourceFile instances; returning true excludes the file.

```ruby
SimpleCov.start do
  add_filter do |source_file|
    source_file.lines.count < 5
  end
end

```

--------------------------------

### Define a Custom filter class

Source: https://www.rubydoc.info/gems/simplecov

Inherit from SimpleCov::Filter and implement matches? to create reusable filter logic.

```ruby
class LineFilter < SimpleCov::Filter
  def matches?(source_file)
    source_file.lines.count < filter_argument
  end
end

SimpleCov.add_filter LineFilter.new(5)

```

--------------------------------

### Enable coverage for eval

Source: https://www.rubydoc.info/gems/simplecov

Measure coverage for code evaluated via Kernel#eval, supported in CRuby 3.2+.

```ruby
SimpleCov.start do
  enable_coverage_for_eval
end

```

--------------------------------

### Define a String filter

Source: https://www.rubydoc.info/gems/simplecov

Removes files matching the provided string in their path.

```ruby
SimpleCov.start do
  add_filter "/test/"
end

```

--------------------------------

### Ensuring Unique Command Names for Parallel Tests

Source: https://www.rubydoc.info/gems/simplecov

When running tests in parallel, ensure each process has a unique `command_name` to avoid coverage results clobbering each other. Incorporate `TEST_ENV_NUMBER` for proper merging with `parallel_tests`.

```ruby
# spec/spec_helper.rb
SimpleCov.command_name "features" + (ENV['TEST_ENV_NUMBER'] || '')
```

--------------------------------

### Rake Task for Coverage Report

Source: https://www.rubydoc.info/gems/simplecov

A Rake task to generate coverage reports using SimpleCov. It collates results from multiple sources and uses HTML and simple formatters.

```ruby
namespace :coverage do
  task :report do
    require 'simplecov'

    SimpleCov.collate Dir["simplecov-resultset-*\.resultset.json"], 'rails' do
      formatter SimpleCov::Formatter::MultiFormatter.new([
        SimpleCov::Formatter::SimpleFormatter,
        SimpleCov::Formatter::HTMLFormatter
      ])
    end
  end
end
```

--------------------------------

### Ignore coverage directory in Git

Source: https://www.rubydoc.info/gems/simplecov

Command to append the coverage directory to the .gitignore file.

```bash
echo coverage >> .gitignore
```

--------------------------------

### Configure maximum coverage drop

Source: https://www.rubydoc.info/gems/simplecov

Define the maximum allowed percentage drop in coverage between test runs.

```ruby
SimpleCov.maximum_coverage_drop 5
# same as above (the default is to check line drop)
SimpleCov.maximum_coverage_drop line: 5
# check for a maximum line drop of 5% and maximum 10% branch drop
SimpleCov.maximum_coverage_drop line: 5, branch: 10

```

--------------------------------

### Refuse coverage drops

Source: https://www.rubydoc.info/gems/simplecov

Prevent coverage from decreasing between test runs.

```ruby
SimpleCov.refuse_coverage_drop
# same as above (the default is to only refuse line drop)
SimpleCov.refuse_coverage_drop :line
# refuse drop for line and branch
SimpleCov.refuse_coverage_drop :line, :branch

```

--------------------------------

### Set primary coverage type

Source: https://www.rubydoc.info/gems/simplecov

Define the primary coverage metric used for output and minimum coverage checks.

```ruby
# or in configure SimpleCov.primary_coverage :branch
SimpleCov.start do
  enable_coverage :branch
  primary_coverage :branch
end

```

--------------------------------

### Collating Coverage Results from Multiple Test Runs

Source: https://www.rubydoc.info/gems/simplecov

Use `SimpleCov.collate` to merge coverage results from multiple `.resultset.json` files, typically generated by parallel test runs on different machines. This method accepts an optional profile and a configuration block.

```ruby
# lib/tasks/coverage_report.rake
namespace :coverage do
  desc "Collates all result sets generated by the different test runners"
  task :report do
    require 'simplecov'

    SimpleCov.collate Dir["simplecov-resultset-*
/.resultset.json"]
  end
end

```

--------------------------------

### Configuring Merge Timeout for Cached Coverage Data

Source: https://www.rubydoc.info/gems/simplecov

Set `SimpleCov.merge_timeout` to control how long cached coverage data remains valid. The default is 600 seconds (10 minutes).

```ruby
SimpleCov.merge_timeout 3600
```

--------------------------------

### Define Custom SimpleCov Profile

Source: https://www.rubydoc.info/gems/simplecov

Defines a custom SimpleCov profile named 'rails' with specific filters and group configurations. This profile can be used to tailor coverage reporting for Rails applications.

```ruby
SimpleCov.profiles.define 'rails' do
  add_filter '/test/'
  add_filter '/config/'

  add_group 'Controllers', 'app/controllers'
  add_group 'Models', 'app/models'
  add_group 'Helpers', 'app/helpers'
  add_group 'Libraries', 'lib'
end
```

--------------------------------

### Exclude code from coverage

Source: https://www.rubydoc.info/gems/simplecov

Wraps specific code blocks with # :nocov: to ignore them in reports.

```ruby
# :nocov:
def skip_this_method
  never_reached
end
# :nocov:

```

--------------------------------

### Define an Array filter

Source: https://www.rubydoc.info/gems/simplecov

Combines multiple filter types into a single array for processing.

```ruby
SimpleCov.start do
  proc = Proc.new { |source_file| false }
  add_filter ["string", /regex/, proc, LineFilter.new(5)]
end

```

--------------------------------

### Disabling Automatic Merging of Test Runs

Source: https://www.rubydoc.info/gems/simplecov

Use `SimpleCov.use_merging false` to disable the automatic merging of previous test runs' coverage data.

```ruby
SimpleCov.use_merging false
```

--------------------------------

### Disable SimpleCov Error Status Output

Source: https://www.rubydoc.info/gems/simplecov

Disables the printing of error messages to STDERR when SimpleCov encounters issues. This can be useful for cleaner output during test runs.

```ruby
SimpleCov.print_error_status = false
```
Tokens:
Raw