UndercoverCI

https://undercover-ci.com/docs
Admin
UndercoverCI is a GitHub App that protects Ruby codebases from untested code changes by analyzing...
Tokens:3,673
Snippets:42
Trust Score:6.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### GitHub Actions Workflow for UndercoverCI Upload

Source: https://undercover-ci.com/docs

This example demonstrates a GitHub Actions workflow that includes steps to set up Ruby, install dependencies, run tests, and upload SimpleCov coverage to UndercoverCI.

```yaml
name: Rails Unit Tests
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Ruby 3.2
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: 3.2
    - name: Build and test with Rake
      env:
        RAILS_ENV: test
      run: |
        # other pre-requisite setup steps...
        gem install bundler
        bundle install --jobs 4 --retry 3
        bundle exec rake test
        ruby -e "$(curl -s https://undercover-ci.com/uploader.rb)" -- \
          --repo ${{ github.repository }} \
          --commit ${{ github.event.pull_request.head.sha || github.sha }} \
          --simplecov coverage/coverage.json
```

--------------------------------

### Install Undercover Claude Plugin

Source: https://undercover-ci.com/docs

Install the undercover-claude plugin for Claude Code by cloning the repository and providing the plugin directory to the `claude` command.

```bash
git clone https://github.com/grodowski/undercover-claude
```

```bash
claude --plugin-dir ./undercover-claude
```

--------------------------------

### Install Undercover CLI

Source: https://undercover-ci.com/docs

Install the undercover ruby gem locally to use the CLI for checking code coverage.

```bash
gem install undercover
```

--------------------------------

### Get Coverage Report

Source: https://undercover-ci.com/docs

Retrieves the coverage report for a specific commit SHA. The report format (JSON or LCOV) is preserved from the original upload. The example uses `curl` with the `-L` flag to follow redirects to the storage provider.

```APIDOC
## GET /v1/checks/:commit_sha/coverage

### Description
Returns the coverage report for the given commit SHA. The coverage report will be in the original format (JSON or LCOV) as uploaded. The `curl` example below includes the `-L` flag to ensure curl follows the redirect to the storage provider.

### Method
GET

### Endpoint
/v1/checks/:commit_sha/coverage

### Request Example
```bash
curl -LH "Authorization: Bearer $UNDERCOVER_API_TOKEN" \
-o check_coverage.json \
https://undercover-ci.com/v1/checks/aa412c105eff7a7af918fc422bf5085101295798/coverage
```
```

--------------------------------

### Get Coverage Check Information

Source: https://undercover-ci.com/docs

Retrieves the coverage check information for a given commit SHA. This endpoint is useful for checking the status and details of coverage analysis for a specific point in your project's history.

```APIDOC
## GET /v1/checks/:commit_sha

### Description
Returns the coverage check information for the given commit SHA.

### Method
GET

### Endpoint
/v1/checks/:commit_sha

### Parameters
#### Path Parameters
- **commit_sha** (string) - Required - The SHA of the commit to retrieve coverage information for.

### Request Example
```bash
curl -H "Authorization: Bearer $UNDERCOVER_API_TOKEN" \
 https://undercover-ci.com/v1/checks/aa412c105eff7a7af918fc422bf5085101295798
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the coverage check.
- **head_sha** (string) - The commit SHA for which the coverage check was performed.
- **base_sha** (string) - The base commit SHA used for comparison.
- **state** (string) - The current state of the coverage check (e.g., "complete").
- **state_log** (array) - A log of state transitions with timestamps.
  - **to** (string) - The state the check transitioned to.
  - **ts** (string) - The timestamp of the state transition.
  - **from** (string) - The state the check transitioned from.
- **repo_full_name** (string) - The full name of the repository.

#### Response Example
```json
{
  "id": 327889,
  "head_sha": "aa412c105eff7a7af918fc422bf5085101295798",
  "base_sha": "master",
  "state": "complete",
  "state_log": [
    {
      "to": "awaiting_coverage",
      "ts": "2023-11-25T15:27:14Z",
      "from": "created"
    },
    {
      "to": "in_progress",
      "ts": "2023-11-25T15:28:48Z",
      "from": "awaiting_coverage"
    },
    {
      "to": "complete",
      "ts": "2023-11-25T15:37:22Z",
      "from": "in_progress"
    }
  ],
  "repo_full_name": "twitchy-tortoise/undercover-test"
}
```
```

--------------------------------

### Configure SimpleCov for Parallel Tests in Rails

Source: https://undercover-ci.com/docs

Configure SimpleCov with the `parallelize` helper for Rails applications to produce a single coverage output file suitable for UndercoverCI. This setup is useful for managing coverage across parallel test workers.

```ruby
# test_helper.rb
# ...
parallelize(workers: :number_of_processors)

parallelize_setup do |worker|
  SimpleCov.command_name "#{SimpleCov.command_name}-#{worker}"
end

parallelize_teardown do |worker|
  SimpleCov.result
end
# ...
```

--------------------------------

### Configure Undercover Repository Options

Source: https://undercover-ci.com/docs

Define Undercover options for your repository by creating a `.undercover` file in the root directory. This file uses the same format as the gem's configuration file and allows control over which files are analyzed.

```plaintext
--exclude-files "vendor/*,db/*,spec/*"
--include-files "*.rb,*.rake"
```

--------------------------------

### Configure SimpleCov and Undercover for Ruby

Source: https://undercover-ci.com/docs

Add these gems to your project and append this configuration to your `spec_helper.rb` or `test_helper.rb` to enable UndercoverCI's SimpleCov formatter and branch coverage.

```ruby
require 'simplecov'
require 'undercover/simplecov_formatter'
SimpleCov.formatter = SimpleCov::Formatter::Undercover
SimpleCov.start do
  add_filter(/^\/spec\//) # For RSpec, use `test` for MiniTest
  enable_coverage(:branch)
end
```

--------------------------------

### Download Coverage Report using curl

Source: https://undercover-ci.com/docs

Use this command to download the coverage report for a specific commit SHA. Ensure you replace `$UNDERCOVER_API_TOKEN` with your actual API token. The `-L` flag is important for following redirects to the storage provider.

```bash
curl -LH "Authorization: Bearer $UNDERCOVER_API_TOKEN" \
-o check_coverage.json \
https://undercover-ci.com/v1/checks/aa412c105eff7a7af918fc422bf5085101295798/coverage
```

--------------------------------

### Bash Commands for Development Workflow

Source: https://undercover-ci.com/docs

A set of bash commands for running tests, linters, and coverage checks locally. These are useful for AI coding agents to understand the development environment.

```bash
bundle exec rake # run rspec tests and rubocop
```

```bash
bundle exec rspec # run specs
```

```bash
bundle exec rubocop # run rubocop lint
```

```bash
bundle exec rubocop -A # correct correctable rubocop violations
```

--------------------------------

### Fetch Coverage Check Information via API

Source: https://undercover-ci.com/docs

Retrieve coverage check information for a specific commit SHA using the Undercover HTTP API. Ensure you have configured your per-user auth token in the API settings.

```bash
curl -H "Authorization: Bearer $UNDERCOVER_API_TOKEN" \
  https://undercover-ci.com/v1/checks/aa412c105eff7a7af918fc422bf5085101295798
```

--------------------------------

### UndercoverCI Uploader Script

Source: https://undercover-ci.com/docs

A Ruby script to upload coverage reports to UndercoverCI. It requires repository name, commit SHA, and the path to the coverage report.

```ruby
ruby -e "$(curl -s https://undercover-ci.com/uploader.rb)" -- \
          --repo grodowski/undercover \
          --commit $CIRCLE_SHA1 \
          --simplecov coverage/coverage.json
```

--------------------------------

### Test Coverage Commands for Development Workflow

Source: https://undercover-ci.com/docs

Commands to inspect local test coverage using Undercover. These commands are helpful for AI coding agents to ensure code changes are adequately tested.

```bash
bundle exec undercover # inspect coverage of local changes
```

```bash
bundle exec undercover --compare master # inspect coverage w.r.t. master (for pull requests)
```

```bash
bundle exec undercover --compare HEAD~1 # inspect coverage w.r.t. previous commit
```

--------------------------------

### Upload Coverage to UndercoverCI using CircleCI

Source: https://undercover-ci.com/docs

Use this command in your CircleCI configuration to upload SimpleCov coverage data to UndercoverCI after tests have run. Replace placeholders with your repository details.

```bash
ruby -e "$(curl -s https://undercover-ci.com/uploader.rb)" -- \
  --repo $your-username/$repository-name \
  --commit $CIRCLE_SHA1 \
  --simplecov coverage/coverage.json
```

--------------------------------

### Skip Coverage with :nocov: Comment

Source: https://undercover-ci.com/docs

Use the `:nocov:` syntax to exclude specific code blocks from coverage analysis. This is useful for acknowledging untested changes and preventing UndercoverCI warnings, with the intention to improve coverage later.

```ruby
# :nocov:
def skip_this_method
  never_reached
end
# :nocov:
```

--------------------------------

### Run Coverage Skill in Claude Code

Source: https://undercover-ci.com/docs

Invoke the coverage skill within a Claude Code session using the `/undercover:coverage` command.

```bash
/undercover:coverage
```

--------------------------------

### Check Local Coverage with Undercover CLI

Source: https://undercover-ci.com/docs

Use the `undercover` CLI command to check for missing coverage in uncommitted changes. The `--compare` flag allows comparison against a specific commit or branch.

```bash
undercover --compare base-branch
```

```bash
undercover --compare HEAD~1
```

--------------------------------

### Conditional Coverage Upload in GitHub Actions

Source: https://undercover-ci.com/docs

This snippet shows how to conditionally run tests and upload coverage in a GitHub Actions matrix build, ensuring coverage is only uploaded for a specific Ruby version.

```yaml
# ...
- name: Run tests with coverage
  if: ${{ matrix.ruby-version == env.undercover_version }}
  env:
    COVERAGE: "true"
  run: bundle exec rspec
# ...
```

--------------------------------

### Merge Parallel Test Coverage Reports

Source: https://undercover-ci.com/docs

A Ruby snippet to merge multiple coverage reports when CI builds run tests in parallel. This is necessary because the uploader script currently accepts only a single coverage file.

```ruby
#!/usr/bin/env ruby

```

--------------------------------

### Merge Parallel Coverage Results

Source: https://undercover-ci.com/docs

Use this script to merge coverage results from parallel CircleCI test containers into a single JSON report for UndercoverCI. Ensure the coverage results are in the expected JSON format.

```ruby
require 'simplecov'
require 'undercover/simplecov_formatter'

puts('Merging coverage results from parallel CircleCI tests containers into a single JSON report...')

SimpleCov.collate(Dir['/home/circleci/rspec/*.resultset.json']) do
  enable_coverage(:branch)
end

report_path = ARGV[0] || 'coverage/coverage.json'
SimpleCov.formatter = SimpleCov::Formatter::Undercover

merged_result = SimpleCov.result
merged_result.format!

if File.size(report_path).zero?
  puts('Written report has 0 bytes')
  exit 1
end
puts("Done! Coverage saved to #{report_path}")
```
Tokens:
Raw