coveralls-ruby-demo

Coveralls demo project, using:

• Ruby — Language
• Rspec — Testing Library
• Simplecov — Code Coverage Library

How to run it:

bundle install
bundle exec rspec

About Coveralls

Coveralls is a web service that sends code coverage reports to a shared workspace so you and your team can track your project's code coverage over time. Coveralls can also post PR comments and pass / fail checks to help you control your development workflow.

Coveralls is language-, SCM- and CI-agnostic, but for this project we're using Ruby and GitHub, with various CI Services depending on the branch you choose.

How It Works

Before your project gets to Coveralls, it must already be using a code coverage library to generate coverage results. In this project, we're using the Ruby-based Simplecov:

Here's how it works:

1. You commit changes to your repo at your SCM (GitHub).
2. Your CI service builds your project, runs your test, and generates your code coverage report.
3. Your CI posts those results to Coveralls.
4. Coveralls updates your project with new coverage results.
5. (Optional) Coveralls posts PR comments and pass/fail checks to control your development workflow.

What then?

---

There's an implicit Step 6 here, which is you deciding whether to merge, and deploy, the new changes based on coverage. This can be manual or automated, based on settings you configure at Coveralls.

---

We'll set up this project to work exactly like the above diagram, with these four (4) steps:

Get Started

1. Understand test coverage in this project
2. Run tests for the first time
3. Add tests and see coverage change
4. Configure this project to use Coveralls

1. Understand test coverage in this project

Do it.

---

This is the totality of the code in this project:

class ClassOne

  def self.covered
    "covered"
  end

  def self.uncovered
    "uncovered"
  end

end

And these are the tests:

require 'spec_helper'
require 'class_one'

describe ClassOne do

  describe "covered" do
    it "returns 'covered'" do
      expect(ClassOne.covered).to eql("covered")
    end
  end

  # Uncomment below to achieve 100% coverage
  # describe "uncovered" do
  #   it "returns 'uncovered'" do
  #     expect(ClassOne.uncovered).to eql("uncovered")
  #   end
  # end
end

Notice that right now, only one of the two methods in ClassOne is being tested.

2. Run tests for the first time

Do it.

---

Let's run the test suite for the first time and see what the results are.

If you haven't already, go ahead and clone the project down to your local machine:

git clone git@github.com:afinetooth/coveralls-demo-ruby.git

Now, cd into coveralls-demo-ruby and run this command to install the dependencies:

bundle install

Finally, run the test suite, Rspec.

bundle exec rspec

You'll notice test results on the screen, which should look like this:

ClassOne
  covered
    returns 'covered'

Finished in 0.0028 seconds (files took 1 second to load)
1 example, 0 failures

Coverage report generated for RSpec to /Users/jameskessler/Workspace/2020/coveralls/coveralls-demo-ruby/coverage. 4 / 5 LOC (80.0%) covered.

In additional to the test results themselves, we have the added benefit of test coverage results, from using our test coverage library, Simplecov.

Every time we run our test suite, Simplecov, in the background, generates HTML-based code coverage results, which you can see by opening the newly created file at /coverage/index.html in your browser, or by issuing this command in your terminal:

open coverage/index.html

The first results should look like this:

Where coverage stands at 80% for the entire project.

Clicking on lib/class_one.rb brings up results for the file:

Where you'll notice covered lines in green, and uncovered lines in red.

In our case, 4/5 lines are covered, indicating 80% coverage.

Why isn't coverage 50%?

---

One might expect the coverage results here to be 50%, given that ClassOne has two (2) methods (covered and uncovered) and we're only testing one of them. However, that's not how it works. Instead, Simplecov counts relevant lines in each file and compares the number of covered lines to uncovered lines to determine the file's coverage percentage.

3. Add tests and see coverage change

Do it.

---

To "add" tests, simply un-comment the test of the second method in ClassOne:

require 'spec_helper'
require 'class_one'

describe ClassOne do

  describe "covered" do
    it "returns 'covered'" do
      expect(ClassOne.covered).to eql("covered")
    end
  end

  # Uncomment below to achieve 100% coverage
  describe "uncovered" do
    it "returns 'uncovered'" do
      expect(ClassOne.uncovered).to eql("uncovered")
    end
  end
end

Now run the test suite again:

bundle exec rspec

And open the new results at coverage/index.html.

Here's how things look now:

Notice coverage has increased from 80% to 100% (and turned green).

And now, if we click on lib/class_one.rb we see:

Five (5) out of five (5) relevant lines are now covered, resulting in 100% coverage for the file, which means 100% coverage for our one-file project.

4. Configure this project to use Coveralls

Do it.

---

Now that you understand how test coverage works in this project, you'll soon be able to verify the same results through Coveralls.

Which CI Service will you use?

Since your CI Service will be sending code coverage results to Coveralls, you'll need to choose a CI service and add this repo to it.^*

Follow the branch for your CI service and we'll pick up the conversation there:

1. Travis CI
2. Circle CI
3. ...

* other scenarios

---

Technically speaking, there are other ways to send your test coverage results to Coveralls without a CI Service; namely, through their API. That's not the subject of this README, so to find out more see Coveralls API Docs. You can find out about creating new repos here, and about posting coverage results to those repos here.