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/history.rb,
lib/simplecov/configuration/merging.rb,
lib/simplecov/configuration/baseline.rb,
lib/simplecov/configuration/coverage.rb,
lib/simplecov/configuration/formatting.rb,
lib/simplecov/configuration/production.rb,
lib/simplecov/configuration/thresholds.rb,
lib/simplecov/configuration/missed_caps.rb,
lib/simplecov/configuration/deprecations.rb,
lib/simplecov/configuration/eval_coverage.rb,
lib/simplecov/configuration/test_tracking.rb,
lib/simplecov/configuration/view_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,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs,
sig/simplecov.rbs

Defined Under Namespace

Classes: CoverageCriterion

Constant Summary collapse

DROP_BASELINES =

Returns:

  • (Array[Symbol]) 
%i[last_run median branch].freeze
COVERAGE_THRESHOLD_OPTIONS =

Returns:

  • (Array[Symbol]) 
%i[minimum maximum exact maximum_drop ignore minimum_per_file
maximum_missed maximum_missed_per_file].freeze
BUILT_IN_FORMATS =

Returns:

  • (Hash[Symbol, Symbol]) 
{
  html: :HTMLFormatter, json: :JSONFormatter, simple: :SimpleFormatter, baseline: :BaselineFormatter
}.freeze
LAZY_FORMAT_REQUIRES =

Returns:

  • (Hash[Symbol, String]) 
{html: "../../simplecov-html"}.freeze
DEPRECATION_MODES =

Returns:

  • (Array[Symbol]) 
Deprecation::MODES
TRACK_TESTS_GRANULARITIES =

Returns:

  • (Array[Symbol]) 
%i[test file].freeze
DEFAULT_VIEW_GLOBS =

Returns:

  • (Array[String]) 
%w[app/views/**/*.{erb,haml,slim}].freeze
IGNORABLE_BRANCH_TYPES =

Returns:

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

Returns:

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

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 =

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

Returns:



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

def filters
  @filters ||= []
end

#formatter(formatter = :__no_arg__) ⇒ Class?

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
  end
end

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

Returns:

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


5
6
7
 
# File 'lib/simplecov/configuration/groups.rb', line 5

def groups
  @groups ||= {}
end

#print_error_status ⇒ Boolean

Returns:

  • (Boolean) 


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

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

Instance Method Details

#__send__ ⇒ Object

Parameters:

  • name (Symbol)
  • args (Object)

Returns:

  • (Object) 


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

def __send__: (Symbol name, *untyped args) -> untyped

#active_session? ⇒ Boolean

The Coverage module is actively tracking, or a @result has already been assembled (SimpleCov.collate never starts Coverage).

Returns:

  • (Boolean) 


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

def active_session?
  !!SimpleCov.result? || coverage_running?
end

#add_coverage_criterion(criterion) ⇒ void

This method returns an undefined value.

Parameters:

  • criterion (criterion, :oneshot_line) 


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

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.

Parameters:

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


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

def add_filter(filter_argument = nil, &block)
  example = block ? "`SimpleCov.skip { ... }`" : "`SimpleCov.skip #{filter_argument.inspect}`"
  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.

Parameters:

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


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

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

Parameters:



22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/simplecov/configuration/coverage.rb', line 22

def apply_threshold_options(configurator, options)
  options.each do |verb, value|
    unless COVERAGE_THRESHOLD_OPTIONS.include?(verb)
      raise 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.



93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/simplecov/configuration.rb', line 93

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

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

#at_fork(&block) ⇒ void

This method returns an undefined value.



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/simplecov/configuration.rb', line 117

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. Built 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 (#1171).
    SimpleCov.command_name "#{SimpleCov.command_name} (subprocess: #{SimpleCov.subprocess_serial})"
    SimpleCov.print_errors false
    SimpleCov.formatter Formatter::SimpleFormatter
    SimpleCov.minimum_coverage 0
    SimpleCov.start
  }
end

#baseline ⇒ Baseline?

Memoized per resolved path so the exit check and the JSON formatter's errors section read the file once, while a baseline_file or root change between reads is still picked up.

Returns:



23
24
25
26
27
28
29
 
# File 'lib/simplecov/configuration/baseline.rb', line 23

def baseline
  resolved = File.expand_path(baseline_file, root)
  return @baseline if @baseline_path.eql?(resolved)

  @baseline_path = resolved
  @baseline = Baseline.read_if_exists(resolved)
end

#baseline_file(path = nil) ⇒ String

The baseline's path, relative to SimpleCov.root; an absolute path is honored as given. The file's presence is the opt-in: generate it with simplecov ratchet, check it in, and the exit check holds every listed file to its own floor (#1268).

Parameters:

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

Returns:

  • (String) 


9
10
11
12
13
14
 
# File 'lib/simplecov/configuration/baseline.rb', line 9

def baseline_file(path = nil)
  return @baseline_file ||= Baseline::DEFAULT_FILENAME unless path

  self.baseline_file = path
  _ = @baseline_file
end

#baseline_file=(path) ⇒ String

Parameters:

  • path (String)

Returns:

  • (String) 


16
17
18
 
# File 'lib/simplecov/configuration/baseline.rb', line 16

def baseline_file=(path)
  @baseline_file = path
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]

Strings are treated as globs, not substrings (that's skip's semantics); everything else dispatches exactly like add_filter.

Parameters:

  • arg (cover_arg)

Returns:



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

def build_cover_filter(arg)
  Filter.build_filter(arg, string_filter: GlobFilter)
rescue ConfigurationError
  raise 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.



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

def clear_coverage_criteria
  @coverage_criteria = nil
  @primary_coverage = nil
end

#clear_filters ⇒ Array[Filter[untyped]]

Returns:



91
92
93
 
# File 'lib/simplecov/configuration/filters.rb', line 91

def clear_filters
  @filters = []
end

#collating_result? ⇒ boolish

Returns:

  • (boolish) 


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

def collating_result?: () -> boolish

#collect_cover_globs(filter_list) ⇒ Array[String]

Descends into ArrayFilter wrappers built by cover(["a", "b"]).

Parameters:

  • filter_list (Array[Filter[untyped]])

Returns:

  • (Array[String]) 


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

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

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

Parameters:

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

Returns:

  • (bool, :auto) 


50
51
52
53
54
 
# File 'lib/simplecov/configuration/formatting.rb', line 50

def color(value = :__no_arg__)
  return instance_variable_defined?(:@color) ? @color : :auto if value.eql?(:__no_arg__)

  self.color = _ = value
end

#color=(value) ⇒ Object

Parameters:

  • value (Object)

Returns:

  • (Object) 


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

def color=(value)
  @color = value
end

#combined_formatter(formatters) ⇒ Object

An empty list is how a project opts out of formatting.

Parameters:

  • formatters (Array[untyped])

Returns:

  • (Object) 


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

def combined_formatter(formatters)
  return if formatters.empty?

  Formatter::MultiFormatter.new(formatters)
end

#command_name(name = nil) ⇒ String

The name of the command (a.k.a. Test Suite) currently running. Used for result merging and caching. Auto-detected.

Parameters:

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

Returns:

  • (String) 


64
65
66
67
 
# File 'lib/simplecov/configuration.rb', line 64

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

#command_name=(name) ⇒ String

Parameters:

  • name (String)

Returns:

  • (String) 


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

def command_name=(name)
  @command_name = name
end

#configure ⇒ self #configure ⇒ self

Configure simplecov in a block instead of prepending SimpleCov to each config method. Parameterized blocks retain their caller context and receive this configuration target explicitly.

Overloads:

  • #configure ⇒ self

    Returns:

    • (self)
  • #configure ⇒ self

    Returns:

    • (self)

Yields:

Yield Parameters:

  • config (self)

Yield Returns:

  • (void)

Raises:

  • (ArgumentError) 


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

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 universe of files in the coverage report to those matching one or more globs, regexps, or block predicates. Multiple calls union; when any cover matcher is configured the report drops every file that doesn't match at least one of them.

Strings are interpreted as shell globs, not substring matches, a deliberate departure from the legacy add_filter semantics.

A string glob is also expanded on disk, so files that exist but were never required during the run still appear in the report at 0%. This is the "include unloaded files" half of the legacy track_files behavior.

Parameters:

  • args (cover_arg) 


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

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

#cover_filters ⇒ Array[Filter[untyped]]

Returns:



26
27
28
 
# File 'lib/simplecov/configuration/filters.rb', line 26

def cover_filters
  @cover_filters ||= []
end

#cover_globs ⇒ Array[String]

The string globs passed to cover, used by the disk-discovery pass in SimpleCov.tracked_file_paths so files matching a cover glob appear in the report even when they were never required during the suite.

Returns:

  • (Array[String]) 


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

def cover_globs
  collect_cover_globs(cover_filters)
end

#cover_views(*globs) ⇒ Array[String]

Reports coverage for ActionView templates, defaulting to a Rails app's views. Globs are expanded against SimpleCov.root, and one naming an extension no handler is registered for (as the default does whenever a project has no Haml or Slim) leaves those files out rather than reporting them as empty.

Templates the suite renders are measured through eval coverage, which this enables. Templates it never renders are compiled at the end of the run so they appear at 0% instead of going missing.

Parameters:

  • globs (String, Array[String?], nil)

Returns:

  • (Array[String]) 


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

def cover_views(*globs)
  globs = globs.flatten.compact
  globs = DEFAULT_VIEW_GLOBS.dup if globs.empty?
  @view_globs = globs
  enable_eval_coverage
  globs
end

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

This method returns an undefined value.

Parameters:

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


8
9
10
11
12
13
14
15
16
17
18
 
# File 'lib/simplecov/configuration/coverage.rb', line 8

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

Returns:

  • (Set[criterion | :oneshot_line]) 


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

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

#coverage_criterion_enabled?(criterion) ⇒ Boolean

Parameters:

  • criterion (Symbol)

Returns:

  • (Boolean) 


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

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

#coverage_criterion_supported?(criterion) ⇒ Boolean

Older Rubies don't expose Coverage.supported?, so fall back to the historical engine check that line/branch/method were unavailable on JRuby. :eval was added later, so its fallback is "always unsupported".

Parameters:

  • criterion (Symbol)

Returns:

  • (Boolean) 


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

def coverage_criterion_supported?(criterion)
  load_coverage
  return Coverage.supported?(criterion) if Coverage.respond_to?(:supported?)

  !criterion.eql?(:eval) && !RUBY_ENGINE.eql?("jruby")
end

#coverage_dir(dir = nil) ⇒ String

Parameters:

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

Returns:

  • (String) 


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

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

  self.coverage_dir = dir
  @coverage_dir
end

#coverage_dir=(dir) ⇒ String

nil means the default 'coverage', recorded as a derivation rather than a choice.

Parameters:

  • dir (String, nil)

Returns:

  • (String) 


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

def coverage_dir=(dir)
  @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) 


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

def coverage_for_eval_enabled?
  @coverage_for_eval_enabled ||= false
end

#coverage_for_eval_supported? ⇒ Boolean

The standalone eval-coverage toggle, kept apart from the criteria-set logic in coverage_criteria.rb because :eval is a boolean toggle, never a member of the enabled-criteria set.

Returns:

  • (Boolean) 


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

def coverage_for_eval_supported?
  coverage_criterion_supported?(:eval)
end

#coverage_path(path = nil) ⇒ String

Defaults to SimpleCov.root + SimpleCov.coverage_dir, but callers can override with an arbitrary absolute path, handy for out-of-tree build directories (#716).

Reading is pure: the directory is only created when a path is explicitly assigned. The codepaths that write into it ensure existence themselves, so read-only CLI subcommands that interpolate the path into status text don't materialize a stray coverage/ directory.

Parameters:

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

Returns:

  • (String) 


45
46
47
48
49
 
# File 'lib/simplecov/configuration.rb', line 45

def coverage_path(path = nil)
  self.coverage_path = path if path

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

#coverage_path=(path) ⇒ Object

Assigning is the signal the caller intends to write there, so the directory is created.

Parameters:

  • path (String)

Returns:

  • (Object) 


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

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

#coverage_running? ⇒ Boolean

A configuration loaded on its own may have no Coverage to ask, which is not something a suite that measures coverage can be.

Returns:

  • (Boolean) 


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

def coverage_running?
  defined?(Coverage) ? Coverage.running? : false
end

#current_nocov_token(value = nil) ⇒ String

Parameters:

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

Returns:

  • (String) 


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

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

  @nocov_token = value || "nocov"
end

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

The group set SimpleCov.grouped bins against when its caller names none. It reads through a method of its own because the keyword it defaults shadows groups, so the default has to name a receiver, and every spelling of that receiver is the same call.

mutant:disable — for that reason: SimpleCov.groups, self.groups and groups() cannot be told apart.

Returns:

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


16
17
18
 
# File 'lib/simplecov/configuration/groups.rb', line 16

def default_groups
  groups
end

#default_primary_coverage ⇒ criterion, :oneshot_line

Answering :line even when it is disabled would propagate broken state into minimum_coverage 90, so fall back to whichever criterion the user actually enabled, in insertion order.

Returns:

  • (criterion, :oneshot_line) 


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

def default_primary_coverage
  return DEFAULT_COVERAGE_CRITERION if coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION)

  _ = coverage_criteria.first
end

#deprecations(mode = nil) ⇒ Symbol

The configuration DSL migrates by warn-and-delegate, which means a project can run on deprecated spellings indefinitely without noticing. deprecations :raise turns every deprecated API into a ConfigurationError, so a project that has migrated can guard in CI against old spellings creeping back. There is deliberately no silencing mode: a deprecation you cannot see is a migration you never make.

Parameters:

  • mode (Symbol, nil) (defaults to: nil)

Returns:

  • (Symbol) 


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

def deprecations(mode = nil)
  return Deprecation.mode unless mode

  Deprecation.mode = mode
end

#disable_coverage(criterion) ⇒ void

This method returns an undefined value.

Disabling every criterion raises at start_tracking, not here, so config files that toggle criteria in arbitrary order don't have to worry about transient empty states.

Parameters:

  • criterion (criterion, :oneshot_line, :eval) 


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

def disable_coverage(criterion)
  return disable_eval_coverage if criterion.equal?(:eval)

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

#disable_eval_coverage ⇒ void

This method returns an undefined value.

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



33
34
35
 
# File 'lib/simplecov/configuration/eval_coverage.rb', line 33

def disable_eval_coverage
  @coverage_for_eval_enabled = false
end

#drop_baseline(mode = nil) ⇒ Symbol

What maximum_coverage_drop measures the drop against: :last_run (the default) the previous run whatever it was, :median the median of the recorded history so one run that dipped for an unrelated reason cannot quietly become the baseline, and :branch the newest recorded run on the current git branch so a feature branch is compared with itself.

The latter two read coverage/.history.json and find nothing to compare against while it is empty, which counts as "no previous run" the way a missing .last_run.json does.

Parameters:

  • mode (Symbol, nil) (defaults to: nil)

Returns:

  • (Symbol) 


33
34
35
36
37
38
39
40
41
42
 
# File 'lib/simplecov/configuration/history.rb', line 33

def drop_baseline(mode = nil)
  return @drop_baseline ||= :last_run if mode.nil?

  unless DROP_BASELINES.include?(mode)
    raise ConfigurationError,
      "drop_baseline takes one of #{DROP_BASELINES}, got #{mode.inspect}"
  end

  @drop_baseline = mode
end

#enable_coverage(*criteria) ⇒ void

This method returns an undefined value.

Parameters:

  • criteria (criterion, :oneshot_line, :eval) 


11
12
13
14
15
 
# File 'lib/simplecov/configuration/coverage_criteria.rb', line 11

def enable_coverage(*criteria)
  criteria.each do |criterion|
    criterion.equal?(:eval) ? enable_eval_coverage : add_coverage_criterion(_ = criterion)
  end
end

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

Parameters:

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

Returns:

  • (criterion, :oneshot_line, :eval) 


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

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.



16
17
18
19
20
 
# File 'lib/simplecov/configuration/eval_coverage.rb', line 16

def enable_coverage_for_eval
  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.



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

def enable_eval_coverage
  if coverage_for_eval_supported?
    @coverage_for_eval_enabled = true
  else
    warn "Coverage for eval is not available on this Ruby"
  end
end

#enable_for_subprocesses(value = nil) ⇒ Boolean

Parameters:

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

Returns:

  • (Boolean) 


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

def enable_for_subprocesses(value = nil)
  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

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) 


24
25
26
 
# File 'lib/simplecov/configuration/merging.rb', line 24

def enabled_for_subprocesses?
  !!@enable_for_subprocesses
end

#env_merge_timeout ⇒ Integer?

Returns:

  • (Integer, nil) 


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

def env_merge_timeout
  value = ENV.fetch("SIMPLECOV_MERGE_TIMEOUT", nil)
  Integer(value, 10) if value&.match?(/\A\d+\z/)
end

#expected_coverage(coverage = nil) ⇒ coverage_thresholds

Parameters:

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

Returns:

  • (coverage_thresholds) 


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

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

  minimum_coverage(coverage)
  maximum_coverage(coverage)
end

#explicit_coverage_destination? ⇒ Boolean

Returns:

  • (Boolean) 


177
178
179
 
# File 'lib/simplecov/configuration/merging.rb', line 177

def explicit_coverage_destination?
  @coverage_path_explicit || @coverage_dir_explicit
end

#explicit_custom_coverage_destination? ⇒ Boolean

Returns:

  • (Boolean) 


171
172
173
174
175
 
# File 'lib/simplecov/configuration/merging.rb', line 171

def explicit_custom_coverage_destination?
  return false unless explicit_coverage_destination?

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

#final_result_process? ⇒ boolish

Returns:

  • (boolish) 


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

def final_result_process?: () -> boolish

#finalize_merge(*value) ⇒ Boolean

Whether SimpleCov's selected final process owns merge processing: waiting for sibling workers, building the merged result, formatting, enforcing thresholds, and writing .last_run.json.

Defaults to true, except for recognized multi-worker parallel runs that explicitly write to a custom coverage destination while merging is enabled. Those runs are likely using an external SimpleCov.collate step to finalize the merge.

Splatted rather than defaulted: false is a value someone sets on purpose, so "given nothing" cannot be told from it by looking at the argument.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/simplecov/configuration/merging.rb', line 72

def finalize_merge(*value)
  unless value.empty?
    explicit, = value
    self.finalize_merge = _ = explicit
  end

  return @finalize_merge if @finalize_merge_explicit

  inferred = inferred_finalize_merge?
  warn_about_inferred_finalize_merge unless inferred
  inferred
end

#finalize_merge=(value) ⇒ Boolean

Writing is what makes the answer explicit rather than inferred.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


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

def finalize_merge=(value)
  @finalize_merge = value
  @finalize_merge_explicit = true
end

#finalize_merge? ⇒ Boolean

Returns:

  • (Boolean) 


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

def finalize_merge?
  finalize_merge
end

#formats(*names) ⇒ Array[Class], ...

Parameters:

  • names (Object)

Returns:

  • (Array[Class], Class, nil) 


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

def formats(*names)
  return formatters if names.empty?

  self.formatters = names.map { |name| resolve_format(name) }
  formatters
end

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

Parameters:

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

Returns:

  • (Array[Class], Class, nil) 


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

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

#formatters=(formatters) ⇒ void

This method returns an undefined value.

nil, false, and [] all opt out of formatting entirely. false is normalized first, since Array(false) would otherwise smuggle it in as a "formatter" that can only fail.

Parameters:

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


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

def formatters=(formatters)
  @formatter = combined_formatter(Array(formatters || nil))
end

#group(group_name, filter_argument = nil) ⇒ void

This method returns an undefined value.

Same matcher grammar as skip, but instead of dropping the matching files it bins them under group_name for the formatter. Files matched by no group fall into the implicit "Ungrouped" bucket.

Parameters:

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


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

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

#history_limit(limit = nil) ⇒ Integer

How many runs coverage/.history.json keeps, newest kept. 0 disables recording entirely, and anything but a count of runs is refused.

Parameters:

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

Returns:

  • (Integer) 


9
10
11
12
13
14
 
# File 'lib/simplecov/configuration/history.rb', line 9

def history_limit(limit = nil)
  return @history_limit ||= 100 if limit.nil?

  self.history_limit = limit
  _ = @history_limit
end

#history_limit=(limit) ⇒ Integer

Parameters:

  • limit (Integer)

Returns:

  • (Integer) 


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

def history_limit=(limit)
  unless limit.instance_of?(Integer) && limit >= 0
    raise ConfigurationError, "history_limit takes a non-negative integer, got #{limit.inspect}"
  end

  @history_limit = limit
end

#ignore_branches(*types) ⇒ Array[Symbol]

Deprecated in favour of coverage(:branch) { ignore :implicit_else }, which fixes the criterion by context the way the threshold verbs do. One difference rides out the deprecation period: the coverage block enables the criterion it names, while this legacy setter records without enabling.

Parameters:

  • types (:implicit_else, :eval_generated)

Returns:

  • (Array[Symbol]) 


12
13
14
15
16
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 12

def ignore_branches(*types)
  Deprecation.warn("`SimpleCov.ignore_branches` is deprecated. " \
                   "Replace with `coverage(:branch) { ignore #{types.map(&:inspect).join(", ")} }`.")
  store_ignored_branches(types)
end

#ignore_methods(*types) ⇒ Array[Symbol]

Parameters:

  • types (:eval_generated)

Returns:

  • (Array[Symbol]) 


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

def ignore_methods(*types)
  Deprecation.warn("`SimpleCov.ignore_methods` is deprecated. " \
                   "Replace with `coverage(:method) { ignore #{types.map(&:inspect).join(", ")} }`.")
  store_ignored_methods(types)
end

#ignored_branch?(type) ⇒ Boolean

Parameters:

  • type (Symbol)

Returns:

  • (Boolean) 


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

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

#ignored_branches ⇒ Array[Symbol]

Returns:

  • (Array[Symbol]) 


18
19
20
 
# File 'lib/simplecov/configuration/ignored_entries.rb', line 18

def ignored_branches
  @ignored_branches ||= []
end

#ignored_method?(type) ⇒ Boolean

Parameters:

  • type (Symbol)

Returns:

  • (Boolean) 


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

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

#ignored_methods ⇒ Array[Symbol]

Returns:

  • (Array[Symbol]) 


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

def ignored_methods
  @ignored_methods ||= []
end

#inferred_finalize_merge? ⇒ Boolean

Returns:

  • (Boolean) 


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

def inferred_finalize_merge?
  return true unless merging

  adapter = 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) 


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

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) 


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

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

#load_coverage ⇒ Object

Loading simplecov/configuration on its own leaves Coverage undefined, and this question is asked at configuration time.

Returns:

  • (Object) 


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

def load_coverage
  require "coverage"
end

#maximum_coverage(coverage = nil) ⇒ coverage_thresholds

The maximum overall coverage allowed for the testsuite to pass. Useful paired with minimum_coverage (or via expected_coverage) to pin coverage to an exact value, so an unexpected jump up fails the build (#187).

Parameters:

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

Returns:

  • (coverage_thresholds) 


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

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

Parameters:

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

Returns:

  • (coverage_thresholds) 


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

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

#maximum_missed(counts = nil) ⇒ missed_caps

Caps the total number of misses per criterion. Where a percent minimum asks for a ratio, this asks for an absolute burn-down number, which stays meaningful as the codebase grows and shrinks.

Parameters:

  • counts (?(Numeric | missed_caps), nil) (defaults to: nil)

Returns:

  • (missed_caps) 


8
9
10
11
12
 
# File 'lib/simplecov/configuration/missed_caps.rb', line 8

def maximum_missed(counts = nil)
  return @maximum_missed ||= {} unless counts

  @maximum_missed = normalized_missed_caps(counts, "maximum_missed")
end

#maximum_missed_per_file(counts = nil) ⇒ missed_caps

Unlike a percent minimum, which systematically flatters big files, this holds every file to the same absolute budget. Files with a baseline entry are exempt per covered criterion, as they are from the per-file minimum.

Parameters:

  • counts (?(Numeric | missed_caps), nil) (defaults to: nil)

Returns:

  • (missed_caps) 


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

def maximum_missed_per_file(counts = nil)
  return @maximum_missed_per_file ||= {} unless counts

  Deprecation.warn("`SimpleCov.maximum_missed_per_file` is deprecated. " \
                   "Replace it with:\n#{missed_per_file_replacement(counts)}")
  @maximum_missed_per_file = normalized_missed_caps(counts, "maximum_missed_per_file")
end

#maximum_missed_per_file_overrides ⇒ Hash[String | Regexp, missed_caps]

Returns:

  • (Hash[String | Regexp, missed_caps]) 


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

def maximum_missed_per_file_overrides
  @maximum_missed_per_file_overrides ||= {}
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) 


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

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

#merge_subprocesses(value = nil) ⇒ Boolean

Whether SimpleCov should hook Process._fork to attach itself to subprocesses. Required when the suite uses parallel test workers (Rails' parallelize(workers:)). Defaults to false.

Parameters:

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

Returns:

  • (Boolean) 


10
11
12
13
14
15
 
# File 'lib/simplecov/configuration/merging.rb', line 10

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

  self.merge_subprocesses = value
  @enable_for_subprocesses
end

#merge_subprocesses=(value) ⇒ Object

false stands in for nothing, so the answer is always a real opt-in or opt-out.

Parameters:

  • value (Boolean, nil)

Returns:

  • (Object) 


19
20
21
 
# File 'lib/simplecov/configuration/merging.rb', line 19

def merge_subprocesses=(value)
  @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. Default is 600 seconds.

A numeric SIMPLECOV_MERGE_TIMEOUT in the environment takes precedence over the configured value: simplecov watch re-runs test subsets across a long session and extends its child runs' merge window this way, where editing every watched project's configuration is not an option.

Parameters:

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

Returns:

  • (Integer) 


115
116
117
118
119
120
121
122
123
124
 
# File 'lib/simplecov/configuration/merging.rb', line 115

def merge_timeout(seconds = nil)
  self.merge_timeout = seconds
  # Memoized through a local rather than `|| (@merge_timeout ||= 600)`:
  # steep 2.0's logic-type interpreter crashes on an or-assignment nested in
  # a logical operand, and ivar narrowing doesn't carry across statements
  # the way a local's does.
  configured = @merge_timeout || 600
  @merge_timeout = configured
  env_merge_timeout || configured
end

#merge_timeout=(seconds) ⇒ Object

Anything but an Integer is ignored, the way the dual method always did.

Parameters:

  • seconds (Object)

Returns:

  • (Object) 


127
128
129
 
# File 'lib/simplecov/configuration/merging.rb', line 127

def merge_timeout=(seconds)
  @merge_timeout = seconds if seconds.instance_of?(Integer)
end

#merging(use = nil) ⇒ Boolean

Parameters:

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

Returns:

  • (Boolean) 


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

def merging(use = nil)
  self.merging = use unless use.nil?
  # Unset reads as nil, and only an explicit `merging false` turns it off.
  @use_merging = true if @use_merging.nil?
  @use_merging
end

#merging=(use) ⇒ Boolean

Parameters:

  • use (Boolean)

Returns:

  • (Boolean) 


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

def merging=(use)
  @use_merging = use
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

Parameters:

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

Returns:

  • (coverage_thresholds) 


5
6
7
8
9
 
# File 'lib/simplecov/configuration/thresholds.rb', line 5

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]

The minimum coverage per file required for the testsuite to pass. Accepts a Numeric (global threshold on the primary criterion), a Symbol-keyed Hash (per-criterion globals), or a Hash mixing Symbol keys with String / Regexp keys to declare per-path overrides (#575).

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


49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/simplecov/configuration/thresholds.rb', line 49

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)

  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]

Returns:

  • (Hash[String | Regexp, coverage_thresholds]) 


65
66
67
 
# File 'lib/simplecov/configuration/thresholds.rb', line 65

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]

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


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

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

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


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

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

#missed_per_file_replacement(counts) ⇒ String

Parameters:

  • counts (Numeric, missed_caps)

Returns:

  • (String) 


45
46
47
48
49
 
# File 'lib/simplecov/configuration/missed_caps.rb', line 45

def missed_per_file_replacement(counts)
  counts = {primary_coverage => counts} if counts.is_a?(Numeric)
  counts.map { |criterion, cap| "  coverage(#{criterion.inspect}) { maximum_missed #{cap}, per: :file }" }
    .join("\n")
end

#no_default_skips ⇒ Array[Filter[untyped]]

Order matters: call this before your own skip invocations.

Returns:



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

def no_default_skips
  clear_filters
end

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

Parameters:

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

Returns:

  • (String) 


86
87
88
89
90
 
# File 'lib/simplecov/configuration/formatting.rb', line 86

def nocov_token(nocov_token = nil)
  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_missed_caps(counts, setting) ⇒ missed_caps

Parameters:

  • counts (Numeric, missed_caps)
  • setting (String)

Returns:

  • (missed_caps) 


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

def normalized_missed_caps(counts, setting)
  counts = {primary_coverage => counts} if counts.is_a?(Numeric)
  counts.each_key { |criterion| raise_if_criterion_disabled(criterion) }
  counts.each_value { |cap| raise_on_invalid_missed_cap(cap, setting) }
  _ = counts
end

#normalized_threshold(coverage, setting) ⇒ coverage_thresholds

A bare Numeric targets the primary criterion, and the resulting per-criterion hash is validated before it is stored.

Parameters:

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

Returns:

  • (coverage_thresholds) 


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

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

#parallel_tests(value = :__no_arg__) ⇒ Boolean?

Whether SimpleCov should auto-require the parallel_tests gem when it sees TEST_ENV_NUMBER / PARALLEL_TEST_GROUPS in the environment. Defaults to auto-detect (nil). See #1018.

Parameters:

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

Returns:

  • (Boolean, nil) 


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

def parallel_tests(value = :__no_arg__)
  return @parallel_tests if value.eql?(:__no_arg__)

  self.parallel_tests = _ = value
end

#parallel_tests=(value) ⇒ Object

Parameters:

  • value (Object)

Returns:

  • (Object) 


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

def parallel_tests=(value)
  @parallel_tests = value
end

#parallel_wait_timeout(seconds = nil) ⇒ Integer

How long (in seconds) the reporting process waits for the remaining parallel-test workers to write their resultsets before it proceeds with a partial merge. Default is 60 seconds. Raise it when a slow worker routinely finishes well after the others, so its coverage is still included and the threshold checks aren't skipped against a partial total.

Parameters:

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

Returns:

  • (Integer) 


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

def parallel_wait_timeout(seconds = nil)
  self.parallel_wait_timeout = seconds
  @parallel_wait_timeout ||= 60
end

#parallel_wait_timeout=(seconds) ⇒ Object

Anything but an Integer is ignored, the way the dual method always did.

Parameters:

  • seconds (Object)

Returns:

  • (Object) 


149
150
151
 
# File 'lib/simplecov/configuration/merging.rb', line 149

def parallel_wait_timeout=(seconds)
  @parallel_wait_timeout = seconds if seconds.instance_of?(Integer)
end

#parallel_worker_environment? ⇒ Boolean

Returns:

  • (Boolean) 


167
168
169
 
# File 'lib/simplecov/configuration/merging.rb', line 167

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.

Parameters:

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

Raises:

  • (ArgumentError) 


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

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

  Filter.build_filter(filter)
end

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

Splits into Symbol-keyed criterion defaults and String/Regexp-keyed per-path overrides, normalizing Numeric override values to {primary_coverage => N} so downstream code has one shape to handle.

Parameters:

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

Returns:

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


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

def partition_per_file_thresholds(coverage)
  coverage.each_key { |key| validate_per_file_key(key) }
  # The assertions restate what the partition predicate guarantees: Symbol
  # keys carry per-criterion Numeric defaults, the rest are paths.
  symbol_pairs, path_pairs = coverage.partition { |key, _| key.instance_of?(Symbol) }
  defaults = symbol_pairs.to_h #: coverage_thresholds
  raw = path_pairs.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

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


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

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

#per_group_coverage_replacement(coverage) ⇒ String

Parameters:

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

Returns:

  • (String) 


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

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 #{percent}, per: group(#{group_name.inspect})"
    end
  end
  render_coverage_blocks(by_criterion)
end

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

Parameters:

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

Returns:

  • (criterion, :oneshot_line) 


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

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

#primary_coverage=(criterion) ⇒ criterion, :oneshot_line

Parameters:

  • criterion (criterion, :oneshot_line)

Returns:

  • (criterion, :oneshot_line) 


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

def primary_coverage=(criterion)
  raise_if_criterion_disabled(criterion)
  @primary_coverage = criterion
end

#print_errors(value = :__no_arg__) ⇒ Boolean

Parameters:

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

Returns:

  • (Boolean) 


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

def print_errors(value = :__no_arg__)
  return instance_variable_defined?(:@print_error_status) ? @print_error_status : true if value.eql?(:__no_arg__)

  self.print_errors = _ = value
end

#print_errors=(value) ⇒ Boolean

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


66
67
68
 
# File 'lib/simplecov/configuration/formatting.rb', line 66

def print_errors=(value)
  @print_error_status = value
end

#production_coverage(path = nil) ⇒ String?

The path to a production coverage store, the file a SimpleCov::Production sink wrote. Relative paths resolve against SimpleCov.root. The store is read at report time, and an unreadable or invalid file warns and leaves the section out, because a missing night's data should not fail the suite that measured the tests.

Parameters:

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

Returns:

  • (String, nil) 


10
11
12
13
14
15
 
# File 'lib/simplecov/configuration/production.rb', line 10

def production_coverage(path = nil)
  return @production_coverage if path.nil?

  self.production_coverage = path
  @production_coverage
end

#production_coverage=(path) ⇒ String

Parameters:

  • path (String)

Returns:

  • (String)

Raises:



17
18
19
20
21
 
# File 'lib/simplecov/configuration/production.rb', line 17

def production_coverage=(path)
  raise ConfigurationError, "production_coverage takes a path, got #{path.inspect}" unless path.is_a?(String)

  @production_coverage = File.expand_path(path, root)
end

#profiles ⇒ Profiles

Returns:



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

def profiles
  @profiles ||= Profiles.new
end

#project_name(new_name = nil) ⇒ String

Only a String renames, and a name already chosen survives anything else.

Parameters:

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

Returns:

  • (String) 


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

def project_name(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:



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

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

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

Parameters:

  • criterion (Symbol)

Raises:



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

def raise_if_criterion_disabled(criterion)
  if criterion.equal?(:eval)
    raise 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 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:



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

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

  raise 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:



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

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

  raise 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, Symbol) 


11
12
13
14
15
16
 
# File 'lib/simplecov/configuration/thresholds.rb', line 11

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

#raise_on_invalid_missed_cap(cap, setting) ⇒ void

This method returns an undefined value.

Parameters:

  • cap (Object)
  • setting (String, Symbol)

Raises:



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

def raise_on_invalid_missed_cap(cap, setting)
  return if cap.instance_of?(Integer) && cap >= 0

  raise ConfigurationError,
    "#{setting} takes a non-negative integer count of misses, got #{cap.inspect}"
end

#refuse_coverage_drop(*criteria) ⇒ coverage_thresholds

Parameters:

  • criteria (criterion, :oneshot_line)

Returns:

  • (coverage_thresholds) 


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

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

reject! answers nil when it rejected nothing, which is the whole of "was anything removed".

Parameters:

  • filter_argument (Object)

Returns:

  • (Boolean) 


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

def remove_filter(filter_argument)
  rejected = filters.reject! do |filter|
    filter.respond_to?(:filter_argument) && filter.filter_argument.eql?(filter_argument)
  end
  !rejected.nil?
end

#render_coverage_blocks(by_criterion) ⇒ String

Parameters:

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

Returns:

  • (String) 


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

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

#require_html_formatter(name) ⇒ void

This method returns an undefined value.

formats :html has to work in a process that never required the HTML formatter, which under SIMPLECOV_NO_DEFAULTS nothing else has.

Parameters:

  • name (Object) 


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

def require_html_formatter(name)
  path = LAZY_FORMAT_REQUIRES[name]
  require_relative(path) if path
end

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

Parameters:

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

Returns:

  • (criterion, :oneshot_line, :eval)

Raises:



40
41
42
43
44
45
46
 
# File 'lib/simplecov/configuration/coverage.rb', line 40

def resolve_criterion_variant(criterion, oneshot)
  return criterion unless oneshot

  raise ConfigurationError, "`oneshot: true` is only valid for `coverage :line`" unless criterion.equal?(:line)

  ONESHOT_LINE_COVERAGE_CRITERION
end

#resolve_format(name) ⇒ Object

Parameters:

  • name (Object)

Returns:

  • (Object) 


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

def resolve_format(name)
  return name unless name.instance_of?(Symbol)

  constant = BUILT_IN_FORMATS[name]
  unless constant
    raise ConfigurationError,
      "Unknown format #{name.inspect}. Built-in formats are :html, :json, :simple, and :baseline; " \
      "pass a formatter class or instance for anything else."
  end

  require_html_formatter(name)
  Formatter.const_get(constant)
end

#root(root = nil) ⇒ String

Parameters:

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

Returns:

  • (String) 


7
8
9
10
11
12
 
# File 'lib/simplecov/configuration.rb', line 7

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

  self.root = root
  @root
end

#root=(root) ⇒ String

nil means the working directory, the default the reader would have derived.

Parameters:

  • root (String, nil)

Returns:

  • (String) 


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

def root=(root)
  @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. Accepts a String (path-segment substring), Regexp, block predicate, or Array of any of those.

Parameters:

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


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

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

#source_in_json(value = :__no_arg__) ⇒ Boolean

Parameters:

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

Returns:

  • (Boolean) 


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

def source_in_json(value = :__no_arg__)
  return instance_variable_defined?(:@source_in_json) ? @source_in_json : true if value.eql?(:__no_arg__)

  self.source_in_json = _ = value
end

#source_in_json=(value) ⇒ Boolean

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


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

def source_in_json=(value)
  @source_in_json = value
end

#store_ignored_branches(types) ⇒ Array[Symbol]

Variadic semantics: multiple calls union, duplicates are no-ops, unknown tokens raise.

Parameters:

  • types (Array[Symbol])

Returns:

  • (Array[Symbol]) 


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

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

#store_ignored_methods(types) ⇒ Array[Symbol]

Parameters:

  • types (Array[Symbol])

Returns:

  • (Array[Symbol]) 


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

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

#store_maximum_missed_per_file(criterion, count, target) ⇒ void

This method returns an undefined value.

Parameters:

  • criterion (Symbol)
  • count (Integer)
  • target (String, Regexp, nil) 


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

def store_maximum_missed_per_file(criterion, count, target)
  raise_if_criterion_disabled(criterion)
  raise_on_invalid_missed_cap(count, "maximum_missed_per_file")
  return maximum_missed_per_file[criterion] = count if target.nil?

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

  (maximum_missed_per_file_overrides[target] ||= {})[criterion] = count
end

#store_minimum_per_file(criterion, percent, target) ⇒ void

This method returns an undefined value.

Parameters:

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


72
73
74
75
76
77
78
79
80
81
 
# File 'lib/simplecov/configuration/coverage.rb', line 72

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


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

def store_minimum_per_group(criterion, percent, group_name)
  raise_on_invalid_coverage({criterion => percent}, "minimum_coverage_by_group")
  # Normalized like `group` does, so `per: group(:Models)` finds the group
  # defined as `group "Models"` at check time.
  (minimum_coverage_by_group[GroupNames.normalize(group_name)] ||= {})[criterion] = percent
end

#store_missed_cap(setting, criterion, count) ⇒ void

This method returns an undefined value.

Parameters:

  • setting (Symbol)
  • criterion (Symbol)
  • count (Integer) 


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

def store_missed_cap(setting, criterion, count)
  raise_if_criterion_disabled(criterion)
  raise_on_invalid_missed_cap(count, setting)
  public_send(setting)[criterion] = count
end

#store_overall_threshold(setting, criterion, percent) ⇒ void

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.

This method returns an undefined value.

Parameters:

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


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

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

#track_files(glob) ⇒ String?

Parameters:

  • glob (String, nil)

Returns:

  • (String, nil) 


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

def track_files(glob)
  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.

Parameters:

  • glob (String, nil)

Returns:

  • (String) 


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

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

#track_tests(enabled = nil, granularity: nil) ⇒ Boolean

Enables recording of which test covered which line. Off by default: sampling coverage around every test costs run time, and the recorded map costs space in .resultset.json. RSpec examples and Minitest tests are wrapped automatically; other runners wrap their own units of work with SimpleCov.track_test. A bare track_tests enables, and only an explicit track_tests false turns it back off.

granularity decides what one recorded context stands for: a test (:test, the default) or a whole test file (:file). File granularity is the batching lever for suites where per-test sampling costs too much.

Parameters:

  • enabled (Boolean, nil) (defaults to: nil)
  • granularity: (Symbol, nil) (defaults to: nil)

Returns:

  • (Boolean) 


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

def track_tests(enabled = nil, granularity: nil)
  if granularity && !TRACK_TESTS_GRANULARITIES.include?(granularity)
    raise ConfigurationError,
      "Unsupported track_tests granularity #{granularity.inspect}, " \
      "supported values are #{TRACK_TESTS_GRANULARITIES.inspect}"
  end

  @track_tests_granularity = granularity if granularity
  @track_tests = enabled.nil? || enabled
end

#track_tests? ⇒ Boolean

Returns:

  • (Boolean) 


28
29
30
 
# File 'lib/simplecov/configuration/test_tracking.rb', line 28

def track_tests?
  !!@track_tests
end

#track_tests_granularity ⇒ Symbol

Returns:

  • (Symbol) 


32
33
34
 
# File 'lib/simplecov/configuration/test_tracking.rb', line 32

def track_tests_granularity
  @track_tests_granularity || :test
end

#tracked_files ⇒ String?

Nil until cover names a glob: an unset ivar reads as nil, so the absence needs no guard of its own.

Returns:

  • (String, nil) 


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

def tracked_files
  @tracked_files
end

#use_merging(use = nil) ⇒ Boolean

Parameters:

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

Returns:

  • (Boolean) 


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

def use_merging(use = nil)
  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.

Raises:



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

def validate_coverage_criteria!
  return unless coverage_criteria.empty?

  raise 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:



107
108
109
110
111
112
113
 
# File 'lib/simplecov/configuration/thresholds.rb', line 107

def validate_per_file_key(key)
  # Symbols have no subclasses; paths and patterns may.
  return if key.instance_of?(Symbol) || key.is_a?(String) || key.is_a?(Regexp)

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

#validate_test_tracking! ⇒ void

This method returns an undefined value.

:oneshot_line does not produce: a line reports only its first hit ever, so every test after the first would show no delta.

Raises:



39
40
41
42
43
44
45
46
 
# File 'lib/simplecov/configuration/test_tracking.rb', line 39

def validate_test_tracking!
  return unless track_tests?
  return if coverage_criterion_enabled?(DEFAULT_COVERAGE_CRITERION)

  raise ConfigurationError,
    "`track_tests` needs line coverage with execution counts. " \
    "Enable it with `enable_coverage :line` (`:oneshot_line` cannot record per-test data)."
end

#view_coverage? ⇒ Boolean

False when eval coverage couldn't be enabled, where cover_views has already warned and the templates would come back empty rather than at 0%.

Returns:

  • (Boolean) 


33
34
35
 
# File 'lib/simplecov/configuration/view_coverage.rb', line 33

def view_coverage?
  !view_globs.nil? && coverage_for_eval_enabled?
end

#view_globs ⇒ Array[String]?

Nil rather than an empty Array when cover_views was never called, so "not asked for" stays distinguishable from "asked for, with nothing to match".

Returns:

  • (Array[String], nil) 


27
28
29
 
# File 'lib/simplecov/configuration/view_coverage.rb', line 27

def view_globs
  @view_globs
end

#warn_about_inferred_finalize_merge ⇒ void

This method returns an undefined value.



181
182
183
184
185
186
187
 
# File 'lib/simplecov/configuration/merging.rb', line 181

def warn_about_inferred_finalize_merge
  return if @finalize_merge_inference_warned
  return unless print_errors

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