Module: SimpleCov::Configuration

Included in:
SimpleCov
Defined in:
lib/simplecov/configuration.rb,
lib/simplecov/configuration/groups.rb,
lib/simplecov/configuration/filters.rb,
lib/simplecov/configuration/merging.rb,
lib/simplecov/configuration/coverage.rb,
lib/simplecov/configuration/formatting.rb,
lib/simplecov/configuration/thresholds.rb,
lib/simplecov/configuration/eval_coverage.rb,
lib/simplecov/configuration/ignored_entries.rb,
lib/simplecov/configuration/coverage_criteria.rb,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs

Overview

Selection and validation of the coverage criteria Ruby's Coverage library should track. Supports :line (the historical default), :branch, :method, and :oneshot_line. The standalone :eval toggle lives in eval_coverage.rb.

Defined Under Namespace

Classes: CoverageCriterion

Constant Summary collapse

COVERAGE_THRESHOLD_OPTIONS =

Members are minimum, maximum, exact, maximum_drop, and minimum_per_file (%i literals infer as Array).

Returns:

  • (Array[Symbol]) 
%i[minimum maximum exact maximum_drop minimum_per_file].freeze
IGNORABLE_BRANCH_TYPES =

Branch types accepted by ignore_branches: implicit_else and eval_generated (%i literals infer as Array).

Returns:

  • (Array[Symbol]) 
%i[implicit_else eval_generated].freeze
IGNORABLE_METHOD_TYPES =

Method types accepted by ignore_methods: eval_generated (%i literals infer as Array).

Returns:

  • (Array[Symbol]) 
%i[eval_generated].freeze
SUPPORTED_COVERAGE_CRITERIA =

Members are line, branch, method, and oneshot_line (%i literals infer as Array).

Returns:

  • (Array[Symbol]) 
%i[line branch method oneshot_line].freeze
DEFAULT_COVERAGE_CRITERION =

Returns:

  • (:line) 
:line
ONESHOT_LINE_COVERAGE_CRITERION =

Returns:

  • (:oneshot_line) 
:oneshot_line
LINE_COVERAGE_ALTERNATIVES =

Signature:

  • line_coverage_alternatives

Returns:

  • (line_coverage_alternatives) 
{line: :oneshot_line, oneshot_line: :line}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#filters ⇒ Array[Filter[untyped]]

The configured exclusion filters added via skip (or the deprecated add_filter).

Returns:



86
87
88
 
# File 'lib/simplecov/configuration/filters.rb', line 86

def filters
  @filters ||= []
end

#formatter(formatter = :__no_arg__) ⇒ Class?

Gets or sets the configured formatter. Pass false (or nil) to opt out of formatting entirely (see #964).

Parameters:

  • formatter (?(Class | false | :__no_arg__), nil) (defaults to: :__no_arg__)

Returns:

  • (Class, nil) 


24
25
26
27
28
29
30
31
 
# File 'lib/simplecov/configuration/formatting.rb', line 24

def formatter(formatter = :__no_arg__)
  case formatter
  when :__no_arg__
    @formatter
  else
    @formatter = formatter || nil # normalize `false` to `nil`
  end
end

#groups ⇒ Hash[String, Filter[untyped]]

The configured groups. Add groups using group.

Returns:

  • (Hash[String, Filter[untyped]]) 


8
9
10
 
# File 'lib/simplecov/configuration/groups.rb', line 8

def groups
  @groups ||= {}
end

#print_error_status ⇒ Boolean

DEPRECATED: use print_errors instead (same value).

Returns:

  • (Boolean) 


110
111
112
113
114
 
# File 'lib/simplecov/configuration/formatting.rb', line 110

def print_error_status
  SimpleCov::Deprecation.warn("`SimpleCov.print_error_status` is deprecated. " \
                              "Replace with `SimpleCov.print_errors` (same value).")
  defined?(@print_error_status) ? @print_error_status : true
end

Instance Method Details

#active_session? ⇒ boolish

Whether SimpleCov has anything to do at exit: coverage is being tracked, or a result has already been assembled (e.g. by collate).

Returns:

  • (boolish) 


114
115
116
 
# File 'lib/simplecov/configuration.rb', line 114

def active_session?
  SimpleCov.result? || (defined?(Coverage) && Coverage.running?)
end

#add_coverage_criterion(criterion) ⇒ void

This method returns an undefined value.

Parameters:

  • criterion (criterion, :oneshot_line) 


110
111
112
113
114
115
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 110

def add_coverage_criterion(criterion)
  raise_if_criterion_unsupported(criterion)
  incompatible = LINE_COVERAGE_ALTERNATIVES[criterion]
  disable_coverage(incompatible) if incompatible
  coverage_criteria << criterion
end

#add_filter(filter_argument = nil, &block) ⇒ void

This method returns an undefined value.

DEPRECATED: use skip instead (same arguments, same behavior).

Parameters:

  • filter_argument (filter_arg, nil) (defaults to: nil) 


101
102
103
104
105
106
 
# File 'lib/simplecov/configuration/filters.rb', line 101

def add_filter(filter_argument = nil, &block)
  example = block ? "`SimpleCov.skip { ... }`" : "`SimpleCov.skip #{filter_argument.inspect}`"
  SimpleCov::Deprecation.warn("`SimpleCov.add_filter` is deprecated. " \
                              "Replace with `SimpleCov.skip` (same arguments, same behavior). Example: #{example}.")
  skip(filter_argument, &block)
end

#add_group(group_name, filter_argument = nil, &block) ⇒ void

This method returns an undefined value.

DEPRECATED: use group instead (same arguments, same behavior).

Parameters:

  • group_name (String)
  • filter_argument (filter_arg, nil) (defaults to: nil) 


29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/simplecov/configuration/groups.rb', line 29

def add_group(group_name, filter_argument = nil, &block)
  example = if block
              "`SimpleCov.group #{group_name.inspect} { ... }`"
            else
              "`SimpleCov.group #{group_name.inspect}, #{filter_argument.inspect}`"
            end
  SimpleCov::Deprecation.warn(
    "`SimpleCov.add_group` is deprecated. " \
    "Replace with `SimpleCov.group` (same arguments, same behavior). Example: #{example}."
  )
  group(group_name, filter_argument, &block)
end

#apply_threshold_options(configurator, options) ⇒ void

This method returns an undefined value.

Forward the one-liner threshold keywords (coverage :branch, minimum: 80) to the matching CoverageCriterion verbs, rejecting anything that isn't a recognized threshold option.

Parameters:



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/simplecov/configuration/coverage.rb', line 61

def apply_threshold_options(configurator, options)
  options.each do |verb, value|
    unless COVERAGE_THRESHOLD_OPTIONS.include?(verb)
      raise SimpleCov::ConfigurationError,
            "Unknown `coverage` option #{verb.inspect}. " \
            "Supported options are #{COVERAGE_THRESHOLD_OPTIONS.inspect}."
    end

    configurator.public_send(verb, value)
  end
end

#at_exit(&block) ⇒ void

This method returns an undefined value.

Gets or sets the behavior that processes coverage results at process exit. The default stores/merges the current result and formats only from the final reporting process.



99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/simplecov/configuration.rb', line 99

def at_exit(&block)
  @at_exit = block if block
  configured = @at_exit
  return configured if configured
  return proc {} unless active_session?

  @at_exit = proc do
    result = SimpleCov.result
    result.format! if result && SimpleCov.merge_finalization_owner?
  end
end

#at_fork(&block) ⇒ void

This method returns an undefined value.

Gets or sets the behavior run in a newly forked process. The block receives the child pid. The default renames the command from the fork serial, silences errors, and restarts SimpleCov.



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/simplecov/configuration.rb', line 123

def at_fork(&block)
  @at_fork = block if block
  @at_fork ||= lambda { |_pid|
    # Needs a name that's unique per worker within a run yet identical
    # across runs. Build it from SimpleCov's stable fork serial rather
    # than the OS pid: with the pid, every run produced uniquely-named
    # results that never overwrote the previous run's, so they piled up
    # in .resultset.json until merge_timeout and the merged report's
    # file set drifted from run to run. See issue #1171.
    SimpleCov.command_name "#{SimpleCov.command_name} (subprocess: #{SimpleCov.subprocess_serial})"
    # be quiet, the parent process will use the regular formatter
    SimpleCov.print_errors false
    SimpleCov.formatter SimpleCov::Formatter::SimpleFormatter
    SimpleCov.minimum_coverage 0
    SimpleCov.start
  }
end

#branch_coverage? ⇒ Boolean

Returns:

  • (Boolean) 


76
77
78
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 76

def branch_coverage?
  branch_coverage_supported? && coverage_criterion_enabled?(:branch)
end

#branch_coverage_supported? ⇒ Boolean

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 80

def branch_coverage_supported?
  coverage_criterion_supported?(:branches)
end

#build_cover_filter(arg) ⇒ Filter[untyped]

Build a filter for a cover argument. Strings are treated as globs (not substrings — that's skip/add_filter's semantics); everything else dispatches exactly like add_filter.

Parameters:

  • arg (cover_arg)

Returns:



144
145
146
147
148
149
150
 
# File 'lib/simplecov/configuration/filters.rb', line 144

def build_cover_filter(arg)
  SimpleCov::Filter.build_filter(arg, string_filter: SimpleCov::GlobFilter)
rescue SimpleCov::ConfigurationError
  raise SimpleCov::ConfigurationError, "Unsupported `cover` argument #{arg.inspect}; " \
                                       "expected a String glob, Regexp, Proc, " \
                                       "SimpleCov::Filter, or Array of those."
end

#clear_coverage_criteria ⇒ void

This method returns an undefined value.

Reset the criteria back to the lazy default (Set[:line]).



52
53
54
55
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 52

def clear_coverage_criteria
  @coverage_criteria = nil
  @primary_coverage = nil
end

#clear_filters ⇒ Array[Filter[untyped]]

Remove every filter from the chain, including the defaults installed by SimpleCov.start.

Returns:



118
119
120
 
# File 'lib/simplecov/configuration/filters.rb', line 118

def clear_filters
  @filters = []
end

#collating_result? ⇒ boolish

Host contract: defined on SimpleCov itself (result_processing.rb). This module is only ever extended onto SimpleCov, where both methods are available to merge_finalization_owner?.

Returns:

  • (boolish) 


696
 
# File 'sig/simplecov.rbs', line 696

def collating_result?: () -> boolish

#collect_cover_globs(filter_list) ⇒ Array[String]

Walk a list of cover filters and return the string globs they hold, descending into ArrayFilter wrappers built by cover(["a", "b"]).

Parameters:

  • filter_list (Array[Filter[untyped]])

Returns:

  • (Array[String]) 


154
155
156
157
158
159
160
161
162
 
# File 'lib/simplecov/configuration/filters.rb', line 154

def collect_cover_globs(filter_list)
  filter_list.flat_map do |filter|
    case filter
    when SimpleCov::GlobFilter  then filter.filter_argument
    when SimpleCov::ArrayFilter then collect_cover_globs(filter.filter_argument)
    else []
    end
  end
end

#color(value = :__no_arg__) ⇒ bool, :auto

Whether stderr diagnostics are colorized: true, false, or :auto (default — respects TTY, NO_COLOR, and FORCE_COLOR).

Parameters:

  • value (?(bool | :auto | :__no_arg__)) (defaults to: :__no_arg__)

Returns:

  • (bool, :auto) 


68
69
70
71
72
 
# File 'lib/simplecov/configuration/formatting.rb', line 68

def color(value = :__no_arg__)
  return defined?(@color) ? @color : :auto if value == :__no_arg__

  @color = value
end

#command_name(name = nil) ⇒ String

The name of the command (a.k.a. test suite) currently running. Auto-detected when not set explicitly.

Parameters:

  • name (String, nil) (defaults to: nil)

Returns:

  • (String) 


68
69
70
71
 
# File 'lib/simplecov/configuration.rb', line 68

def command_name(name = nil)
  @command_name = name unless name.nil?
  @command_name ||= SimpleCov::CommandGuesser.guess
end

#configure ⇒ self #configure ⇒ self

Configure SimpleCov in a block. A zero-argument block runs with the configuration target as self; a parameterized block keeps its lexical self and receives the target explicitly:

SimpleCov.configure { skip "test" }
SimpleCov.configure { |config| config.skip caller_filter }

Overloads:

  • #configure ⇒ self

    Returns:

    • (self)
  • #configure ⇒ self

    Returns:

    • (self)

Yields:

Yield Parameters:

  • config (self)

Yield Returns:

  • (void) 


83
84
85
86
87
88
89
90
91
92
 
# File 'lib/simplecov/configuration.rb', line 83

def configure(&block)
  raise ArgumentError, "configuration block required" unless block

  if block.parameters.empty?
    instance_exec(&(_ = block))
  else
    yield self
  end
  self
end

#cover(*args, &block) ⇒ void

This method returns an undefined value.

Restrict the report to files matching one or more shell globs, regexps, or block predicates. Multiple calls union. String globs are also expanded on disk so unloaded files appear at 0% coverage.

Parameters:

  • args (cover_arg) 


32
33
34
35
36
 
# File 'lib/simplecov/configuration/filters.rb', line 32

def cover(*args, &block)
  args.each { |arg| cover_filters << build_cover_filter(arg) }
  cover_filters << SimpleCov::BlockFilter.new(block) if block
  cover_filters
end

#cover_filters ⇒ Array[Filter[untyped]]

The configured inclusion filters added via cover.

Returns:



39
40
41
 
# File 'lib/simplecov/configuration/filters.rb', line 39

def cover_filters
  @cover_filters ||= []
end

#cover_globs ⇒ Array[String]

The string globs passed to cover, driving unloaded-file discovery.

Returns:

  • (Array[String]) 


51
52
53
 
# File 'lib/simplecov/configuration/filters.rb', line 51

def cover_globs
  collect_cover_globs(cover_filters)
end

#coverage(criterion, primary: false, enabled: true, oneshot: false, **thresholds, &block) ⇒ void

This method returns an undefined value.

Configure (and, unless enabled: false, enable) a coverage criterion. primary: true makes it the report's leading criterion; oneshot: true (only for :line) selects oneshot-lines mode. Threshold keywords mirror the block verbs for one-liner use. Returns the criterion symbol the thresholds were stored under. The threshold keywords (minimum:, maximum:, exact:, maximum_drop:, minimum_per_file:) arrive via **thresholds in the implementation, so they are typed as a Numeric kwarg splat. The block runs under instance_eval, which also yields the receiver as an optional argument.

Parameters:

  • criterion (criterion, :eval)
  • primary: (Boolean) (defaults to: false)
  • enabled: (Boolean) (defaults to: true)
  • oneshot: (Boolean) (defaults to: false)
  • thresholds (Numeric) 


43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/simplecov/configuration/coverage.rb', line 43

def coverage(criterion, primary: false, enabled: true, oneshot: false, **thresholds, &block)
  criterion = enable_coverage_criterion(criterion, enabled: enabled, oneshot: oneshot)
  # The cast admits :eval, which primary_coverage rejects at runtime
  # (it is a standalone toggle, never in the enabled-criteria set).
  primary_coverage(_ = criterion) if primary

  configurator = CoverageCriterion.new(self, criterion)
  apply_threshold_options(configurator, thresholds)
  configurator.instance_eval(&block) if block

  criterion
end

#coverage_criteria ⇒ Set[criterion | :oneshot_line]

The currently enabled criteria. Defaults to Set[:line].

Returns:

  • (Set[criterion | :oneshot_line]) 


291
292
293
 
# File 'sig/simplecov.rbs', line 291

def coverage_criteria
  @coverage_criteria ||= Set[DEFAULT_COVERAGE_CRITERION]
end

#coverage_criterion_enabled?(criterion) ⇒ Boolean

Any Symbol is accepted: asking whether an unknown criterion is enabled is a legitimate question (the answer is false), and the private validators rely on it.

Parameters:

  • criterion (Symbol)

Returns:

  • (Boolean) 


296
297
298
 
# File 'sig/simplecov.rbs', line 296

def coverage_criterion_enabled?(criterion)
  coverage_criteria.member?(criterion)
end

#coverage_criterion_supported?(criterion) ⇒ Boolean

Whether the running Ruby's Coverage library supports the given criterion, named in Coverage's own plural vocabulary (:lines, :branches, :methods, :oneshot_lines, :eval).

Parameters:

  • criterion (Symbol)

Returns:

  • (Boolean) 


100
101
102
103
104
105
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 100

def coverage_criterion_supported?(criterion)
  require "coverage"
  return Coverage.supported?(criterion) if Coverage.respond_to?(:supported?)

  criterion != :eval && RUBY_ENGINE != "jruby"
end

#coverage_dir(dir = nil) ⇒ String

The name of the output and cache directory. Defaults to "coverage".

Parameters:

  • dir (String, nil) (defaults to: nil)

Returns:

  • (String) 


30
31
32
33
34
35
36
 
# File 'lib/simplecov/configuration.rb', line 30

def coverage_dir(dir = nil)
  return @coverage_dir if defined?(@coverage_dir) && dir.nil?

  @coverage_path = nil unless @coverage_path_explicit # invalidate cache
  @coverage_dir_explicit = true unless dir.nil?
  @coverage_dir = dir || "coverage"
end

#coverage_for_eval_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


13
14
15
 
# File 'lib/simplecov/configuration/eval_coverage.rb', line 13

def coverage_for_eval_enabled?
  @coverage_for_eval_enabled ||= false
end

#coverage_for_eval_supported? ⇒ Boolean

Returns:

  • (Boolean) 


9
10
11
 
# File 'lib/simplecov/configuration/eval_coverage.rb', line 9

def coverage_for_eval_supported?
  coverage_criterion_supported?(:eval)
end

#coverage_path(path = nil) ⇒ String

The full path to the output directory. By default root + coverage_dir; assign an absolute path to pin the destination regardless of later root / coverage_dir changes (see #716).

Parameters:

  • path (String, nil) (defaults to: nil)

Returns:

  • (String) 


52
53
54
55
56
57
58
59
60
61
 
# File 'lib/simplecov/configuration.rb', line 52

def coverage_path(path = nil)
  if path
    expanded = File.expand_path(path)
    @coverage_path = expanded
    @coverage_path_explicit = true
    FileUtils.mkdir_p expanded
  end

  @coverage_path ||= File.expand_path(coverage_dir, root)
end

#current_nocov_token(value = nil) ⇒ String

Internal accessor used by SimpleCov to recognise # :nocov: markers without emitting the public-API deprecation warning. Will be removed alongside the deprecated nocov_token setter.

Parameters:

  • value (String, nil) (defaults to: nil)

Returns:

  • (String) 


132
133
134
135
136
 
# File 'lib/simplecov/configuration/formatting.rb', line 132

def current_nocov_token(value = nil)
  return @nocov_token if defined?(@nocov_token) && value.nil?

  @nocov_token = value || "nocov"
end

#default_primary_coverage ⇒ criterion, :oneshot_line

If :line is enabled, it's the default primary; otherwise fall back to whichever criterion the user actually enabled (in insertion order). Returning :line even when disabled would propagate broken state into minimum_coverage 90.

Returns:

  • (criterion, :oneshot_line) 


121
122
123
124
125
126
127
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 121

def default_primary_coverage
  return DEFAULT_COVERAGE_CRITERION if coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION)

  # Set#first types as nilable, but an empty criteria set is rejected at
  # start_tracking before any caller can observe a nil here.
  _ = coverage_criteria.first
end

#disable_coverage(criterion) ⇒ void

This method returns an undefined value.

Remove criterion from the set of enabled coverage criteria. :eval turns the standalone eval-coverage toggle back off. Disabling every criterion raises at start_tracking, not here.

Parameters:

  • criterion (criterion, :oneshot_line, :eval) 


26
27
28
29
30
31
32
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 26

def disable_coverage(criterion)
  return disable_eval_coverage if criterion == :eval

  raise_if_criterion_unsupported(criterion)
  coverage_criteria.delete(criterion)
  @primary_coverage = nil if @primary_coverage == criterion
end

#disable_eval_coverage ⇒ void

This method returns an undefined value.

No support check needed: off is a safe state on every Ruby.



37
38
39
 
# File 'lib/simplecov/configuration/eval_coverage.rb', line 37

def disable_eval_coverage
  @coverage_for_eval_enabled = false
end

#enable_coverage(*criteria) ⇒ void

This method returns an undefined value.

Enable one or more coverage criteria. :eval is accepted as a shorthand for the standalone eval-coverage toggle. :line and :oneshot_line replace each other; the last enabled mode wins.

Parameters:

  • criteria (criterion, :oneshot_line, :eval) 


17
18
19
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 17

def enable_coverage(*criteria)
  criteria.each { |criterion| criterion == :eval ? enable_eval_coverage : add_coverage_criterion(criterion) }
end

#enable_coverage_criterion(criterion, enabled:, oneshot:) ⇒ criterion, ...

Enable or disable the criterion (or its oneshot / eval variant) and return the criterion symbol that thresholds should be stored under.

Parameters:

  • criterion (criterion, :eval)
  • enabled: (Boolean)
  • oneshot: (Boolean)

Returns:

  • (criterion, :oneshot_line, :eval) 


75
76
77
78
79
 
# File 'lib/simplecov/configuration/coverage.rb', line 75

def enable_coverage_criterion(criterion, enabled:, oneshot:)
  criterion = resolve_criterion_variant(criterion, oneshot)
  enabled ? enable_coverage(criterion) : disable_coverage(criterion)
  criterion
end

#enable_coverage_for_eval ⇒ void

This method returns an undefined value.

DEPRECATED: use enable_coverage :eval instead.



18
19
20
21
22
 
# File 'lib/simplecov/configuration/eval_coverage.rb', line 18

def enable_coverage_for_eval
  SimpleCov::Deprecation.warn("`SimpleCov.enable_coverage_for_eval` is deprecated. " \
                              "Replace with `SimpleCov.enable_coverage :eval`.")
  enable_eval_coverage
end

#enable_eval_coverage ⇒ void

This method returns an undefined value.

Shared implementation backing both enable_coverage :eval and the deprecated enable_coverage_for_eval.



28
29
30
31
32
33
34
 
# File 'lib/simplecov/configuration/eval_coverage.rb', line 28

def enable_eval_coverage
  if coverage_for_eval_supported?
    @coverage_for_eval_enabled = true
  else
    warn "Coverage for eval is not available; Use Ruby 3.2.0 or later"
  end
end

#enable_for_subprocesses(value = nil) ⇒ Boolean

DEPRECATED: use merge_subprocesses instead (same value).

Parameters:

  • value (Boolean, nil) (defaults to: nil)

Returns:

  • (Boolean) 


38
39
40
41
42
 
# File 'lib/simplecov/configuration/merging.rb', line 38

def enable_for_subprocesses(value = nil)
  SimpleCov::Deprecation.warn("`SimpleCov.enable_for_subprocesses` is deprecated. " \
                              "Replace with `SimpleCov.merge_subprocesses` (same value, same behavior).")
  merge_subprocesses(value)
end

#enabled_for_subprocesses? ⇒ Boolean

whether to install the fork hook.

Returns:

  • (Boolean) 


21
22
23
 
# File 'lib/simplecov/configuration/merging.rb', line 21

def enabled_for_subprocesses?
  defined?(@enable_for_subprocesses) ? @enable_for_subprocesses : false
end

#expected_coverage(coverage = nil) ⇒ coverage_thresholds

Pin the suite to an exact figure: sets both minimum_coverage and maximum_coverage. See #187.

Parameters:

  • coverage (?(Numeric | coverage_thresholds), nil) (defaults to: nil)

Returns:

  • (coverage_thresholds) 


43
44
45
46
47
48
 
# File 'lib/simplecov/configuration/thresholds.rb', line 43

def expected_coverage(coverage = nil)
  return minimum_coverage if coverage.nil?

  minimum_coverage(coverage)
  maximum_coverage(coverage)
end

#explicit_coverage_destination? ⇒ Boolean

Returns:

  • (Boolean) 


144
145
146
147
 
# File 'lib/simplecov/configuration/merging.rb', line 144

def explicit_coverage_destination?
  (defined?(@coverage_path_explicit) && @coverage_path_explicit) ||
    (defined?(@coverage_dir_explicit) && @coverage_dir_explicit)
end

#explicit_custom_coverage_destination? ⇒ Boolean

Returns:

  • (Boolean) 


138
139
140
141
142
 
# File 'lib/simplecov/configuration/merging.rb', line 138

def explicit_custom_coverage_destination?
  return false unless explicit_coverage_destination?

  coverage_path != File.expand_path("coverage", root)
end

#final_result_process? ⇒ boolish

Returns:

  • (boolish) 


698
 
# File 'sig/simplecov.rbs', line 698

def final_result_process?: () -> boolish

#finalize_merge(value = :__no_arg__) ⇒ Boolean

Get or set whether SimpleCov's selected final process owns merge processing: waiting for sibling workers, merging, formatting, enforcing thresholds, and writing .last_run.json. Defaults to true except for recognized multi-worker parallel runs writing to a custom coverage destination (those likely finalize via an external SimpleCov.collate step). See #1215.

Parameters:

  • value (?(:__no_arg__ | bool)) (defaults to: :__no_arg__)

Returns:

  • (Boolean) 


65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/simplecov/configuration/merging.rb', line 65

def finalize_merge(value = :__no_arg__)
  unless value == :__no_arg__
    @finalize_merge = value
    @finalize_merge_explicit = true
  end

  return @finalize_merge if defined?(@finalize_merge_explicit) && @finalize_merge_explicit

  inferred = inferred_finalize_merge?
  warn_about_inferred_finalize_merge unless inferred
  inferred
end

#finalize_merge? ⇒ Boolean

Returns:

  • (Boolean) 


78
79
80
 
# File 'lib/simplecov/configuration/merging.rb', line 78

def finalize_merge?
  finalize_merge
end

#formatters(formatters = :__no_arg__) ⇒ Array[Class], ...

Gets the formatter chain, or sets it. Accepts an Array, a single formatter, or nil / [] to opt out of formatting entirely. Returns the passed value when setting.

Parameters:

  • formatters (?(Array[Class] | Class | :__no_arg__), nil) (defaults to: :__no_arg__)

Returns:

  • (Array[Class], Class, nil) 


35
36
37
38
39
40
41
42
43
44
 
# File 'lib/simplecov/configuration/formatting.rb', line 35

def formatters(formatters = :__no_arg__)
  case formatters
  when :__no_arg__
    configured = formatter
    configured ? [configured] : []
  else
    self.formatters = formatters
    formatters
  end
end

#formatters=(formatters) ⇒ void

This method returns an undefined value.

Sets the configured formatters (single formatters are wrapped; nil / [] opts out of formatting entirely).

Parameters:

  • formatters (Array[Class], Class, nil) 


53
54
55
56
 
# File 'lib/simplecov/configuration/formatting.rb', line 53

def formatters=(formatters)
  formatters = Array(formatters || nil)
  @formatter = formatters.empty? ? nil : SimpleCov::Formatter::MultiFormatter.new(formatters)
end

#group(group_name, filter_argument = nil) ⇒ void

This method returns an undefined value.

Define a display group for files. Same matcher grammar as skip, but bins matches under group_name instead of dropping them.

Parameters:

  • group_name (String)
  • filter_argument (filter_arg, nil) (defaults to: nil) 


22
23
24
25
26
 
# File 'lib/simplecov/configuration/groups.rb', line 22

def group(group_name, filter_argument = nil, &)
  group_name = GroupNames.normalize(group_name)
  GroupNames.validate!([group_name])
  groups[group_name] = parse_filter(filter_argument, &)
end

#ignore_branches(*types) ⇒ Array[Symbol]

Opt out of synthetic branch entries. Variadic; multiple calls union. Recorded even when branch coverage is not (yet) enabled.

Parameters:

  • types (:implicit_else, :eval_generated)

Returns:

  • (Array[Symbol]) 


15
16
17
18
19
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 15

def ignore_branches(*types)
  types.each { |type| raise_if_branch_type_unsupported(type) }
  ignored_branches.concat(types).uniq!
  ignored_branches
end

#ignore_methods(*types) ⇒ Array[Symbol]

Opt out of synthetic method entries (currently :eval_generated only).

Parameters:

  • types (:eval_generated)

Returns:

  • (Array[Symbol]) 


31
32
33
34
35
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 31

def ignore_methods(*types)
  types.each { |type| raise_if_method_type_unsupported(type) }
  ignored_methods.concat(types).uniq!
  ignored_methods
end

#ignored_branch?(type) ⇒ Boolean

Parameters:

  • type (Symbol)

Returns:

  • (Boolean) 


25
26
27
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 25

def ignored_branch?(type)
  ignored_branches.include?(type)
end

#ignored_branches ⇒ Array[Symbol]

Returns:

  • (Array[Symbol]) 


21
22
23
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 21

def ignored_branches
  @ignored_branches ||= []
end

#ignored_method?(type) ⇒ Boolean

Parameters:

  • type (Symbol)

Returns:

  • (Boolean) 


41
42
43
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 41

def ignored_method?(type)
  ignored_methods.include?(type)
end

#ignored_methods ⇒ Array[Symbol]

Returns:

  • (Array[Symbol]) 


37
38
39
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 37

def ignored_methods
  @ignored_methods ||= []
end

#inferred_finalize_merge? ⇒ Boolean

Returns:

  • (Boolean) 


122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/simplecov/configuration/merging.rb', line 122

def inferred_finalize_merge?
  return true unless merging

  adapter = SimpleCov::ParallelAdapters.current
  return true unless adapter
  return true unless adapter.expected_worker_count > 1
  return true unless parallel_worker_environment?
  return true unless explicit_custom_coverage_destination?

  false
end

#inferred_finalize_merge_warning ⇒ String

Returns:

  • (String) 


157
158
159
160
161
162
163
 
# File 'lib/simplecov/configuration/merging.rb', line 157

def inferred_finalize_merge_warning
  "SimpleCov inferred `finalize_merge false` because this parallel worker is merging " \
    "into a custom coverage destination. Set `SimpleCov.finalize_merge false` to keep " \
    "external collation ownership, or `SimpleCov.finalize_merge true` if this worker " \
    "should wait, merge, format, enforce thresholds, and write `.last_run.json`. " \
    "See https://github.com/simplecov-ruby/simplecov#merge-finalization-ownership."
end

#line_coverage? ⇒ Boolean

Whether this run produces line data at all. The oneshot variant counts: ResultAdapter turns its executed-line list back into a line array. A branch-only or method-only run produces none, and Coverage.result entries for the files it loaded carry no "lines" key.

Returns:

  • (Boolean) 


71
72
73
74
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 71

def line_coverage?
  coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION) ||
    coverage_criterion_enabled?(ONESHOT_LINE_COVERAGE_CRITERION)
end

#maximum_coverage(coverage = nil) ⇒ coverage_thresholds

The maximum overall coverage allowed — an unexpected jump above it fails the build. Pair with minimum_coverage (or use expected_coverage) to pin coverage. See #187.

Parameters:

  • coverage (?(Numeric | coverage_thresholds), nil) (defaults to: nil)

Returns:

  • (coverage_thresholds) 


33
34
35
36
37
 
# File 'lib/simplecov/configuration/thresholds.rb', line 33

def maximum_coverage(coverage = nil)
  return @maximum_coverage ||= {} unless coverage

  @maximum_coverage = normalized_threshold(coverage, "maximum_coverage")
end

#maximum_coverage_drop(coverage_drop = nil) ⇒ coverage_thresholds

The maximum coverage drop between runs allowed for the suite to pass. Default: none (100%, disabled).

Parameters:

  • coverage_drop (?(Numeric | coverage_thresholds), nil) (defaults to: nil)

Returns:

  • (coverage_thresholds) 


54
55
56
57
58
 
# File 'lib/simplecov/configuration/thresholds.rb', line 54

def maximum_coverage_drop(coverage_drop = nil)
  return @maximum_coverage_drop ||= {} unless coverage_drop

  @maximum_coverage_drop = normalized_threshold(coverage_drop, "maximum_coverage_drop")
end

#merge_finalization_owner? ⇒ Boolean

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.

Returns:

  • (Boolean) 


83
84
85
 
# File 'lib/simplecov/configuration/merging.rb', line 83

def merge_finalization_owner?
  collating_result? || (finalize_merge? && final_result_process?)
end

#merge_subprocesses(value = nil) ⇒ Boolean

Get or set whether SimpleCov hooks Process._fork to attach itself to subprocesses (e.g. Rails' parallelize(workers:)). Defaults to false.

Parameters:

  • value (Boolean, nil) (defaults to: nil)

Returns:

  • (Boolean) 


13
14
15
16
17
 
# File 'lib/simplecov/configuration/merging.rb', line 13

def merge_subprocesses(value = nil)
  return @enable_for_subprocesses if defined?(@enable_for_subprocesses) && value.nil?

  @enable_for_subprocesses = value || false
end

#merge_timeout(seconds = nil) ⇒ Integer

The maximum age (in seconds) of a resultset to still be included in merged results. Defaults to 600.

Parameters:

  • seconds (Integer, nil) (defaults to: nil)

Returns:

  • (Integer) 


102
103
104
105
 
# File 'lib/simplecov/configuration/merging.rb', line 102

def merge_timeout(seconds = nil)
  @merge_timeout = seconds if seconds.is_a?(Integer)
  @merge_timeout ||= 600
end

#merging(use = nil) ⇒ Boolean

Get or set whether to merge results from multiple test suites into a single coverage report. Defaults to true.

Parameters:

  • use (Boolean, nil) (defaults to: nil)

Returns:

  • (Boolean) 


49
50
51
52
53
 
# File 'lib/simplecov/configuration/merging.rb', line 49

def merging(use = nil)
  @use_merging = use unless use.nil?
  @use_merging = true unless defined?(@use_merging) && @use_merging == false
  @use_merging
end

#method_coverage? ⇒ Boolean

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 84

def method_coverage?
  method_coverage_supported? && coverage_criterion_enabled?(:method)
end

#method_coverage_supported? ⇒ Boolean

Returns:

  • (Boolean) 


88
89
90
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 88

def method_coverage_supported?
  coverage_criterion_supported?(:methods)
end

#minimum_coverage(coverage = nil) ⇒ coverage_thresholds

The minimum overall coverage required for the suite to pass. Default: none (0%, disabled).

Parameters:

  • coverage (?(Numeric | coverage_thresholds), nil) (defaults to: nil)

Returns:

  • (coverage_thresholds) 


14
15
16
17
18
 
# File 'lib/simplecov/configuration/thresholds.rb', line 14

def minimum_coverage(coverage = nil)
  return @minimum_coverage ||= {} unless coverage

  @minimum_coverage = normalized_threshold(coverage, "minimum_coverage")
end

#minimum_coverage_by_file ⇒ coverage_thresholds #minimum_coverage_by_file(coverage) ⇒ Hash[String | Regexp, coverage_thresholds]

DEPRECATED: use coverage(criterion) { minimum_per_file ... }. Symbol keys declare per-criterion defaults; String / Regexp keys declare per-path overrides.

Overloads:

  • #minimum_coverage_by_file ⇒ coverage_thresholds

    Returns:

    • (coverage_thresholds)
  • #minimum_coverage_by_file(coverage) ⇒ Hash[String | Regexp, coverage_thresholds]

    Parameters:

    • coverage (Numeric, Hash[Symbol | String | Regexp, Numeric | coverage_thresholds])

    Returns:

    • (Hash[String | Regexp, coverage_thresholds]) 


67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/simplecov/configuration/thresholds.rb', line 67

def minimum_coverage_by_file(coverage = nil)
  return @minimum_coverage_by_file ||= {} unless coverage

  coverage = {primary_coverage => coverage} if coverage.is_a?(Numeric)
  defaults, overrides = partition_per_file_thresholds(coverage)

  SimpleCov::Deprecation.warn("`SimpleCov.minimum_coverage_by_file` is deprecated. " \
                              "Replace it with:\n#{per_file_coverage_replacement(defaults, overrides)}")

  raise_on_invalid_coverage(defaults, "minimum_coverage_by_file")
  overrides.each_value { |criteria| raise_on_invalid_coverage(criteria, "minimum_coverage_by_file") }

  @minimum_coverage_by_file = defaults
  @minimum_coverage_by_file_overrides = overrides
end

#minimum_coverage_by_file_overrides ⇒ Hash[String | Regexp, coverage_thresholds]

The per-path overrides set via minimum_coverage_by_file (or coverage(criterion) { minimum_per_file N, only: ... }).

Returns:

  • (Hash[String | Regexp, coverage_thresholds]) 


84
85
86
 
# File 'lib/simplecov/configuration/thresholds.rb', line 84

def minimum_coverage_by_file_overrides
  @minimum_coverage_by_file_overrides ||= {}
end

#minimum_coverage_by_group ⇒ Hash[String, coverage_thresholds] #minimum_coverage_by_group(coverage) ⇒ Hash[String, coverage_thresholds]

DEPRECATED: use coverage(criterion) { minimum_per_group ... }.

Overloads:

  • #minimum_coverage_by_group ⇒ Hash[String, coverage_thresholds]

    Returns:

    • (Hash[String, coverage_thresholds])
  • #minimum_coverage_by_group(coverage) ⇒ Hash[String, coverage_thresholds]

    Parameters:

    • coverage (Hash[String, Numeric | coverage_thresholds])

    Returns:

    • (Hash[String, coverage_thresholds]) 


92
93
94
95
96
97
98
99
100
 
# File 'lib/simplecov/configuration/thresholds.rb', line 92

def minimum_coverage_by_group(coverage = nil)
  return @minimum_coverage_by_group ||= {} unless coverage

  SimpleCov::Deprecation.warn("`SimpleCov.minimum_coverage_by_group` is deprecated. " \
                              "Replace it with:\n#{per_group_coverage_replacement(coverage)}")
  @minimum_coverage_by_group = coverage.to_h do |group_name, group_coverage|
    [GroupNames.normalize(group_name), normalized_threshold(group_coverage, "minimum_coverage_by_group")]
  end
end

#minimum_possible_coverage_exceeded(coverage_option) ⇒ void

This method returns an undefined value.

Parameters:

  • coverage_option (String) 


143
144
145
 
# File 'lib/simplecov/configuration/thresholds.rb', line 143

def minimum_possible_coverage_exceeded(coverage_option)
  warn "The coverage you set for #{coverage_option} is greater than 100%"
end

#no_default_skips ⇒ Array[Filter[untyped]]

Drop every previously installed filter (defaults included) so subsequent skip calls start from a clean slate.

Returns:



126
127
128
 
# File 'lib/simplecov/configuration/filters.rb', line 126

def no_default_skips
  clear_filters
end

#nocov_token(nocov_token = nil) ⇒ String Also known as: skip_token

DEPRECATED: use # simplecov:disable / # simplecov:enable directive comments instead of # :nocov: toggles.

Parameters:

  • nocov_token (String, nil) (defaults to: nil)

Returns:

  • (String) 


122
123
124
125
126
 
# File 'lib/simplecov/configuration/formatting.rb', line 122

def nocov_token(nocov_token = nil)
  SimpleCov::Deprecation.warn("`SimpleCov.nocov_token` and `SimpleCov.skip_token` are deprecated. " \
                              "Replace with `# simplecov:disable` / `# simplecov:enable` block comments.")
  current_nocov_token(nocov_token)
end

#normalized_threshold(coverage, setting) ⇒ coverage_thresholds

Shared normalize-and-validate step behind every threshold setter.

Parameters:

  • coverage (Numeric, coverage_thresholds)
  • setting (String)

Returns:

  • (coverage_thresholds) 


115
116
117
118
119
 
# File 'lib/simplecov/configuration/thresholds.rb', line 115

def normalized_threshold(coverage, setting)
  coverage = {primary_coverage => coverage} if coverage.is_a?(Numeric)
  raise_on_invalid_coverage(coverage, setting)
  coverage
end

#parallel_tests(value = :__no_arg__) ⇒ Boolean?

Get or set whether SimpleCov auto-requires the parallel_tests gem when it sees its environment variables. nil (the default) means auto-detect. See #1018.

Parameters:

  • value (?(:__no_arg__ | bool), nil) (defaults to: :__no_arg__)

Returns:

  • (Boolean, nil) 


31
32
33
34
35
 
# File 'lib/simplecov/configuration/merging.rb', line 31

def parallel_tests(value = :__no_arg__)
  return defined?(@parallel_tests) ? @parallel_tests : nil if value == :__no_arg__

  @parallel_tests = value
end

#parallel_wait_timeout(seconds = nil) ⇒ Integer

How long (in seconds) the reporting process waits for remaining parallel-test workers to write their resultsets before it proceeds with a partial merge. Defaults to 60. See #1171.

Parameters:

  • seconds (Integer, nil) (defaults to: nil)

Returns:

  • (Integer) 


115
116
117
118
 
# File 'lib/simplecov/configuration/merging.rb', line 115

def parallel_wait_timeout(seconds = nil)
  @parallel_wait_timeout = seconds if seconds.is_a?(Integer)
  @parallel_wait_timeout ||= 60
end

#parallel_worker_environment? ⇒ Boolean

Returns:

  • (Boolean) 


134
135
136
 
# File 'lib/simplecov/configuration/merging.rb', line 134

def parallel_worker_environment?
  ENV.key?("TEST_ENV_NUMBER") || ENV.key?("PARALLEL_TEST_GROUPS")
end

#parse_filter(filter_argument = nil, &filter_proc) ⇒ void

This method returns an undefined value.

The actual filter processor. Not meant for direct use.

Parameters:

  • filter_argument (filter_arg, nil) (defaults to: nil)

Raises:

  • (ArgumentError) 


133
134
135
136
137
138
139
 
# File 'lib/simplecov/configuration/filters.rb', line 133

def parse_filter(filter_argument = nil, &filter_proc)
  filter = filter_argument || filter_proc

  raise ArgumentError, "Please specify either a filter or a block to filter with" unless filter

  SimpleCov::Filter.build_filter(filter)
end

#partition_per_file_thresholds(coverage) ⇒ [coverage_thresholds, Hash[String | Regexp, coverage_thresholds]]

Split a minimum_coverage_by_file argument into Symbol-keyed criterion defaults and String/Regexp-keyed per-path overrides; normalize Numeric override values to {primary_coverage => N} so downstream code only has one shape to handle.

Parameters:

  • coverage (Hash[Symbol | String | Regexp, Numeric | coverage_thresholds])

Returns:

  • ([coverage_thresholds, Hash[String | Regexp, coverage_thresholds]]) 


125
126
127
128
129
130
131
132
133
134
 
# File 'lib/simplecov/configuration/thresholds.rb', line 125

def partition_per_file_thresholds(coverage)
  coverage.each_key { |key| validate_per_file_key(key) }
  pairs = coverage.partition { |key, _| key.is_a?(Symbol) }
  # The assertions restate what the partition predicate guarantees:
  # Symbol keys carry per-criterion Numeric defaults, the rest are paths.
  defaults = pairs[0].to_h #: coverage_thresholds
  raw = pairs[1].to_h #: Hash[String | Regexp, Numeric | coverage_thresholds]
  overrides = raw.transform_values { |value| value.is_a?(Numeric) ? {primary_coverage => value} : value }
  [defaults, overrides]
end

#per_file_coverage_replacement(defaults, overrides) ⇒ String

Render the coverage configuration equivalent to a (deprecated) minimum_coverage_by_file argument so the deprecation warning can be copy-pasted verbatim into the user's config.

Parameters:

  • defaults (coverage_thresholds)
  • overrides (Hash[String | Regexp, coverage_thresholds])

Returns:

  • (String) 


150
151
152
153
154
155
156
157
158
159
 
# File 'lib/simplecov/configuration/thresholds.rb', line 150

def per_file_coverage_replacement(defaults, overrides)
  by_criterion = {} #: Hash[Symbol, Array[String]]
  defaults.each { |criterion, percent| (by_criterion[criterion] ||= []) << "minimum_per_file #{percent}" }
  overrides.each do |target, criteria|
    criteria.each do |criterion, percent|
      (by_criterion[criterion] ||= []) << "minimum_per_file #{percent}, only: #{target.inspect}"
    end
  end
  render_coverage_blocks(by_criterion)
end

#per_group_coverage_replacement(coverage) ⇒ String

Same, for a (deprecated) minimum_coverage_by_group argument.

Parameters:

  • coverage (Hash[String, Numeric | coverage_thresholds])

Returns:

  • (String) 


162
163
164
165
166
167
168
169
170
171
 
# File 'lib/simplecov/configuration/thresholds.rb', line 162

def per_group_coverage_replacement(coverage)
  by_criterion = {} #: Hash[Symbol, Array[String]]
  coverage.each do |group_name, thresholds|
    normalized = (thresholds.is_a?(Numeric) ? {primary_coverage => thresholds} : thresholds) #: coverage_thresholds
    normalized.each do |criterion, percent|
      (by_criterion[criterion] ||= []) << "minimum_per_group #{percent}, only: #{group_name.inspect}"
    end
  end
  render_coverage_blocks(by_criterion)
end

#primary_coverage(criterion = nil) ⇒ criterion, :oneshot_line

Gets the report's leading criterion, or sets it. The setter validates at runtime that the criterion is enabled; the parameter type also rejects unknown criteria statically.

Parameters:

  • criterion (?(criterion | :oneshot_line), nil) (defaults to: nil)

Returns:

  • (criterion, :oneshot_line) 


288
289
290
291
292
293
294
295
 
# File 'sig/simplecov.rbs', line 288

def primary_coverage(criterion = nil)
  if criterion.nil?
    @primary_coverage ||= default_primary_coverage
  else
    raise_if_criterion_disabled(criterion)
    @primary_coverage = criterion
  end
end

#print_errors(value = :__no_arg__) ⇒ Boolean

Whether SimpleCov prints its own diagnostic warnings to stderr. Defaults to true.

Parameters:

  • value (?(bool | :__no_arg__)) (defaults to: :__no_arg__)

Returns:

  • (Boolean) 


81
82
83
84
85
 
# File 'lib/simplecov/configuration/formatting.rb', line 81

def print_errors(value = :__no_arg__)
  return defined?(@print_error_status) ? @print_error_status : true if value == :__no_arg__

  @print_error_status = value
end

#profiles ⇒ Profiles

The hash of available profiles.

Returns:



74
75
76
 
# File 'lib/simplecov/configuration.rb', line 74

def profiles
  @profiles ||= SimpleCov::Profiles.new
end

#project_name(new_name = nil) ⇒ String

The project name — defaults to the last dirname in root, capitalized, with underscores replaced by spaces.

Parameters:

  • new_name (String, nil) (defaults to: nil)

Returns:

  • (String) 


145
146
147
148
149
150
151
 
# File 'lib/simplecov/configuration.rb', line 145

def project_name(new_name = nil)
  current = defined?(@project_name) ? @project_name : nil
  return current if current && new_name.nil?

  @project_name = new_name if new_name.is_a?(String)
  @project_name ||= File.basename(root).capitalize.tr("_", " ")
end

#raise_if_branch_type_unsupported(type) ⇒ void

This method returns an undefined value.

Parameters:

  • type (Symbol)

Raises:



47
48
49
50
51
52
53
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 47

def raise_if_branch_type_unsupported(type)
  return if IGNORABLE_BRANCH_TYPES.member?(type)

  raise SimpleCov::ConfigurationError,
        "Unsupported branch type #{type.inspect} for `ignore_branches`. " \
        "Supported values are #{IGNORABLE_BRANCH_TYPES.inspect}"
end

#raise_if_criterion_disabled(criterion) ⇒ void

This method returns an undefined value.

Validators: any Symbol is accepted at the type level; the whole point of these is raising ConfigurationError on bad input.

Parameters:

  • criterion (Symbol) 


330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'sig/simplecov.rbs', line 330

def raise_if_criterion_disabled(criterion)
  # `coverage :eval` by itself IS supported — it's a standalone
  # toggle, never in the enabled-criteria set — so the generic
  # "unsupported criterion" message below would mislead here.
  if criterion == :eval
    raise SimpleCov::ConfigurationError,
          "Coverage criterion :eval only toggles measuring eval'd code; " \
          "it cannot carry thresholds or serve as the primary criterion"
  end

  raise_if_criterion_unsupported(criterion)
  return if coverage_criterion_enabled?(criterion)

  raise SimpleCov::ConfigurationError,
        "Coverage criterion #{criterion}, is disabled! " \
        "Please enable it first through enable_coverage #{criterion} (if supported)"
end

#raise_if_criterion_unsupported(criterion) ⇒ void

This method returns an undefined value.

Parameters:

  • criterion (Symbol)

Raises:



147
148
149
150
151
152
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 147

def raise_if_criterion_unsupported(criterion)
  return if SUPPORTED_COVERAGE_CRITERIA.member?(criterion)

  raise SimpleCov::ConfigurationError,
        "Unsupported coverage criterion #{criterion}, supported values are #{SUPPORTED_COVERAGE_CRITERIA}"
end

#raise_if_method_type_unsupported(type) ⇒ void

This method returns an undefined value.

Parameters:

  • type (Symbol)

Raises:



55
56
57
58
59
60
61
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 55

def raise_if_method_type_unsupported(type)
  return if IGNORABLE_METHOD_TYPES.member?(type)

  raise SimpleCov::ConfigurationError,
        "Unsupported method type #{type.inspect} for `ignore_methods`. " \
        "Supported values are #{IGNORABLE_METHOD_TYPES.inspect}"
end

#raise_on_invalid_coverage(coverage, coverage_setting) ⇒ void

This method returns an undefined value.

Parameters:

  • coverage (coverage_thresholds)
  • coverage_setting (String) 


20
21
22
23
24
25
 
# File 'lib/simplecov/configuration/thresholds.rb', line 20

def raise_on_invalid_coverage(coverage, coverage_setting)
  coverage.each_key { |criterion| raise_if_criterion_disabled(criterion) }
  coverage.each_value do |percent|
    minimum_possible_coverage_exceeded(coverage_setting) if percent && percent > 100
  end
end

#refuse_coverage_drop(*criteria) ⇒ coverage_thresholds

Refuse any coverage drop for the given criteria (all enabled criteria when none are given). Coverage may only increase.

Parameters:

  • criteria (criterion, :oneshot_line)

Returns:

  • (coverage_thresholds) 


105
106
107
108
 
# File 'lib/simplecov/configuration/thresholds.rb', line 105

def refuse_coverage_drop(*criteria)
  criteria = coverage_criteria if criteria.empty?
  maximum_coverage_drop(criteria.to_h { |c| [c, 0] })
end

#remove_filter(filter_argument) ⇒ Boolean

Remove any filters whose filter_argument equals the given value. Returns true when at least one filter was removed.

Parameters:

  • filter_argument (Object)

Returns:

  • (Boolean) 


110
111
112
113
114
 
# File 'lib/simplecov/configuration/filters.rb', line 110

def remove_filter(filter_argument) # rubocop:disable Naming/PredicateMethod
  before = filters.size
  filters.reject! { |filter| filter.respond_to?(:filter_argument) && filter.filter_argument == filter_argument }
  filters.size != before
end

#render_coverage_blocks(by_criterion) ⇒ String

Parameters:

  • by_criterion (Hash[Symbol, Array[String]])

Returns:

  • (String) 


173
174
175
176
177
 
# File 'lib/simplecov/configuration/thresholds.rb', line 173

def render_coverage_blocks(by_criterion)
  by_criterion.map do |criterion, statements|
    "  coverage(#{criterion.inspect}) { #{statements.join('; ')} }"
  end.join("\n")
end

#resolve_criterion_variant(criterion, oneshot) ⇒ criterion, ...

Parameters:

  • criterion (criterion, :eval)
  • oneshot (Boolean)

Returns:

  • (criterion, :oneshot_line, :eval) 


81
82
83
84
85
86
87
88
89
 
# File 'lib/simplecov/configuration/coverage.rb', line 81

def resolve_criterion_variant(criterion, oneshot)
  return criterion unless oneshot

  unless criterion == :line
    raise SimpleCov::ConfigurationError, "`oneshot: true` is only valid for `coverage :line`"
  end

  ONESHOT_LINE_COVERAGE_CRITERION
end

#root(root = nil) ⇒ String

The root for the project, defaulting to the current working directory. Get, or set with SimpleCov.root('/my/project/path').

Parameters:

  • root (String, nil) (defaults to: nil)

Returns:

  • (String) 


18
19
20
21
22
23
 
# File 'lib/simplecov/configuration.rb', line 18

def root(root = nil)
  return @root if defined?(@root) && root.nil?

  @coverage_path = nil unless @coverage_path_explicit # invalidate cache
  @root = File.expand_path(root || Dir.getwd)
end

#skip(filter_argument = nil) ⇒ void

This method returns an undefined value.

Drop matching files from the coverage report. The inverse of cover. Strings match at path-segment boundaries.

Parameters:

  • filter_argument (filter_arg, nil) (defaults to: nil) 


96
97
98
 
# File 'lib/simplecov/configuration/filters.rb', line 96

def skip(filter_argument = nil, &)
  filters << parse_filter(filter_argument, &)
end

#source_in_json(value = :__no_arg__) ⇒ Boolean

Whether coverage.json embeds the full source text of every file. Defaults to true.

Parameters:

  • value (?(bool | :__no_arg__)) (defaults to: :__no_arg__)

Returns:

  • (Boolean) 


103
104
105
106
107
 
# File 'lib/simplecov/configuration/formatting.rb', line 103

def source_in_json(value = :__no_arg__)
  return defined?(@source_in_json) ? @source_in_json : true if value == :__no_arg__

  @source_in_json = value
end

#store_minimum_per_file(criterion, percent, target) ⇒ void

This method returns an undefined value.

Parameters:

  • criterion (Symbol)
  • percent (Numeric)
  • target (String, Regexp, nil) 


99
100
101
102
103
104
105
106
107
108
 
# File 'lib/simplecov/configuration/coverage.rb', line 99

def store_minimum_per_file(criterion, percent, target)
  raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_file")
  return minimum_coverage_by_file[criterion] = percent if target.nil?

  unless target.is_a?(String) || target.is_a?(Regexp)
    raise SimpleCov::ConfigurationError, "`only:` must be a String path or Regexp, got #{target.inspect}"
  end

  (minimum_coverage_by_file_overrides[target] ||= {})[criterion] = percent
end

#store_minimum_per_group(criterion, percent, group_name) ⇒ void

This method returns an undefined value.

Parameters:

  • criterion (Symbol)
  • percent (Numeric)
  • group_name (String) 


110
111
112
113
114
115
116
 
# File 'lib/simplecov/configuration/coverage.rb', line 110

def store_minimum_per_group(criterion, percent, group_name)
  raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_group")
  # Normalize like `group` does, so `only: :Models` finds the group
  # defined as `group "Models"` at check time instead of storing a
  # Symbol key no lookup ever matches.
  (minimum_coverage_by_group[GroupNames.normalize(group_name)] ||= {})[criterion] = percent
end

#store_overall_threshold(setting, criterion, percent) ⇒ void

This method returns an undefined value.

Threshold-store writers used by CoverageCriterion via send. They accept any criterion Symbol; raise_on_invalid_coverage rejects invalid ones (including :eval) at runtime.

Parameters:

  • setting (Symbol)
  • criterion (Symbol)
  • percent (Numeric) 


94
95
96
97
 
# File 'lib/simplecov/configuration/coverage.rb', line 94

def store_overall_threshold(setting, criterion, percent)
  raise_on_invalid_coverage({criterion => percent}, setting.to_s)
  public_send(setting)[criterion] = percent
end

#track_files(glob) ⇒ String?

DEPRECATED: use cover instead.

Parameters:

  • glob (String, nil)

Returns:

  • (String, nil) 


58
59
60
61
62
 
# File 'lib/simplecov/configuration/filters.rb', line 58

def track_files(glob)
  SimpleCov::Deprecation.warn("`SimpleCov.track_files` is deprecated. " \
                              "#{track_files_replacement_hint(glob)}")
  @tracked_files = glob
end

#track_files_replacement_hint(glob) ⇒ String

track_files(nil) is the documented way to clear a previously-set glob, but cover(nil) raises ConfigurationError, so don't point users at it. The cover API has no direct equivalent for "reset the inclusion list" — point users at the @cover_filters reset.

Parameters:

  • glob (String, nil)

Returns:

  • (String) 


68
69
70
71
72
73
74
75
76
77
 
# File 'lib/simplecov/configuration/filters.rb', line 68

def track_files_replacement_hint(glob)
  if glob.nil?
    "Replace with `SimpleCov.cover_filters.clear` — clearing the inclusion list."
  else
    "Replace with `SimpleCov.cover #{glob.inspect}` — `cover` includes unloaded files on disk " \
      "(the historical `track_files` behavior) and also restricts the report to the matching set. " \
      "If you want to keep additional files outside #{glob.inspect} in the report, pass every " \
      "directory you care about, e.g. `cover #{glob.inspect}, \"app/**/*.rb\"`."
  end
end

#tracked_files ⇒ String?

The glob used to include files that were not explicitly required.

Returns:

  • (String, nil) 


80
81
82
 
# File 'lib/simplecov/configuration/filters.rb', line 80

def tracked_files
  @tracked_files if defined?(@tracked_files)
end

#use_merging(use = nil) ⇒ Boolean

DEPRECATED: use merging instead (same value, same behavior). Returns nil when merging had already been disabled.

Parameters:

  • use (Boolean, nil) (defaults to: nil)

Returns:

  • (Boolean) 


92
93
94
95
96
 
# File 'lib/simplecov/configuration/merging.rb', line 92

def use_merging(use = nil)
  SimpleCov::Deprecation.warn("`SimpleCov.use_merging` is deprecated. " \
                              "Replace with `SimpleCov.merging` (same value, same behavior).")
  merging(use)
end

#validate_coverage_criteria! ⇒ void

This method returns an undefined value.

fast when the user has disabled every coverage criterion.

Raises:



59
60
61
62
63
64
65
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 59

def validate_coverage_criteria!
  return unless coverage_criteria.empty?

  raise SimpleCov::ConfigurationError,
        "At least one coverage criterion must be enabled. " \
        "Re-enable one with `enable_coverage :line`, `:branch`, or `:method`."
end

#validate_per_file_key(key) ⇒ void

This method returns an undefined value.

Parameters:

  • key (Symbol, String, Regexp)

Raises:



136
137
138
139
140
141
 
# File 'lib/simplecov/configuration/thresholds.rb', line 136

def validate_per_file_key(key)
  return if key.is_a?(Symbol) || key.is_a?(String) || key.is_a?(Regexp)

  raise SimpleCov::ConfigurationError,
        "minimum_coverage_by_file keys must be Symbol (criterion), String, or Regexp; got #{key.inspect}"
end

#warn_about_inferred_finalize_merge ⇒ void

This method returns an undefined value.



149
150
151
152
153
154
155
 
# File 'lib/simplecov/configuration/merging.rb', line 149

def warn_about_inferred_finalize_merge
  return if defined?(@finalize_merge_inference_warned) && @finalize_merge_inference_warned
  return unless print_errors

  @finalize_merge_inference_warned = true
  warn SimpleCov::Color.colorize(inferred_finalize_merge_warning, :yellow)
end