Coveralls was designed with Ruby projects in mind, and we've made it as easy as we possibly can to get started.
Please note that SimpleCov only supports Ruby 1.9 and later.
Installing the Gem
You shouldn't need more than a quick change to get your project on Coveralls. Just include the Coveralls gem in your project's Gemfile like so:
# ./Gemfile gem 'coveralls', require: false
While SimpleCov only supports Ruby 1.9+, using the Coveralls gem will not fail builds on earlier Rubies or other flavors of Ruby.
Coveralls for Ruby uses an optional
.coveralls.yml file at the root level of your repository to configure options.
repo_token (found on your repository's page on Coveralls) is used to specify which project on Coveralls your project maps to. This is only needed for repos not using a CI and should be kept secret -- anyone could use it to submit coverage data on your repo's behalf. This shouldn't be a concern for private repos, however.
Another important option is
service_name which allows you to specify where Coveralls should look to find additional information about your builds. This can be any string, but using
travis-pro will allow Coveralls to fetch branch data, comment on pull requests, and more.
.coveralls.yml file configured for Travis Pro:
CircleCI, Jenkins, Semaphore, and Codeship
When using CircleCI, Jenkins, Semaphore, or Codeship you must either include your repo token in a
.coveralls.yml file or, if you don't want it under source control, set it in your build config like this in the "Test Commands" (CircleCI) or "Build Commands" (Semaphore) section of the project settings:
COVERALLS_REPO_TOKEN=asdfasdf bundle exec rspec spec
Testing Suite Setup
The next step is to add Coveralls to your testing suite.
# ./spec/spec_helper.rb # ./test/test_helper.rb # ..etc.. require 'coveralls' Coveralls.wear!
Or, for a Rails app:
require 'coveralls' Coveralls.wear!('rails')
Coveralls.wear! must occur before any of your application code is required, so should be at the very top of your spec_helper.rb, test_helper.rb, or env.rb, etc.
And holy moly, you're done!
Next time your project is built on Travis, SimpleCov will dial us up and send us the hot details on your code coverage.
"But wait!" you are saying, "I already use SimpleCov. And I have some custom settings! Are you clowns just overriding everything I've carefully set up?"
Good news, just use our SimpleCov formatter directly:
require 'simplecov' require 'coveralls' SimpleCov.formatter = Coveralls::SimpleCov::Formatter SimpleCov.start do add_filter 'app/secrets' end
Or use it alongside another formatter:
require 'simplecov' require 'coveralls' SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[ SimpleCov::Formatter::HTMLFormatter, Coveralls::SimpleCov::Formatter ] SimpleCov.start
Merging multiple test suites
If you're using more than one testing suite and want the coverage results to be merged, use
Coveralls.wear_merged! instead of
Coveralls.wear!, or if you're using Coveralls alongside another SimpleCov formatter, simply omit the Coveralls formatter.
Then add the rake task
coveralls:push as a dependency to your testing task like so in your Rakefile:
require 'coveralls/rake/task' Coveralls::RakeTask.new task :test_with_coveralls => [:spec, :features, 'coveralls:push']
This will prevent Coveralls from sending coverage data after each individual suite, instead waiting until SimpleCov has merged the results, which are then posted to Coveralls.io.
Unless you've added
coveralls:push to your default rake task, your build command will need to be updated on your CI to reflect this, ex:
bundle exec rake :test_with_coveralls
Read more about SimpleCov's result merging.
Manual Builds via CLI
Coveralls for Ruby also allows you to upload coverage data manually by running your test suite directly.
To do this with RSpec, just type
bundle exec coveralls push in your project directory.
This will run RSpec and upload the coverage data to Coveralls as a one-off build, passing along any configuration options specified in