Uncov

Uncov analyzes test coverage for changed files in your Git repository, helping you ensure that all your recent changes are properly tested.

Uncov uses git diff to detect changes and simplecov reports to detect uncovered code.

The uncov Manifesto

Features

Compare your working tree to a target branch
Identify changed Ruby files
Run tests automatically for (changed) relevant files
Print report of uncovered lines in (changed) files
Print report of covered :nocov: lines in (changed) files
Extensible with gem plugins

Installation

gem install uncov

Or add to your Gemfile (only for convenience):

gem 'uncov', require: false

Usage

Basic usage:

uncov

Display configuration options

$ uncov -h
Usage: uncov [options]
    -t, --target TARGET              Target branch for comparison, default: "HEAD"
    -r, --report FILTER              Report filter to generate file/line list, one_of: "DiffFiles", "DiffLines"(default), "FileSystem", "GitFiles", "NocovLines", "Simplecov"
    -o, --output-format FORMAT       Output format, one_of: "Terminal"(default)
    -C, --context LINES_NUMBER       Additional lines context in output, default: 1
        --test-command COMMAND       Test command that generates SimpleCov, default: "COVERAGE=true bundle exec rake test"
        --simplecov-file PATH        SimpleCov results file, default: "autodetect"
        --relevant-files FN_GLOB     Only show uncov for matching code files AND trigger tests if matching code files are newer than the report, default: "{{bin,exe,exec}/*,{app,lib}/**/*.{rake,rb},Rakefile}"
        --relevant-tests FN_GLOB     Trigger tests if matching test files are newer than the report, default: "{test,spec}/**/*_{test,spec}.rb"
        --nocov-ignore               Ignore :nocov: markers - consider all lines, default: false
        --nocov-covered              Report :nocov: lines that have coverage, default: false
        --debug                      Get some insights, default: false
    -h, --help                       Print this help

Report FILTERs:
 DiffFiles - Report missing coverage on added/changed files in the git diff
 DiffLines - Report missing coverage on added lines in the git diff
FileSystem - Report missing coverage on file system
  GitFiles - Report missing coverage on files tracked with git
NocovLines - Report coverage on nocov lines, requires one or both: --nocov-ignore / --nocov-covered
 Simplecov - Report missing coverage on files tracked with simplecov

Report FILTERs take NOTICE:
git*/diff*  - filters will not consider new files unless added to the git index with `git add`.
nocov*      - filters/flags only work with coverage/.resultset.json SimpleCov files,
              coverage.json does not provide the information needed.

FN_GLOB: shell filename globing -> https://ruby-doc.org/core-3.1.1/File.html#method-c-fnmatch
         in bash: `shopt -s extglob dotglob globstar` and test with `ls {app,lib}/**/*.rb`

uncov 0.6.1 by Michal Papis <mpapis@gmail.com>

Configuration file

.uncov file in the directory where it's ran stores default options, specify one argument per line - this eliminates the need for special parsing of the file.

Example:

--target
develop
--test-command
COVERAGE=1 rspec

Plugins

Uncov uses pluginator to load plugins.

See lib/plugins/uncov for default plugins.

To create your own plugin, create a gem with a lib/plugins/uncov/... structure - same as uncov has, the plugins will be loaded automatically.

When you use uncov from a Gemfile then the new gam has to be added there too.

Using in CI

uncov uses itself to check new missing code coverage .github/workflows/ci.yml, no need to set minimal, always get better.

Ideas for CI:

run uncov after running your tests with coverage enabled,
be less restrictive - provide custom --relevant-files pattern that excludes some paths you do not think should be always tested.

Requirements

Ruby 3.2+
A Git repository
SimpleCov for test coverage

Contributing

Contributing, developing, pull requests, releasing, security -> CONTRIBUTING.md.

License

The gem is available as open source under the terms of the MIT License.

uncov

Runtime