undercover

If you want to acknowledge an untested change without fixing it immediately, or if you want to skip certain blocks of code entirely, use the :nocov: syntax supported by SimpleCov.

Wrap the code you wish to ignore with # :nocov: and # :nocov::

# :nocov:
def skip_this_method
    never_reached
end
# :nocov:

You can install undercover by adding it to your application's Gemfile and running bundle, or by installing it directly via the command line.

To add to a Gemfile:

gem 'undercover'

Then run:

$ bundle

Or install it globally:

$ gem install undercover

The undercover CLI flags untested methods, classes, and blocks that were changed in the current git diff without corresponding tests.

• Run on current diff: Run undercover with no arguments to check changes in your current working directory.
• Run in CI/CD (Recommended): Use the --compare flag to specify a git ref (branch, commit, or tag) to compare against. This ensures undercover exits with code 1 if untested changes are found, which is ideal for build pipelines.

Example for CI:

undercover --compare origin/master

Undercover uses a FilterSet to determine which files should be included in coverage analysis. The filtering logic follows a specific hierarchy:

1. SimpleCov Filters: If a file is ignored by your existing SimpleCov configuration, Undercover will ignore it automatically. SimpleCov filters are supported in three formats:
   • :string: A substring match against the normalized filepath.
   • :regex: A regular expression match against the normalized filepath.
   • :file: An exact match against the filepath.
2. Undercover Allow Filters: The file must match at least one pattern in the allow_filters list.
3. Undercover Reject Filters: The file must NOT match any pattern in the reject_filters list.

For a file to be included, it must pass the SimpleCov check AND match an allow filter AND not match any reject filter.

You can create a .undercover configuration file at the root of your project to store CLI options. This avoids repeating flags in your CI configuration.

Example .undercover file:

-l path/to/different.lcov
-c origin/master

Note: Options in this file can be overridden by passing arguments directly to the undercover command.

To use undercover with custom tooling or CI integrations, use the --format json flag. The output contains a warnings array and a summary object.

Each warning includes details about the node (method/class), file location, coverage percentage, and specific uncovered_lines or uncovered_branches.

undercover --compare origin/main --format json

You can customize the name of the generated coverage JSON file by setting SimpleCov::Formatter::Undercover.output_filename. If this is not set, the gem defaults to coverage.json. The file will be saved within your configured SimpleCov.coverage_path.

SimpleCov::Formatter::Undercover.output_filename = 'my_project_coverage.json'

The ignored_files method returns a list of files that were excluded from the coverage report.

Returns:

• An Array of file paths extracted from the meta['ignored_files'] key in the SimpleCov JSON data. Returns an empty array [] if no ignored files are specified.

ignored = result_adapter.ignored_files

When using the Undercover::JsonFormatter, the exit_code method determines the process exit status based on the presence of validation errors and results:

• Returns 0 if a @validation_error is present.
• Returns 0 if there are no @results (no warnings found).
• Returns 1 if there are results and no validation error (indicating warnings were found that need attention).

To generate coverage reports compatible with Undercover, add SimpleCov::Formatter::Undercover to your SimpleCov.formatters configuration. This formatter extends the standard JSON formatter to include metadata such as the project root and ignored files (based on your SimpleCov filters).

require 'undercover'

SimpleCov.formatters = [
  SimpleCov::Formatter::Undercover
]