Module: SimpleCov::CLI

Defined in:
lib/simplecov/cli.rb,
lib/simplecov/cli/run.rb,
lib/simplecov/cli/diff.rb,
lib/simplecov/cli/open.rb,
lib/simplecov/cli/clean.rb,
lib/simplecov/cli/merge.rb,
lib/simplecov/cli/serve.rb,
lib/simplecov/cli/report.rb,
lib/simplecov/cli/dotfile.rb,
lib/simplecov/cli/coverage.rb,
lib/simplecov/cli/uncovered.rb,
lib/simplecov/cli/coverage_file.rb,
lib/simplecov/cli/command_helpers.rb,
lib/simplecov/cli/serve/report_preparer.rb,
lib/simplecov/cli/serve/static_file_handler.rb

Overview

Lightweight command-line front-end. run dispatches a subcommand (coverage, report, uncovered, merge, diff, open, etc.) — see the usage text below for the full list, or run simplecov help.

Read-only subcommands consume JSONFormatter output (coverage.json), which the bundled HTMLFormatter already drops alongside the HTML, so no runtime hooking is needed for those. Default paths follow the project's .simplecov SimpleCov.coverage_dir setting when one is present, so a project that writes its report somewhere other than coverage/ doesn't have to pass --input / --report every invocation.

Defined Under Namespace

Modules: Clean, CommandHelpers, Coverage, CoverageFile, Diff, Dotfile, Merge, Open, Report, Run, Serve, Uncovered

Constant Summary collapse

COMMANDS = 
{
  "coverage" => Coverage,
  "run" => Run,
  "open" => Open,
  "report" => Report,
  "uncovered" => Uncovered,
  "merge" => Merge,
  "diff" => Diff,
  "serve" => Serve,
  "clean" => Clean
}.freeze

Class Method Summary collapse

Class Method Details

.color_enabled?(opts, stream) ⇒ Boolean

Resolve "should this subcommand colorize?" once per invocation. --no-color (opts) is the per-invocation kill-switch; otherwise we defer to SimpleCov::Color.enabled?, which honors NO_COLOR / FORCE_COLOR and falls back to stream.tty?.

Returns:

  • (Boolean) 


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

def color_enabled?(opts, stream)
  return false if opts[:no_color]

  SimpleCov::Color.enabled?(stream)
end

.coverage_dir ⇒ Object

Resolved once per process. Walks up from cwd looking for a .simplecov; if present, the file is loaded with SimpleCov.start neutered so it can't trigger coverage tracking or an at_exit hook just because we asked it for a config value.



48
49
50
 
# File 'lib/simplecov/cli.rb', line 48

def coverage_dir
  @coverage_dir ||= Dotfile.coverage_dir
end

.default_input ⇒ Object 



52
53
54
 
# File 'lib/simplecov/cli.rb', line 52

def default_input
  File.join(coverage_dir, "coverage.json")
end

.default_report ⇒ Object 



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

def default_report
  File.join(coverage_dir, "index.html")
end

.default_resultset ⇒ Object 



70
71
72
 
# File 'lib/simplecov/cli.rb', line 70

def default_resultset
  File.join(coverage_dir, ".resultset.json")
end

.dispatch(handler, command, rest, stdout:, stderr:) ⇒ Object

One rescue covers every subcommand's OptionParser, so a typo'd flag or a malformed typed argument becomes a one-line error and exit status 1 instead of an unhandled-exception backtrace.



88
89
90
91
92
93
 
# File 'lib/simplecov/cli.rb', line 88

def dispatch(handler, command, rest, stdout:, stderr:)
  handler.run(rest, stdout: stdout, stderr: stderr)
rescue OptionParser::ParseError => e
  stderr.puts("simplecov #{command}: #{e.message} (run `simplecov help` for usage)")
  1
end

.run(argv, stdout: $stdout, stderr: $stderr) ⇒ Object

Returns a process exit status (0 on success, non-zero on error).



75
76
77
78
79
80
81
82
83
 
# File 'lib/simplecov/cli.rb', line 75

def run(argv, stdout: $stdout, stderr: $stderr)
  command, *rest = argv
  handler = COMMANDS[command]
  return dispatch(handler, command, rest, stdout: stdout, stderr: stderr) if handler
  return stdout.puts(usage) || 0 if [nil, "help", "--help", "-h"].include?(command)

  stderr.puts("simplecov: unknown command #{command.inspect}", usage)
  1
end

.usage ⇒ Object 



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/simplecov/cli.rb', line 95

def usage
  <<~USAGE
    Usage: simplecov <command> [options]

    Commands:
      run <command...>          Execute <command> with simplecov pre-loaded
                                (so a coverage report is generated even
                                when the project has no test_helper hook)
      coverage <path>           Print coverage stats for the given file
      report                    Print the overall summary and group totals
      uncovered                 List the lowest-coverage files
      merge <files...>          Merge multiple .resultset.json files
      diff <baseline>           Show per-file coverage delta vs baseline
      open                      Open the HTML report in the default browser
      serve                     Serve the coverage report over HTTP
      clean                     Remove the coverage report directory
      help                      Show this message

    Default paths follow SimpleCov.coverage_dir from a project's
    `.simplecov` when one is present (#{coverage_dir} for this run).

    coverage / report / uncovered / diff options:
      --input PATH              Read from PATH instead of #{default_input}
      --no-color                Disable colorized percentages
                                (also honors NO_COLOR / FORCE_COLOR env)

    coverage options:
      --json                    Print the file's JSON entry verbatim

    report options:
      --json                    Emit totals and group sections as JSON

    uncovered options:
      --threshold N             Only show files below N% coverage
      --top N                   Show at most N files (default: 10)
      --criterion C             line, branch, or method (default: line)
      --json                    Emit results as a JSON array (for CI)

    merge options:
      --output PATH             Write merged resultset to PATH
                                (default: #{default_resultset})
      --honor-timeout           Drop entries older than merge_timeout
      --dry-run                 Print what would be written without
                                actually writing
      -q, --quiet               Suppress the success status line

    diff options:
      --fail-on-drop            Exit non-zero when any file's coverage
                                dropped vs the baseline (deleted
                                files don't count as drops)
      --json                    Emit results as a JSON array (for CI)
      --threshold N             Only show files whose absolute delta
                                in any criterion is at least N%

    open options:
      --report PATH             Open PATH instead of #{default_report}

    serve options:
      --port N                  Bind to port N (default: random open port)
      --host HOST               Bind to HOST (default: 127.0.0.1)

    clean options:
      --dry-run                 Print what would be removed without
                                deleting anything
      -q, --quiet               Suppress status lines
  USAGE
end