Coverband Documentation

Requirements

• Ruby: 3.1+ (Supports the last 3 major releases).
• Redis: Required for production usage.
• Rails: Primarily targets Rails 7.0+. Supports the last two major release versions.

JRuby Support

Coverband is compatible with JRuby.

• Older JRuby versions require tracing enabled via the --debug option or adding debug.fullTrace=true to .jrubyrc.
• For best performance, oneshot_lines is recommended.

For the most accurate coverage, require Coverband as early as possible in your config.ru to capture the boot process.

require 'coverband'
require File.dirname(__FILE__) + '/config/environment'

use Coverband::BackgroundMiddleware
run ActionController::Dispatcher.new

Add a .mcp.json file to your project root to enable Coverband coverage insights for Claude Code. You can use either Stdio or HTTP transport.

{
  "mcpServers": {
    "coverband": {
      "command": "bundle",
      "args": ["exec", "coverband-mcp"]
    }
  }
}

You can mount the Coverband reporting interface directly into your Rails application via config/routes.rb.

Warning: Always protect the route with authentication to prevent leaking your source code structure.

# Basic mounting
Rails.application.routes.draw do
  mount Coverband::Reporters::Web.new, at: '/coverage'
end

# Recommended: Protected mounting (e.g., using Devise)
Rails.application.routes.draw do
  authenticate :user, lambda { |u| u.admin? } do
    mount Coverband::Reporters::Web.new, at: '/coverage'
  end
end

To track ViewComponent renders, ensure you have ViewComponent >= 4.6.0 and enable instrumentation in your application configuration.

# config/application.rb (or environment-specific config)
config.view_component.instrumentation_enabled = true

To use the Model Context Protocol (MCP) server in a local development environment, enable it in your Coverband configuration and set a password. You can do this via the Ruby initializer or an environment variable.

# config/initializers/coverband.rb
Coverband.configure do |config|
  config.mcp_enabled = true
  config.mcp_password = 'dev-password-123'
end

Or via environment variable:

export COVERBAND_MCP_PASSWORD=dev-password-123

For production environments, follow these security requirements:

1. Enable MCP only in specific allowed environments using config.mcp_allowed_environments.
2. Use a strong, unique password retrieved from an environment variable via config.mcp_password.
3. Ensure the environment variable is set (e.g., using openssl rand -base64 32).

# config/initializers/coverband.rb  
Coverband.configure do |config|
  # Enable MCP only in allowed environments
  config.mcp_enabled = true
  
  # Strong authentication (required for production)
  config.mcp_password = ENV['COVERBAND_MCP_PASSWORD'] 
  
  # Restrict to specific environments
  config.mcp_allowed_environments = %w[production staging]
end

If your Redis server requires TLS, use the rediss:// URL scheme. The Redis gem will automatically enable TLS when this scheme is detected.

Via Environment Variable:

REDIS_URL=rediss://my-elasticache.abcdef.cache.amazonaws.com:6379

Via config/coverband.rb:

config.store = Coverband::Adapters::RedisStore.new(
  Redis.new(url: "rediss://my-elasticache-endpoint:6379")
)

To securely access a production MCP server from a development machine, create an SSH tunnel to forward the port.

# Create secure tunnel to production MCP server
ssh -L 9023:localhost:9023 production-server

# Now access MCP locally via tunnel
curl -H "Authorization: Bearer your-mcp-password" \
     -H "Content-Type: application/json" \
     -X POST http://localhost:9023/mcp \
     -d '{"method":"tools/list"}'

To prevent multiple servers from hitting Redis simultaneously at startup, use config.reporting_wiggle to add a random delay to background reporting. You can also use config.defer_eager_loading_data to only have a subset of servers report eager loading data.

# Add a random wiggle in seconds to background reporting
config.reporting_wiggle = 30

# To omit reporting on starting servers, defer saving eager_loading data
config.defer_eager_loading_data = true
# Store eager_loading data on 5% of servers
config.send_deferred_eager_loading_data = rand(100) < 5

To customize Coverband, create a config/coverband.rb file in your project root. This file is used for advanced configuration. By default, Coverband looks for Redis at ENV['COVERBAND_REDIS_URL'], ENV['REDIS_URL'], or localhost.

# config/coverband.rb NOT in the initializers
Coverband.configure do |config|
  config.store = Coverband::Adapters::RedisStore.new(Redis.new(url: ENV['MY_REDIS_URL']))
  config.logger = Rails.logger

  # config options false, true. (defaults to false)
  config.verbose = false

  # default false. button at the top of the web interface which clears all data
  config.web_enable_clear = true

  # default false. Experimental support for routes usage tracking.
  config.track_routes = true
end