Coverband
Ruby production code coverage collection and reporting (line of code usage)
Install / Use
/learn @danmayer/CoverbandREADME
Coverband
A gem to measure production code usage, showing a counter for the number of times each line of code is executed. Coverband allows easy configuration to collect and report on production code usage. It reports in the background via a thread, can be used as Rack middleware, or can be manually configured to meet any need.
Note: Coverband is not intended for test code coverage; for that we recommend using SimpleCov.
Key Features
The primary goal of Coverband is to give you deep insight into the production runtime usage of your application code, while having the least impact on performance possible.
- Low performance overhead
- Simple setup and configuration
- Out of the box support for all standard code execution paths (web, cron, background jobs, rake tasks, etc)
- Splits code loading usage (Rails eager load) and runtime usage metrics
- Easy to understand actionable insights from the report
- Mountable web interface to easily share reports
Installation
Redis
Coverband stores coverage data in Redis. The Redis endpoint is looked for in this order:
ENV['COVERBAND_REDIS_URL']ENV['REDIS_URL']localhost:6379
The redis store can also be explicitly defined within the config/coverband.rb. See advanced config.
Gem Installation
Add this line to your application's Gemfile, remember to bundle install after updating:
gem 'coverband'
No custom code or middleware required
With older versions of Coverband, projects would report to redis using rack or sidekiq middleware. After Coverband 4.0, this should no longer be required and could cause performance issues. Reporting to redis is now automatically done within a background thread with no custom code needed.
See changelog.
Rails
The Railtie integration means you shouldn't need to do anything else other than ensure Coverband is required after Rails within your Gemfile.
Sinatra
For the best coverage, you want this loaded as early as possible. We recommend requiring cover band directly in the config.ru. Requiring Coverband within an initializer could also work, but you may end up missing some boot up coverage. To start collection require Coverband as early as possible.
require 'coverband'
require File.dirname(__FILE__) + '/config/environment'
use Coverband::BackgroundMiddleware
run ActionController::Dispatcher.new
Coverband Web UI
You can check it out locally by running the Coverband Demo App.
-
View a shared demo at https://coverband-rails-example.onrender.com/
-
View overall coverage information
-
Drill into individual file coverage
-
View individual file details
-
Clear Coverage - disabled by default as it could be considered a dangerous operation in production. Enable with
config.web_enable_clearor leave off and clear from the rake task.-
Clear coverage report
This will clear the coverage data. This wipes out all collected data.
-
Clear individual file coverage
This will clear the details of the file you are looking at. This is helpful if you don't want to lose all Coverage data but made a change that you expect would impact a particular file.
-
-
Force coverage collection
This triggers coverage collection on the current webserver process. Useful in development but confusing in production environments where many ruby processes are usually running.
Interpreting results
The columns in the web UI are as follows:
- % covered - Percentage of total relevant lines covered
- % runtime - Percentage of the runtime lines covered where runtime lines are lines that are hit after the application has been eagerly loaded
- Lines - Total lines in the file including lines unreachable or uncover-able. An unreachable line would be an empty line with no code, comments, or
endstatements. - Relevant lines - Lines that are coverable, i.e. not empty
- Lines runtime - Total lines minus uncoverable lines minus the lines that are only hit during eager loading of application
- Lines missed - Relevant lines not covered
- Avg hits/line - Total of coverage to the file divided by relevant lines.
When viewing an individual file, a line of code such as a class or method definition may appear green because it is eager loaded by the application, but still not be hit at all in runtime by actual users.
Coverage first seen and Last activity recorded
In the context of Coverband, a file is considered relevant for monitoring if it is located within certain specified project paths. Specifically, Coverband monitors all *.rb files located in the following paths:
-
app/
-
lib/
-
config/
This applies as long as these files are not included in the list of exclusions defined in "config.ignore".
Coverage first seen
This attribute shows the exact date and time when Coverband first detected the file. This detection happens when:
-
The file is loaded by Ruby (e.g., during application startup in Rails via autoload or require).
-
The file becomes relevant for monitoring, even if no lines within it have been executed yet.
-
By default, Coverband resets a file’s coverage data and updates its “Coverage first seen” timestamp whenever the file changes, ensuring the coverage reflects the file’s new state.
Last activity recorded
This attribute shows the most recent time when any line in the file was executed at runtime. It specifically reflects runtime execution and does not include the file’s load time.
-
When any line in the file is executed at runtime (e.g., a method is called, a route is triggered, or a conditional is evaluated), Coverband updates the “Last activity recorded” timestamp.
-
This only occurs when the file’s lines are actually executed. If a file is loaded but none of its lines are executed, the “Last activity recorded” timestamp will not be updated.
-
It helps determine if a file is actively being used in the application. If a file has no recent activity, it may be a candidate for review or removal.
Example
-
If a file has a “Coverage first seen” timestamp but no “Last activity recorded”, this indicates that the file is being loaded but no runtime activity is occurring (e.g., it contains unused methods or classes).
-
If both attributes are populated and the “Last activity recorded” timestamp is recent, the file is actively used in the application.
Mounting as a Rack App
Coverband comes with a mountable rack app for viewing reports. For Rails this can be done in config/routes.rb with:
Rails.application.routes.draw do
mount Coverband::Reporters::Web.new, at: '/coverage'
end
But don't forget to protect your source code with proper authentication. Something like this when using devise:
Rails.application.routes.draw do
authenticate :user, lambda { |u| u.admin? } do
mount Coverband::Reporters::Web.new, at: '/coverage'
end
end
or you can enable basic auth by setting ENV['COVERBAND_PASSWORD'] or via your configuration config.password = <YOUR_COMPLEX_UNGUESSABLE_PASSWORD>
Standalone
The coverage server can also be started standalone with a rake task:
bundle exec rake coverband:coverage_server
The web UI should then be available here: http://localhost:9022/
If you want to run on an alternative port:
COVERBAND_COVERAGE_PORT=8086 bundle exec rake coverband:coverage_server
This is especially useful for projects that are api only and cannot support the mounted rack app. To get production coverage, point Coverband at your production redis server and ensure to checkout the production version of your project code locally.
COVERBAND_REDIS_URL=redis://username:password@redis_production_server:2322 bundle exec rake coverband:coverage_server
Coverband Demo
Take Coverband for a spin on the live Heroku deployed Coverband Demo. The full source code for the demo is available to help with installation, configuration, and understanding of basic usage.
Example apps
Advanced Config
If you need to configure Coverband, this can be done by creating a config/coverband.rb file relative to your project root.
- See [lib/coverband/configuration.rb](https://
