coverage

Undercover Coverage Feedback

Routing

The user may have stated an intent after the command (shown below as $ARGUMENTS). Use it to decide what to do, then read the matching reference file before acting:

• Set up coverage in a Ruby project (SimpleCov, Gemfile, .undercover, permissions) → read references/setup.md
• Set up CI (UndercoverCI or GitHub Actions; also CircleCI and parallel test merging) → read references/ci.md
• Read/address UndercoverCI feedback on a PR → read references/pr-feedback.md
• Skip coverage for a file (:nocov:, add_filter, --exclude-files) → read references/skipping.md
• Run the feedback loop after tests, or anything else → use the loop below (the default)

Stated intent: $ARGUMENTS

If no intent was given, default to the feedback loop.

Coverage Feedback Loop

After every test run, run undercover to check for coverage gaps.

Only use --include-files when you ran a partial test suite. Full suite → no flag.

Full test suite:

bundle exec undercover --format json

Partial test run (single file or subset — undercover must match scope):

bundle exec undercover --format json --include-files "app/models/foo.rb"
bundle exec undercover --format json --include-files "app/models/*.rb,app/services/foo*.rb"

--include-files accepts comma-separated glob patterns. When running a subset of tests, SimpleCov only has coverage data for loaded files. Without --include-files, undercover will falsely flag all other changed files as uncovered.

Workflow:

1. Run tests
2. Run bundle exec undercover --format json (scoped with --include-files if partial)
3. If gaps found: write tests for uncovered code. Prefer real tests over :nocov: — only use :nocov: when the code genuinely cannot or should not be tested (see references/skipping.md). Only delete code if you are certain it is dead/unreachable — understand why it's uncovered before removing it
4. Repeat until undercover exits 0

JSON output format