Class: SimpleCov::RSpec

Inherits:
Object
  • Object
show all
Defined in:
lib/simplecov-rspec.rb,
lib/simplecov-rspec/uncovered_report.rb,
lib/simplecov-rspec/list_uncovered_option.rb,
lib/simplecov-rspec/described_source_files.rb,
lib/simplecov-rspec/list_uncovered_files_option.rb

Overview

Configure SimpleCov to enforce coverage thresholds for RSpec, on top of what SimpleCov itself already provides.

SimpleCov (>= 1.0) can already enforce minimum_coverage for line, branch, and method coverage, and will exit with a non-zero status when a threshold is missed. This gem layers four things 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. Scopes that listing to the files you name, or to the code the run described.
  4. Lets all of the above be overridden from the environment, for CI.

Simply add the line SimpleCov::RSpec.start in place of SimpleCov.start in the project's spec_helper.rb. This line must appear before the project is required.

Examples:

Initialize SimpleCov with defaults (100% line coverage required)

SimpleCov::RSpec.start

Require 100% line coverage and 90% branch coverage

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

List every uncovered line, branch, and method when coverage is incomplete

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

Report only counts, with a hint on how to see the details

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

Scope the listing to the code the run described

SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_files: :described)

Pass a configuration block to SimpleCov.start

SimpleCov::RSpec.start { formatter SimpleCov::Formatter::LcovFormatter }

Defined Under Namespace

Modules: DescribedSourceFiles, ListUncoveredFilesOption, ListUncoveredOption Classes: UncoveredReport

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Attribute Details

#env ⇒ Hash (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The environment variables consulted for overrides

Returns:

  • (Hash) 



# File 'lib/simplecov-rspec.rb', line 48

#simplecov_module ⇒ Module (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The SimpleCov module being configured

Returns:

  • (Module) 



# File 'lib/simplecov-rspec.rb', line 48

#start_config_block ⇒ Proc? (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A configuration block passed through to SimpleCov.start

Returns:

  • (Proc, nil) 



# File 'lib/simplecov-rspec.rb', line 48

Class Method Details

.described_source_files ⇒ Array<String>

The source files defining the classes this RSpec run described

What list_uncovered_files: :described scopes to. Call it directly to build a scope of your own — to add files the run touches but does not describe, say:

list_uncovered_files: -> { SimpleCov::RSpec.described_source_files + ['lib/support.rb'] }

Only meaningful once the run has defined its examples, which is why it is passed as a callable rather than called at start.

A described class contributes nothing when it is anonymous, defined in C, or no longer reachable by name, since there is no source file to report on.

Examples:

Scope the listing to the code under test, plus one more file

SimpleCov::RSpec.start(
  list_uncovered: :all,
  list_uncovered_files: -> { SimpleCov::RSpec.described_source_files + ['lib/support.rb'] }
)

Returns:

  • (Array<String>) —

    absolute paths, without duplicates



199
 
# File 'lib/simplecov-rspec.rb', line 199

def self.described_source_files = DescribedSourceFiles.call

.start(minimum_coverage: { line: 100 }, fail_on_low_coverage: true, list_uncovered: false, list_uncovered_detail: true, rspec_dry_run: ::RSpec.configuration.dry_run?, env: ENV, &start_config_block) ⇒ Void

Configure and start SimpleCov for RSpec

Examples:

Initialize SimpleCov with defaults

SimpleCov::RSpec.start

Examples:

Initialize SimpleCov with a test coverage threshold other than 100%

SimpleCov::RSpec.start(minimum_coverage: 90)

Initialize SimpleCov to not fail the test run if the coverage is below the threshold

SimpleCov::RSpec.start(fail_on_low_coverage: false)

# OR use an environment variable to override the default
FAIL_ON_LOW_COVERAGE=true rspec

Initialize SimpleCov to list the lines, branches, and methods not covered by tests

SimpleCov::RSpec.start(list_uncovered: :all)

# OR use an environment variable to override the default
LIST_UNCOVERED=all rspec

List uncovered items for one file only

SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_files: 'lib/example_project/parser.rb')

# OR use an environment variable to override the default
LIST_UNCOVERED_FILES=lib/example_project/parser.rb rspec

Scope the listing to the classes the run actually described

SimpleCov::RSpec.start(list_uncovered: :all, list_uncovered_files: :described)

# OR use an environment variable to override the default
LIST_UNCOVERED_FILES=described rspec

Parameters:

  • minimum_coverage (Integer, Hash) (defaults to: { line: 100 }) —

    the minimum coverage threshold (default: { line: 100 })

    An Integer sets the line coverage threshold. A Hash sets a threshold per criterion, e.g. { line: 100, branch: 90, method: 100 }. Passed straight through to SimpleCov.minimum_coverage; any criterion given here is automatically enabled via SimpleCov.enable_coverage.

  • fail_on_low_coverage (Boolean) (defaults to: true) —

    whether to fail if coverage is below the threshold (default: true)

    When false (or when RSpec is in dry-run mode), SimpleCov.minimum_coverage is never set, so SimpleCov will not fail the build regardless of coverage.

    Read from the FAIL_ON_LOW_COVERAGE environment variable if set: true, yes, on, or 1 (case-insensitive) enables it; anything else disables it.

  • list_uncovered (false, :all, Symbol, Array<Symbol>) (defaults to: false) —

    which coverage criteria to list uncovered items for (default: false)

    false reports nothing. :all reports line, branch, and method. A Symbol or Array of Symbols (:line, :branch, :method) reports just those criteria, independent of what minimum_coverage enforces.

    Read from the LIST_UNCOVERED environment variable if set: all, true, yes, on, or 1 means every criterion; false, no, off, or 0 means none; otherwise a comma-separated list of criteria, e.g. line,branch.

  • list_uncovered_detail (Boolean) (defaults to: true) —

    list individual items, or just a count (default: true)

    When false, only the count of uncovered items per criterion is printed, followed by a hint on how to see the details.

    Read from the LIST_UNCOVERED_DETAIL environment variable if set: true, yes, on, or 1 (case-insensitive) shows details; anything else summarizes.

  • list_uncovered_files (nil, Symbol, String, Array<String>, #call) —

    which files to list uncovered items for (default: nil)

    nil reports on every file in the result. A String or Array of Strings names the files to report on, as Dir.glob patterns resolved against SimpleCov.root. :described reports on the files defining the classes the run described, which is the scope a focused run usually wants. A callable returning a String or an Array of Strings is resolved after the run rather than at start, which is what any scope derived from the run needs: start runs before any example is defined.

    This narrows only the uncovered listing. Coverage is still measured, enforced, and formatted for the whole project, so the percentage and the HTML report mean the same thing whether or not this is set.

    A scoped report names how many of the result's files it covered, and says so explicitly when they are fully covered or when nothing matched.

    Read from the LIST_UNCOVERED_FILES environment variable if set: a comma-separated list of patterns, described, or all (or false, no, off, 0, or empty) for every file.

  • start_config_block (Proc) —

    a configuration block to pass to SimpleCov.start (default: nil)

  • rspec_dry_run (Boolean) (defaults to: ::RSpec.configuration.dry_run?) —

    whether the rspec run is a dry run

    Typically not set by the user. If RSpec is being run in dry run mode, test coverage under the threshold will not fail the build. This allows test coverage to be run in a dry run by an IDE so it can report failed tests and coverage without reporting that the entire RSpec run has failed.

  • simplecov_module (Module) —

    the SimpleCov module (default: ::SimpleCov)

    Typically not set by the user. Used for this gem's unit testing.

  • env (Hash) (defaults to: ENV) —

    the environment variables (default: ENV)

    Typically not set by the user. Used for this gem's unit testing.

Returns:

  • (Void) 


174
 
# File 'lib/simplecov-rspec.rb', line 174

def self.start(...) = new(...).send(:start)