Module: SimpleCov::RSpec::ListUncoveredFilesOption Private

Defined in:
lib/simplecov-rspec/list_uncovered_files_option.rb

Overview

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

Resolves the list_uncovered_files: option (plus its LIST_UNCOVERED_FILES ENV override) into a normalized Array of absolute paths, or nil for "every file".

The option may be given as a callable so that it can be evaluated after the test run rather than when SimpleCov::RSpec.start is called. start runs before any example is defined, so a caller that wants to scope the report to the code under test cannot know which files those are yet.

Constant Summary collapse

ALL_ENV_VALUES =

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

LIST_UNCOVERED_FILES environment variable values that mean "every file"

%w[all false no off 0].freeze
DESCRIBED =

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

The value that means "the files defining the classes this run described"

Sugar over passing a callable that does the same thing: the scope is only knowable after the run, so it resolves to one.

See Also:

:described

Class Method Summary collapse

Class Method Details

.expand(patterns, root) ⇒ Array<String>

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.

Expand patterns to absolute paths, resolving relative patterns against root

Each pattern is expanded with Dir.glob. A pattern that matches nothing on disk expands to itself, so the literal pattern is kept rather than dropped. No file in the coverage result can carry that path, so it adds nothing to the listing; it is kept because the report tests these paths against the file system to tell a pattern that matched nothing from one whose files SimpleCov never tracked.

Examples:

ListUncoveredFilesOption.expand(['lib/*.rb'], '/p') # => ['/p/lib/a.rb', '/p/lib/b.rb']

Parameters:

  • patterns (Array<String>) —

    the patterns to expand

  • root (String) —

    the directory that relative patterns are resolved against

Returns:

  • (Array<String>) —

    absolute paths, without duplicates



121
122
123
124
125
126
127
 
# File 'lib/simplecov-rspec/list_uncovered_files_option.rb', line 121

def expand(patterns, root)
  patterns.flat_map do |pattern|
    absolute = File.absolute_path(pattern, root)
    matches = Dir.glob(absolute)
    matches.empty? ? [absolute] : matches
  end.uniq
end

.from_env(raw) ⇒ nil, ...

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.

Parse a raw LIST_UNCOVERED_FILES environment variable value

A value that lists no patterns at all — '', ' ', or separators alone such as ', ,' — means "every file". Dropping the empty entries can empty the list even though the value was not empty to start with, so the check is made after parsing as well as before it.

Examples:

ListUncoveredFilesOption.from_env('lib/a.rb,lib/b.rb') # => ['lib/a.rb', 'lib/b.rb']

Parameters:

  • raw (String) —

    the raw LIST_UNCOVERED_FILES environment variable value

Returns:

  • (nil, Symbol, Array<String>) —

    nil for "every file", DESCRIBED, or the listed patterns



64
65
66
67
68
69
70
71
 
# File 'lib/simplecov-rspec/list_uncovered_files_option.rb', line 64

def from_env(raw)
  stripped = raw.strip
  return nil if stripped.empty? || ALL_ENV_VALUES.include?(stripped.downcase)
  return DESCRIBED if stripped.casecmp?(DESCRIBED.to_s)

  patterns = stripped.split(',').map(&:strip).reject(&:empty?)
  patterns.empty? ? nil : patterns
end

.normalize(value) ⇒ Array<String>

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.

Normalize a list_uncovered_files:-style value into an Array of Strings

Examples:

ListUncoveredFilesOption.normalize('lib/a.rb') # => ['lib/a.rb']

Parameters:

  • value (String, Array<String>) —

    the pattern or patterns

Returns:

  • (Array<String>)

Raises:

  • (ArgumentError) —

    if value is not a String or an Array of Strings



81
82
83
84
85
86
87
88
89
90
 
# File 'lib/simplecov-rspec/list_uncovered_files_option.rb', line 81

def normalize(value)
  case value
  when String then [value]
  when Array then validate(value)
  else
    raise ArgumentError,
          'list_uncovered_files must be nil, :described, a String, an Array of Strings, or a callable ' \
          "returning one of those; got #{value.inspect}"
  end
end

.resolve(value, env:, env_var:, root:) ⇒ Array<String>?

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.

Resolve the effective file list, applying the ENV override if present

Examples:

ListUncoveredFilesOption.resolve('lib/a.rb', env: {}, env_var: 'X', root: '/p') # => ['/p/lib/a.rb']

Parameters:

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

    the list_uncovered_files: argument

  • env (Hash) —

    the environment variables

  • env_var (String) —

    the ENV var name that overrides value

  • root (String) —

    the directory that relative patterns are resolved against

Returns:

  • (Array<String>, nil) —

    absolute paths, or nil to report on every file

Raises:

  • (ArgumentError) —

    if value is not one of the accepted forms



43
44
45
46
47
48
49
50
 
# File 'lib/simplecov-rspec/list_uncovered_files_option.rb', line 43

def resolve(value, env:, env_var:, root:)
  value = from_env(env.fetch(env_var)) if env.key?(env_var)
  value = -> { ::SimpleCov::RSpec.described_source_files } if value == DESCRIBED
  value = value.call if value.respond_to?(:call)
  return nil if value.nil?

  expand(normalize(value), root)
end

.validate(patterns) ⇒ Array<String>

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.

Raise unless every element of patterns is a String

Examples:

ListUncoveredFilesOption.validate(['lib/a.rb']) # => ['lib/a.rb']

Parameters:

  • patterns (Array<String>)

Returns:

  • (Array<String>)

Raises:

  • (ArgumentError) —

    if patterns contains a non-String



100
101
102
103
104
105
 
# File 'lib/simplecov-rspec/list_uncovered_files_option.rb', line 100

def validate(patterns)
  invalid = patterns.grep_v(String)
  return patterns if invalid.empty?

  raise ArgumentError, "list_uncovered_files entries must be Strings; got #{invalid.inspect}"
end