Code Coverage with Coveralls

In an earlier post, I wrote about setting up SonarQube to assist with code inspection. While SonarQube has a number of advanced inspection features, one of its drawbacks is that you must have it running as a service before you can measure things like code test coverage. Impressively, a free service called Coveralls exists to perform code coverage reports. Like Travis CI, Coveralls is an online service that is free to use for open source projects that use GitHub. Setting it up involves:

• Creating a Coveralls account
• Adding your GitHub repository
• Telling your CI service to post coverage information to it

Step 1: Creating an Account

Creating an account involves logging in to Coveralls using your GitHub credentials - it's that simple. For the sake of completeness, if you ever wish to stop using Coveralls, you can simply revoke Coveralls as an application from your GitHub account by clicking on Settings and then Applications. Under Authorized Applications you can see what other third party applications have access to your GitHub repositories. Simply click on the Revoke button if you wish to remove access.

Step 2: Adding Your GitHub Repository

Once you have created a Coveralls account and are signed in, click on the Repos link in the top navigation bar, and then Add Repo. You will be taken to a listing of all your current repositories. Simply switch On the repositories that you want Coveralls to keep track of.

Step 3: Posting to Coveralls

Things can get slightly more complicated depending on the CI solution you are using and the language that your project is coded in. Luckily, the Coveralls documentation has very easy to use instructions on getting your project talking to Coveralls. For me, I was interested in getting my Java Chip 8 emulator hooked up. The project is already being built by Travis-CI so all I needed to do was get it to post the test results coverage to Coveralls.

The answer was a Gradle Plugin. Adding a dependency to Gradle is quite simple – it involves editing the build.gradle file, and inserting the named dependency with its groupId, artifactId and version into the list of dependencies (I spoke more about it in a previous post here). To make this work, you must first apply the Coveralls plugin by adding the following to the top of your configuration file:

apply plugin: 'coveralls'

Next comes the actual Coveralls dependency. The dependency goes in a slightly different spot, since the plugin isn't actually a dependency for the software itself. In my previouspost, I mentioned how there was a section called buildscript in the Gradle configuration file. This section is used to indicate dependencies during the build phase. By placing the plugin here, it will get included at compile time, but will not get packaged into the fat jar:

buildscript {
    repositories {
        mavenCentral()
    }

    dependencies {
        classpath 'org.kt3k.gradle.plugin:coveralls-gradle-plugin:0.3.0'
    }
}

Two other small changes to the build.gradle file are also needed in order for everything to work. The first is to enable the JaCoCo code coverage plugin. This is done by adding the following line:

apply plugin: 'jacoco'

Next, you must tell the plugin what reports you want to generate:

jacocoTestReport {
    reports {
        xml.enabled = true
        html.enabled = true
    }
}

That takes care of the configuration needed on the Gradle end of things. You can test that you have things configured right by doing a gradle tasks to check what tasks are available to Gradle. You should see both coveralls and jacocoTestReport as available tasks in the Other section.

Next up is to modify the .travis.yaml configuration file. The following code gets Travis to generate the JaCoCo coverage reports, and then post them to coveralls:

after_success:
  - gradle jacocoTestReport coveralls

That’s all that is needed. Pushing both modified files should force Travis to rebuild the project, and then post to Coveralls. To make sure everything is working correctly, you can watch Travis build your project, and troubleshoot from there.

Browsing Your Coverage Report

Coveralls displays a list of all your repositories and the current coverage for each one:

That’s helpful, but it’s more helpful to find out where you are lacking coverage. Luckily, Coveralls lets you see that too. Clicking on the repository name will take you into a more detailed report, outlining the change to code coverage based upon each commit:

This is slightly more useful information, but we're not done yet. Clicking on the build number will take you into a more detailed report. By scrolling down to the bottom of the report, you can see a breakdown of coverage by file:

This is the type of report we want! Clicking on a file will reveal another report where tested lines will show up in green, and untested lines will show up in red:

You can use this information to help you determine what lines you are testing, and what lines you are not.

Conclusions

Coveralls provides a convenient, online service that will let you view your test coverage through a simple web interface. Like Travis, Coveralls also supports testing private repositories for a price. If you are looking to do simple code inspection, and need some place to start, Coveralls provides a simple way to get up and running without the need to run your own service.