Module: SimpleCov

Extended by:
Configuration
Defined in:
lib/simplecov.rb,
lib/simplecov/filter.rb,
lib/simplecov/result.rb,
lib/simplecov/combine.rb,
lib/simplecov/version.rb,
lib/simplecov/last_run.rb,
lib/simplecov/profiles.rb,
lib/simplecov/file_list.rb,
lib/simplecov/formatter.rb,
lib/simplecov/exit_codes.rb,
lib/simplecov/source_file.rb,
lib/simplecov/configuration.rb,
lib/simplecov/result_merger.rb,
lib/simplecov/result_adapter.rb,
lib/simplecov/command_guesser.rb,
lib/simplecov/lines_classifier.rb,
lib/simplecov/source_file/line.rb,
lib/simplecov/simulate_coverage.rb,
lib/simplecov/source_file/branch.rb,
lib/simplecov/coverage_statistics.rb,
lib/simplecov/combine/files_combiner.rb,
lib/simplecov/combine/lines_combiner.rb,
lib/simplecov/useless_results_remover.rb,
lib/simplecov/combine/results_combiner.rb,
lib/simplecov/combine/branches_combiner.rb,
lib/simplecov/formatter/multi_formatter.rb,
lib/simplecov/formatter/simple_formatter.rb

Overview

Code coverage for ruby. Please check out README for a full introduction.

Defined Under Namespace

Modules: Combine, CommandGuesser, Configuration, ExitCodes, Formatter, LastRun, ResultMerger, SimulateCoverage, UselessResultsRemover Classes: ArrayFilter, BlockFilter, CoverageStatistics, FileList, Filter, LinesClassifier, Profiles, RegexFilter, Result, ResultAdapter, SourceFile, StringFilter

Constant Summary collapse

VERSION = 
"0.18.5"

Constants included from Configuration

Configuration::DEFAULT_COVERAGE_CRITERION, Configuration::SUPPORTED_COVERAGE_CRITERIA

Class Attribute Summary collapse

Attributes included from Configuration

#filters, #formatter, #groups, #print_error_status

Class Method Summary collapse

Methods included from Configuration

adapters, add_filter, add_group, at_exit, branch_coverage?, clear_coverage_criteria, command_name, configure, coverage_criteria, coverage_criterion, coverage_criterion_enabled?, coverage_dir, coverage_path, coverage_start_arguments_supported?, enable_coverage, formatters, formatters=, maximum_coverage_drop, merge_timeout, minimum_coverage, minimum_coverage_by_file, nocov_token, profiles, project_name, refuse_coverage_drop, root, track_files, tracked_files, use_merging

Class Attribute Details

.exit_exception ⇒ Object (readonly)

Returns the value of attribute exit_exception.



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

def exit_exception
  @exit_exception
end

.external_at_exit ⇒ Object Also known as: external_at_exit?

Basically, should we take care of at_exit behavior or something else? Used by the minitest plugin. See lib/minitest/simplecov_plugin.rb



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

def external_at_exit
  @external_at_exit
end

.pid ⇒ Object

Returns the value of attribute pid.



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

def pid
  @pid
end

.running ⇒ Object

Returns the value of attribute running.



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

def running
  @running
end

Class Method Details

.at_exit_behavior ⇒ Object 



197
198
199
200
201
202
203
 
# File 'lib/simplecov.rb', line 197

def at_exit_behavior
  # If we are in a different process than called start, don't interfere.
  return if SimpleCov.pid != Process.pid

  # If SimpleCov is no longer running then don't run exit tasks
  SimpleCov.run_exit_tasks! if SimpleCov.running
end

.clear_result ⇒ Object

Clear out the previously cached .result. Primarily useful in testing



172
173
174
 
# File 'lib/simplecov.rb', line 172

def clear_result
  @result = nil
end

.collate(result_filenames, profile = nil, &block) ⇒ Object

Collate a series of SimpleCov result files into a single SimpleCov output. You can optionally specify configuration with a block:

SimpleCov.collate Dir["simplecov-resultset-*/.resultset.json"]
 OR
SimpleCov.collate Dir["simplecov-resultset-*/.resultset.json"], 'rails' # using rails profile
 OR
SimpleCov.collate Dir["simplecov-resultset-*/.resultset.json"] do
  add_filter 'test'
end
 OR
SimpleCov.collate Dir["simplecov-resultset-*/.resultset.json"], 'rails' do
  add_filter 'test'
end

Please check out the RDoc for SimpleCov::Configuration to find about available config options, or checkout the README for more in-depth information about coverage collation



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/simplecov.rb', line 80

def collate(result_filenames, profile = nil, &block)
  raise "There's no reports to be merged" if result_filenames.empty?

  initial_setup(profile, &block)

  results = result_filenames.flat_map do |filename|
    # Re-create each included instance of SimpleCov::Result from the stored run data.
    (JSON.parse(File.read(filename)) || {}).map do |command_name, coverage|
      SimpleCov::Result.from_hash(command_name => coverage)
    end
  end

  # Use the ResultMerger to produce a single, merged result, ready to use.
  @result = SimpleCov::ResultMerger.merge_and_store(*results)

  run_exit_tasks!
end

.exit_status_from_exception ⇒ Object

Returns the exit status from the exit exception



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

def exit_status_from_exception
  return SimpleCov::ExitCodes::SUCCESS unless exit_exception

  if exit_exception.is_a?(SystemExit)
    exit_exception.status
  else
    SimpleCov::ExitCodes::EXCEPTION
  end
end

.filtered(files) ⇒ Object

Applies the configured filters to the given array of SimpleCov::SourceFile items



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

def filtered(files)
  result = files.clone
  filters.each do |filter|
    result = result.reject { |source_file| filter.matches?(source_file) }
  end
  SimpleCov::FileList.new result
end

.final_result_process? ⇒ 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) 


279
280
281
282
 
# File 'lib/simplecov.rb', line 279

def final_result_process?
  # checking for ENV["TEST_ENV_NUMBER"] to determine if the tess are being run in parallel
  !defined?(ParallelTests) || !ENV["TEST_ENV_NUMBER"] || ParallelTests.number_of_running_processes <= 1
end

.grouped(files) ⇒ Object

Applies the configured groups to the given array of SimpleCov::SourceFile items



144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/simplecov.rb', line 144

def grouped(files)
  grouped = {}
  grouped_files = []
  groups.each do |name, filter|
    grouped[name] = SimpleCov::FileList.new(files.select { |source_file| filter.matches?(source_file) })
    grouped_files += grouped[name]
  end
  if !groups.empty? && !(other_files = files.reject { |source_file| grouped_files.include?(source_file) }).empty?
    grouped["Ungrouped"] = SimpleCov::FileList.new(other_files)
  end
  grouped
end

.load_adapter(name) ⇒ Object 



164
165
166
167
 
# File 'lib/simplecov.rb', line 164

def load_adapter(name)
  warn "#{Kernel.caller.first}: [DEPRECATION] #load_adapter is deprecated. Use #load_profile instead."
  load_profile(name)
end

.load_profile(name) ⇒ Object

Applies the profile of given name on SimpleCov configuration



160
161
162
 
# File 'lib/simplecov.rb', line 160

def load_profile(name)
  profiles.load(name)
end

.process_result(result, exit_status) ⇒ Object

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.

Usage:

exit_status = SimpleCov.process_result(SimpleCov.result, exit_status)



233
234
235
236
237
238
239
240
 
# File 'lib/simplecov.rb', line 233

def process_result(result, exit_status)
  return exit_status if exit_status != SimpleCov::ExitCodes::SUCCESS # Existing errors

  covered_percent = result.covered_percent.floor(2)
  result_exit_status = result_exit_status(result, covered_percent)
  write_last_run(covered_percent) if result_exit_status == SimpleCov::ExitCodes::SUCCESS # No result errors
  final_result_process? ? result_exit_status : SimpleCov::ExitCodes::SUCCESS
end

.result ⇒ Object

Returns the result for the current coverage run, merging it across test suites from cache using SimpleCov::ResultMerger if use_merging is activated (default)



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/simplecov.rb', line 102

def result
  return @result if result?

  # Collect our coverage result

  process_coverage_result if running

  # If we're using merging of results, store the current result
  # first (if there is one), then merge the results and return those
  if use_merging
    wait_for_other_processes
    SimpleCov::ResultMerger.store_result(@result) if result?
    @result = SimpleCov::ResultMerger.merged_result
  end

  @result
ensure
  self.running = false
end

.result? ⇒ Boolean

Returns nil if the result has not been computed Otherwise, returns the result

Returns:

  • (Boolean) 


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

def result?
  defined?(@result) && @result
end

.result_exit_status(result, covered_percent) ⇒ Object

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.

rubocop:disable Metrics/MethodLength



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/simplecov.rb', line 245

def result_exit_status(result, covered_percent)
  covered_percentages = result.covered_percentages.map { |percentage| percentage.floor(2) }
  if (minimum_violations = minimum_coverage_violated(result)).any?
    report_minimum_violated(minimum_violations)
    SimpleCov::ExitCodes::MINIMUM_COVERAGE
  elsif covered_percentages.any? { |p| p < SimpleCov.minimum_coverage_by_file }
    $stderr.printf(
      "File (%<file>s) is only (%<least_covered_percentage>.2f%%) covered. This is below the expected minimum coverage per file of (%<min_coverage>.2f%%).\n",
      file: result.least_covered_file,
      least_covered_percentage: covered_percentages.min,
      min_coverage: SimpleCov.minimum_coverage_by_file
    )
    SimpleCov::ExitCodes::MINIMUM_COVERAGE
  elsif (last_run = SimpleCov::LastRun.read)
    coverage_diff = last_run[:result][:covered_percent] - covered_percent
    if coverage_diff > SimpleCov.maximum_coverage_drop
      $stderr.printf(
        "Coverage has dropped by %<drop_percent>.2f%% since the last time (maximum allowed: %<max_drop>.2f%%).\n",
        drop_percent: coverage_diff,
        max_drop: SimpleCov.maximum_coverage_drop
      )
      SimpleCov::ExitCodes::MAXIMUM_COVERAGE_DROP
    else
      SimpleCov::ExitCodes::SUCCESS
    end
  else
    SimpleCov::ExitCodes::SUCCESS
  end
end

.run_exit_tasks! ⇒ Object

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.

Called from at_exit block



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/simplecov.rb', line 209

def run_exit_tasks!
  set_exit_exception

  exit_status = SimpleCov.exit_status_from_exception

  SimpleCov.at_exit.call

  # Don't modify the exit status unless the result has already been
  # computed
  exit_status = SimpleCov.process_result(SimpleCov.result, exit_status) if SimpleCov.result?

  # Force exit with stored status (see github issue #5)
  # unless it's nil or 0 (see github issue #281)
  if exit_status&.positive?
    $stderr.printf("SimpleCov failed with exit %<exit_status>d\n", exit_status: exit_status) if print_error_status
    Kernel.exit exit_status
  end
end

.set_exit_exception ⇒ Object

Capture the current exception if it exists This will get called inside the at_exit block



180
181
182
 
# File 'lib/simplecov.rb', line 180

def set_exit_exception
  @exit_exception = $ERROR_INFO
end

.start(profile = nil, &block) ⇒ Object

Sets up SimpleCov to run against your project. You can optionally specify a profile to use as well as configuration with a block:

SimpleCov.start
 OR
SimpleCov.start 'rails' # using rails profile
 OR
SimpleCov.start do
  add_filter 'test'
end
  OR
SimpleCov.start 'rails' do
  add_filter 'test'
end

Please check out the RDoc for SimpleCov::Configuration to find about available config options



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

def start(profile = nil, &block)
  require "coverage"
  initial_setup(profile, &block)
  @result = nil
  self.pid = Process.pid

  start_coverage_measurement
end

.wait_for_other_processes ⇒ Object

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. 



287
288
289
290
291
 
# File 'lib/simplecov.rb', line 287

def wait_for_other_processes
  return unless defined?(ParallelTests) && final_result_process?

  ParallelTests.wait_for_other_processes_to_finish
end

.write_last_run(covered_percent) ⇒ Object

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. 



296
297
298
 
# File 'lib/simplecov.rb', line 296

def write_last_run(covered_percent)
  SimpleCov::LastRun.write(result: {covered_percent: covered_percent})
end