Coverage Reporter

Report code coverage from SimpleCov coverage reports to a GitHub pull request. This tool analyzes your test coverage data and posts detailed comments on pull requests, highlighting uncovered lines in modified code.

• Installation
• Quick Start
• Configuration
• Usage Examples
• CI/CD Integration
• Command Line Options
• Environment Variables
• How It Works
• License
• Code of Conduct
• Contributing

Add this line to your application's Gemfile:

gem 'coverage-reporter'

And then execute:

bundle install

Or install it directly:

gem install coverage-reporter

1. Generate a SimpleCov coverage report in your test suite:

   # In your test helper or spec_helper
   require 'simplecov'
   SimpleCov.start

2. Set up environment variables:

   export GITHUB_TOKEN="your_github_token_here"
   export REPO="owner/repository"
   export PR_NUMBER="123"
   export COMMIT_SHA="abc123def456"

3. Run the coverage reporter:

   coverage-reporter report

The tool will automatically:

• Load your coverage data from coverage/coverage.json
• Fetch the pull request diff from GitHub
• Identify uncovered lines in modified code
• Post inline comments on uncovered lines
• Add a global coverage summary comment

• GitHub Token: A personal access token with repo permissions
• Repository: GitHub repository in owner/repo format
• Pull Request Number: The PR number to comment on
• Commit SHA: The commit SHA being analyzed

• Coverage Report Path: Path to your SimpleCov coverage.json file (default: coverage/coverage.json)
• Build URL: CI build URL for linking back to your build (default: $BUILD_URL)

coverage-reporter \
  --github-token "$GITHUB_TOKEN" \
  --repo "myorg/myrepo" \
  --pr-number "42" \
  --commit-sha "$GITHUB_SHA"

coverage-reporter \
  --github-token "$GITHUB_TOKEN" \
  --repo "myorg/myrepo" \
  --pr-number "42" \
  --commit-sha "$GITHUB_SHA" \
  --coverage-report-path "test/coverage/coverage.json"

coverage-reporter \
  --github-token "$GITHUB_TOKEN" \
  --repo "myorg/myrepo" \
  --pr-number "42" \
  --commit-sha "$GITHUB_SHA" \
  --build-url "https://github.com/myorg/myrepo/actions/runs/123456"

name: Test Coverage
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.1
          bundler-cache: true

      - name: Run tests with coverage
        run: bundle exec rspec
        env:
          COVERAGE: true

      - name: Report coverage
        run: bundle exec coverage-reporter
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          REPO: ${{ github.repository }}
          PR_NUMBER: ${{ github.event.number }}
          COMMIT_SHA: ${{ github.sha }}
          BUILD_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

All command-line options can be set via environment variables:

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export REPO="myorg/myrepo"
export PR_NUMBER="123"
export COMMIT_SHA="abc123def456"
export COVERAGE_REPORT_PATH="coverage/coverage.json"
export BUILD_URL="https://ci.example.com/build/123"

1. Loads Coverage Data: Reads SimpleCov's coverage.json file to understand which lines are covered by tests
2. Fetches PR Diff: Retrieves the pull request diff from GitHub to identify modified lines
3. Finds Intersections: Identifies uncovered lines that were modified in the PR
4. Posts Inline Comments: Adds comments directly on uncovered lines in the diff
5. Creates Summary: Posts a global comment with overall coverage statistics

Your GitHub token needs the following permissions:

• repo (Full control of private repositories)
• public_repo (Access public repositories)

Create a token at: https://github.com/settings/tokens

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

Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Pull requests are welcome! Please read our contribution guidelines for details on our code of conduct and the process for submitting pull requests.