{"id":13879214,"url":"https://github.com/grodowski/undercover","last_synced_at":"2026-02-06T11:22:36.601Z","repository":{"id":32416540,"uuid":"132804934","full_name":"grodowski/undercover","owner":"grodowski","description":"undercover warns about methods, classes and blocks that were changed without tests, to help you easily find untested code and reduce the number of bugs. It does so by analysing data from git diffs, code structure and SimpleCov coverage reports","archived":false,"fork":false,"pushed_at":"2025-05-07T13:59:40.000Z","size":3038,"stargazers_count":739,"open_issues_count":9,"forks_count":27,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-07T14:51:43.337Z","etag":null,"topics":["cli","code-quality","coverage","hacktoberfest","linter","ruby","test-coverage"],"latest_commit_sha":null,"homepage":"https://undercover-ci.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grodowski.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-05-09T19:41:56.000Z","updated_at":"2025-05-01T15:10:27.000Z","dependencies_parsed_at":"2024-11-24T08:31:12.521Z","dependency_job_id":"db3fbe46-365a-4b98-83d2-d3c75a826cf2","html_url":"https://github.com/grodowski/undercover","commit_stats":{"total_commits":228,"total_committers":16,"mean_commits":14.25,"dds":"0.26315789473684215","last_synced_commit":"e2ed94f75be00529081484baa30321762a59de01"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grodowski%2Fundercover","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grodowski%2Fundercover/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grodowski%2Fundercover/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grodowski%2Fundercover/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grodowski","download_url":"https://codeload.github.com/grodowski/undercover/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000885,"owners_count":21997443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","code-quality","coverage","hacktoberfest","linter","ruby","test-coverage"],"created_at":"2024-08-06T08:02:13.649Z","updated_at":"2026-02-06T11:22:36.592Z","avatar_url":"https://github.com/grodowski.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"![logo](https://github.com/grodowski/undercover/assets/4991698/c4bf038b-4472-4406-8f1f-5ddc812908d6)\n\n`undercover` warns about methods, classes and blocks that **were changed without tests**, to help you easily find untested code and reduce the number of bugs. It does so by analysing data from git diffs, code structure and SimpleCov coverage reports.\n\nWorks with any Ruby CI pipeline as well as locally as a CLI.\n\n- Visit **[https://undercover-ci.com](https://undercover-ci.com)** to set up code review checks with the GitHub App, or use one of the [CI integrations](#code-review-integrations)\n- Learn how to find untested code changes locally with the [CLI](#usage)\n\n\n[![Build Status](https://github.com/grodowski/undercover/actions/workflows/ruby.yml/badge.svg)](https://github.com/grodowski/undercover/actions)\n![Downloads](https://img.shields.io/gem/dt/undercover)\n\nA sample output of `undercover` ran before a commit may look like this:\n\n![screenshot warning](docs/screenshot_warnings.png)\n\nAnd like this, given that specs were added:\n\n![screenshot success](docs/screenshot_success.png)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'undercover'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install undercover\n\n## Setting up coverage reporting\n\nTo make your specs or tests compatible with `undercover`, please add `undercover` to your gemfile to use the undercover formatter the test helper.\n\n```ruby\n# Gemfile\ngroup :test do\n  gem 'undercover'\nend\n\n# the very top of spec_helper.rb\nrequire 'simplecov'\nrequire 'undercover/simplecov_formatter'\n\n# optional, the filename defaults to `coverage.json` and is automatically recognised by the gem\n# SimpleCov::Formatter::Undercover.output_filename = 'my_project_coverage.json'\nSimpleCov.formatter = SimpleCov::Formatter::Undercover\n\nSimpleCov.start do\n  add_filter(/^\\/spec\\//) # For RSpec\n  add_filter(/^\\/test\\//) # For Minitest\n  enable_coverage(:branch) # Report branch coverage to trigger branch-level undercover warnings\nend\n# ...\n```\n\nThen run your test suite once through to generate the initial coverage file before you can run the `undercover` command.\n\n## Upgrading from pre-0.7.0\n\nIf you're upgrading from an older version of undercover that used LCOV, you can migrate to the new SimpleCov formatter:\n\n1. Add `gem 'undercover'` to your test group\n2. Replace the LCOV formatter setup with the new SimpleCov formatter\n\n```ruby\n# Gemfile\ngroup :test do\n  gem 'undercover'\nend\n\n# spec_helper.rb\nrequire 'simplecov'\nrequire 'undercover/simplecov_formatter'\nSimpleCov.formatter = SimpleCov::Formatter::Undercover\n```\n\n3. Update CLI usage: Use `--simplecov` flag instead of `--lcov`, or rely on auto-detection of `coverage/coverage.json`\n\nNote: LCOV support will be deprecated in a future release, but remains fully functional for existing projects.\n\n## Usage\n\nInvoked with no arguments, Undercover will flag all untested methods and classes from the current diff:\n\n```sh\nundercover\n```\n\nUse the `-c --compare ref` flag to specify a git ref (commit hash, branch name, tag) to compare against. **This is a recommended usage for CI/CD build environments**, as `undercover` will `exit 1` if there are any warnings.\n\n```sh\nundercover --compare origin/master\n```\n\nCheck out `docs/` for CI configuration examples:\n- [GitHub Actions](docs/actions.yml)\n- [CircleCI - simple](docs/circleci_config.yml)\n- [CircleCI - advanced](docs/circleci_advanced.yml)\n- [Semaphore](docs/semaphore.yml)\n\nMerging coverage results ([sample gist](https://gist.github.com/grodowski/9744ff91034dce8df20c2a8210409fb0)) is required for parallel tests before processing with `undercover`.\n\n## Code review integrations\n\nA few options exist to provide automated comments from `undercover` in Pull Request reviews, which is the most streamlined way to add Undercover to your development workflow.\n\n- [UndercoverCI](https://undercover-ci.com) - `undercover` Pull Request feedback delivered natively with GitHub Checks\n- [pronto-undercover](https://github.com/grodowski/pronto-undercover)\n- [danger-undercover](https://github.com/nimblehq/danger-undercover)\n- [undercover-checkstyle](https://github.com/aki77/undercover-checkstyle)\n\n## Configuration\n\n### CLI Options\n\nOptions can be passed when running the command from the command line:\n\n```sh\nUsage: undercover [options]\n    -s, --simplecov path             SimpleCov JSON report file\n    -l, --lcov path                  LCOV report file path (to be deprecated)\n    -p, --path path                  Project directory\n    -g, --git-dir dir                Override `.git` with a custom directory\n    -c, --compare ref                Generate coverage warnings for all changes after `ref`\n    -r, --ruby-syntax ver            Ruby syntax version, one of: current, ruby18, ruby19, ruby20, ruby21, ruby22, ruby23, ruby24, ruby25, ruby26, ruby30, ruby31, ruby32, ruby33\n    -w, --max-warnings limit         Maximum number of warnings to generate before stopping analysis. Useful as a performance improvement for large diffs.\n    -f, --include-files globs        Include files matching specified glob patterns (comma separated). Defaults to '*.rb,*.rake,*.ru,Rakefile'\n    -x, --exclude-files globs        Skip files matching specified glob patterns (comma separated). Empty by default.\n    -h, --help                       Prints this help\n        --version                    Show version\n```\n\n### Configuration File\n\nA configuration file named `.undercover` can be created at the top level of a project's directory containing the same set of options for the CLI.\nExample file:\n\n```sh\n-l path/to/different.lcov\n-c origin/master\n```\n\nThe options set in the file can be overriden by passing arguments when invoking the executable.\n\nOptions assume that the program is run from the top level of the project directory.\n\n### Ignoring/skipping coverage\n\nProjects with low or nonexistent test coverage are likely to generate large numbers of warnings. While the default workflow would be to address them before the PR approval, your strategy might be different.\n\nIn order to acknowledge an untested change and remove the UndercoverCI warning with the intention to improve later (or never), you can wrap the code block with the `:nocov:` syntax, e.g.\n\n```rb\n# :nocov:\ndef skip_this_method\n    never_reached\nend\n# :nocov:\n```\n\nRead more about the `:nocov:` syntax in [SimpleCov's readme](https://github.com/simplecov-ruby/simplecov#ignoringskipping-code).\n\n## Why?\n\nI wanted to create a tool to help others and myself ensure that tests are written for all the recent code changes. This should be useful for any ruby project, but especially those large or legacy codebases that lack testing (and we can't or don't want to invest in full test coverage).\n\nThe goal was to provide automated warnings, that are:\n- relevant, so scoped to the actual code changes\n- timely, so we don't end up writing tests long after the implementation\n- actionable, so we can fix them before the code is committed or reaches production\n\nFor more background, please [read the blog post](https://medium.com/futuredev/stop-shipping-untested-ruby-code-with-undercover-1edc963be4a6).\n\n## Development\n\nAfter checking out the repo, run `bundle` to install dependencies. Then, run `rake` to run the tests and RuboCop. You can also run `pry -r 'undercover'` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/grodowski/undercover.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrodowski%2Fundercover","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrodowski%2Fundercover","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrodowski%2Fundercover/lists"}