Module: SimpleCov::Configuration

Included in:
SimpleCov
Defined in:
lib/simplecov/configuration.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/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

Overview

Selection and validation of the coverage criteria Ruby's Coverage library should track. Supports :line (the historical default), :branch, :method, and :oneshot_line, plus the standalone :eval toggle for instrumenting eval'd code.

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

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:



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

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) 


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

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]]) 


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

def groups
  @groups ||= {}
end

#print_error_status ⇒ Boolean

DEPRECATED: use print_errors instead (same value).

Returns:

  • (Boolean) 


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

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) 


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

def active_session?
  SimpleCov.result? || (defined?(Coverage) && Coverage.running?)
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) 


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

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) 


138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/simplecov/configuration/filters.rb', line 138

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.



108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/simplecov/configuration.rb', line 108

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? && SimpleCov.final_result_process?
  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.



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/simplecov/configuration.rb', line 132

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) 


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

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

#branch_coverage_supported? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

Parameters:

  • arg (cover_arg)

Returns:



172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/simplecov/configuration/filters.rb', line 172

def build_cover_filter(arg)
  case arg
  when String            then SimpleCov::GlobFilter.new(arg)
  when Regexp            then SimpleCov::RegexFilter.new(arg)
  when Proc              then SimpleCov::BlockFilter.new(arg)
  when SimpleCov::Filter then arg
  when Array             then SimpleCov::ArrayFilter.new(arg.map { |a| build_cover_filter(a) })
  else raise SimpleCov::ConfigurationError, "Unsupported `cover` argument #{arg.inspect}; " \
                                            "expected a String glob, Regexp, Proc, " \
                                            "SimpleCov::Filter, or Array of those."
  end
end

#clear_coverage_criteria ⇒ void

This method returns an undefined value.

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



56
57
58
59
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 56

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:



120
121
122
 
# File 'lib/simplecov/configuration/filters.rb', line 120

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 the method is available to merge_finalization_owner?.

Returns:

  • (boolish) 


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

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]) 


187
188
189
190
191
192
193
194
195
 
# File 'lib/simplecov/configuration/filters.rb', line 187

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) 


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

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 { ... } ⇒ void

This method returns an undefined value.

Configure SimpleCov in a block, evaluated with self bound to the configuration target (usually the SimpleCov module itself):

SimpleCov.configure { skip "test" }

Yields:

Yield Returns:

  • (void) 


82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/simplecov/configuration.rb', line 82

def configure(&block)
  # Both locals are read in the ensure clause, where flow analysis
  # cannot see the assignments below; anchor their types up front.
  saved = nil # : Hash[Symbol, untyped]?
  block_context = block.binding.receiver # : untyped

  # If the block was defined in our own context, instance_exec is
  # sufficient. The `_ =` erases the block's self-binding, which RBS
  # can express but `instance_exec`'s core signature cannot accept.
  return instance_exec(&(_ = block)) if equal?(block_context)

  # Copy the caller's instance variables in so that references like @filter
  # inside the block resolve to the caller's values, not ours.
  saved = swap_ivars_from(block_context)
  instance_exec(&(_ = block))
ensure
  # @type var block_context: untyped
  # @type var saved: Hash[Symbol, untyped]?
  restore_ivars(block_context, saved) if saved
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) 


34
35
36
37
38
 
# File 'lib/simplecov/configuration/filters.rb', line 34

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:



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

def cover_filters
  @cover_filters ||= []
end

#cover_globs ⇒ Array[String]

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

Returns:

  • (Array[String]) 


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

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; :eval is enable-only. 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 enable-only and 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]) 


263
264
265
 
# File 'sig/simplecov.rbs', line 263

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) 


268
269
270
 
# File 'sig/simplecov.rbs', line 268

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) 


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

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

simplecov:enable

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 107

def coverage_for_eval_enabled?
  @coverage_for_eval_enabled ||= false
end

#coverage_for_eval_supported? ⇒ Boolean

Returns:

  • (Boolean) 


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

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) 


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

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) 


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

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. Disabling every criterion raises at start_tracking, not here.

Parameters:

  • criterion (criterion, :oneshot_line) 


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

def disable_coverage(criterion)
  raise_if_criterion_unsupported(criterion)
  coverage_criteria.delete(criterion)
  @primary_coverage = nil if @primary_coverage == criterion
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; :oneshot_line replaces :line.

Parameters:

  • criteria (criterion, :oneshot_line, :eval) 


15
16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 15

def enable_coverage(*criteria)
  criteria.each do |criterion|
    if criterion == :eval
      enable_eval_coverage
    else
      raise_if_criterion_unsupported(criterion)
      # :oneshot_lines can not be combined with :lines
      coverage_criteria.delete(DEFAULT_COVERAGE_CRITERION) if criterion == ONESHOT_LINE_COVERAGE_CRITERION
      coverage_criteria << criterion
    end
  end
end

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

Enable 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
80
81
 
# File 'lib/simplecov/configuration/coverage.rb', line 75

def enable_coverage_criterion(criterion, enabled:, oneshot:)
  return enable_oneshot_line(criterion) if oneshot
  return enable_eval_coverage_criterion if criterion == :eval

  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.



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

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.



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

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_eval_coverage_criterion ⇒ :eval

Returns:

  • (:eval) 


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

def enable_eval_coverage_criterion
  enable_coverage(:eval)
  :eval
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
43
44
 
# 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).")
  return @enable_for_subprocesses if defined?(@enable_for_subprocesses) && value.nil?

  @enable_for_subprocesses = value || false
end

#enable_oneshot_line(criterion) ⇒ :oneshot_line

Parameters:

  • criterion (criterion, :eval)

Returns:

  • (:oneshot_line) 


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

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

  enable_coverage(ONESHOT_LINE_COVERAGE_CRITERION)
  ONESHOT_LINE_COVERAGE_CRITERION
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) 


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

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

  minimum_coverage(coverage)
  maximum_coverage(coverage)
end

#explicit_coverage_destination? ⇒ Boolean

Returns:

  • (Boolean) 


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

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) 


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

def explicit_custom_coverage_destination?
  return false unless explicit_coverage_destination?

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

#finalize_merge(value = :__no_arg__) ⇒ Boolean

Get or set whether this process owns final 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) 


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

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) 


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

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) 


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

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) 


44
45
46
47
 
# File 'lib/simplecov/configuration/formatting.rb', line 44

def formatters=(formatters)
  formatters = Array(formatters)
  @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) 


133
134
135
 
# File 'lib/simplecov/configuration/filters.rb', line 133

def group(group_name, filter_argument = nil, &)
  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) 


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

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) 


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

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

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


35
36
37
38
39
40
41
 
# File 'lib/simplecov/configuration/thresholds.rb', line 35

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

  coverage = {primary_coverage => coverage} if coverage.is_a?(Numeric)
  raise_on_invalid_coverage(coverage, "maximum_coverage")
  @maximum_coverage = 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) 


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

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

  coverage_drop = {primary_coverage => coverage_drop} if coverage_drop.is_a?(Numeric)
  raise_on_invalid_coverage(coverage_drop, "maximum_coverage_drop")
  @maximum_coverage_drop = 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) 


85
86
87
 
# File 'lib/simplecov/configuration/merging.rb', line 85

def merge_finalization_owner?
  collating_result? || finalize_merge?
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) 


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

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) 


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

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) 


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

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

#method_coverage_supported? ⇒ Boolean

Returns:

  • (Boolean) 


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

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
19
20
 
# File 'lib/simplecov/configuration/thresholds.rb', line 14

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

  coverage = {primary_coverage => coverage} if coverage.is_a?(Numeric)
  raise_on_invalid_coverage(coverage, "minimum_coverage")
  @minimum_coverage = 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]) 


73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/simplecov/configuration/thresholds.rb', line 73

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]) 


90
91
92
 
# File 'lib/simplecov/configuration/thresholds.rb', line 90

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]) 


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

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.dup.transform_values do |group_coverage|
    group_coverage = {primary_coverage => group_coverage} if group_coverage.is_a?(Numeric)
    raise_on_invalid_coverage(group_coverage, "minimum_coverage_by_group")
    group_coverage
  end
end

#minimum_possible_coverage_exceeded(coverage_option) ⇒ void

This method returns an undefined value.

Parameters:

  • coverage_option (String) 


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

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:



155
156
157
 
# File 'lib/simplecov/configuration/filters.rb', line 155

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) 


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

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

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


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

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) 


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

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) 


162
163
164
165
166
167
168
 
# File 'lib/simplecov/configuration/filters.rb', line 162

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]]) 


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

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) 


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

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) 


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

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) 


260
261
262
263
264
265
266
267
 
# File 'sig/simplecov.rbs', line 260

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) 


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

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) 


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

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) 


303
304
305
306
307
308
309
310
 
# File 'sig/simplecov.rbs', line 303

def raise_if_criterion_disabled(criterion)
  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:



151
152
153
154
155
156
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 151

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) 


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

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) 


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

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) 


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

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) 


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

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

#restore_ivars(block_context, saved) ⇒ void

This method returns an undefined value.

Copy instance variables back to block_context and restore ours.

Parameters:

  • block_context (Object)
  • saved (Hash[Symbol, untyped]) 


178
179
180
181
182
183
 
# File 'lib/simplecov/configuration.rb', line 178

def restore_ivars(block_context, saved)
  block_context.instance_variables.each do |ivar|
    block_context.instance_variable_set(ivar, instance_variable_get(ivar))
  end
  saved.each { |ivar, value| instance_variable_set(ivar, value) }
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) 


98
99
100
 
# File 'lib/simplecov/configuration/filters.rb', line 98

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) 


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

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) 


105
106
107
108
109
110
111
112
113
114
 
# File 'lib/simplecov/configuration/coverage.rb', line 105

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) 


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

def store_minimum_per_group(criterion, percent, group_name)
  raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_group")
  (minimum_coverage_by_group[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) 


100
101
102
103
 
# File 'lib/simplecov/configuration/coverage.rb', line 100

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

#swap_ivars_from(block_context) ⇒ Hash[Symbol, untyped]

Copy instance variables from block_context into self, saving any of ours that would be clobbered.

Parameters:

  • block_context (Object)

Returns:

  • (Hash[Symbol, untyped]) 


167
168
169
170
171
172
173
174
175
 
# File 'lib/simplecov/configuration.rb', line 167

def swap_ivars_from(block_context)
  saved = {} # : Hash[Symbol, untyped]
  our_ivars = instance_variables
  block_context.instance_variables.each do |ivar|
    saved[ivar] = instance_variable_get(ivar) if our_ivars.include?(ivar)
    instance_variable_set(ivar, block_context.instance_variable_get(ivar))
  end
  saved
end

#track_files(glob) ⇒ String?

DEPRECATED: use cover instead.

Parameters:

  • glob (String, nil)

Returns:

  • (String, nil) 


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

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) 


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

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) 


82
83
84
 
# File 'lib/simplecov/configuration/filters.rb', line 82

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, nil) 


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

def use_merging(use = nil)
  SimpleCov::Deprecation.warn("`SimpleCov.use_merging` is deprecated. " \
                              "Replace with `SimpleCov.merging` (same value, same behavior).")
  @use_merging = use unless use.nil?
  @use_merging = true unless defined?(@use_merging) && @use_merging == false
end

#validate_coverage_criteria! ⇒ void

This method returns an undefined value.

fast when the user has disabled every coverage criterion.

Raises:



63
64
65
66
67
68
69
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 63

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:



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

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.



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

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