README.md

coveralls-ruby-demo

Coveralls demo project, using:

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

How to run it:

bundle install
bundle exec rspec

About Coveralls

Coveralls is a web service that sends test coverage reports to a shared workspace so you and your team can track your projects' test coverage over time. Coveralls is language- and CI-agnostic, but it lets you control whether your builds pass or fail based on coverage metrics you define.

How It Works

Before your project gets to Coveralls, it must already be using a code coverage library to generate coverage results (Simplecov, in this project).

Your CI service will run your tests, and your code coverage report, then post those results to Coveralls.

1. You commit changes to your repo at your SCM (GitHub).
2. Your CI service builds your project, runs your tests, and generates your test 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.

Get Started

We'll set up this project to do all those things, following these four (4) steps:

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.00198 seconds (files took 0.16243 seconds to load)
1 example, 0 failures

Coverage report generated for RSpec to /Users/jameskessler/Workspace/2020/coveralls/coverallsapp/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.

But first we’ll need to set up the CI pipeline.

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. Github Actions
4. ...