sbt-coveralls

SBT plugin that uploads scala code coverage to coveralls and integrates with Travis CI and GitHub Actions. This plugin uses scoverage to generate the code coverage metrics.

Please take a look at the samples project to see some [sample output][].

Installation

1. Add the following to your project/build.sbt file

addSbtPlugin("org.scoverage" % "sbt-scoverage" % "1.8.2")

addSbtPlugin("org.scoverage" % "sbt-coveralls" % "1.3.1")

2. Setup coveralls configuration options (such as Specifying Your Repo Token)

3. Register on coveralls

4. Follow the instructions for either Travis CI or Manual Usage

Travis CI Integration

sbt-coveralls can be run by Travis CI by following these instructions:

1. Add the following to your travis.yml

   script: "sbt clean coverage test"
   after_success: "sbt coverageReport coveralls"

   If you have a multi-module project, perform coverageAggregate as a separate command.

   script:
     - sbt clean coverage test coverageReport &&
       sbt coverageAggregate
   after_success:
     - sbt coveralls

2. Job done! Commit these changes to travis.yml to kick off your Travis build and you should see coverage reports appear on coveralls.

GitHub Actions Integration

sbt-coveralls can be run by GitHub Actions by following these instructions:

1. Add the following to your .github/workflows/ci.yml

   - name: Git checkout (merge)
     uses: actions/checkout@v3
     if: github.event_name != 'pull_request'
     with:
       fetch-depth: 0
   
   - name: Git checkout (PR)
     uses: actions/checkout@v3
     if: github.event_name == 'pull_request'
     with:
       fetch-depth: 0
       # see: https://frontside.com/blog/2020-05-26-github-actions-pull_request/#how-does-pull_request-affect-actionscheckout
       ref: ${{ github.event.pull_request.head.sha }}
   
   - name: Run tests
     run: sbt clean coverage test
   
   - name: Upload coverage data to Coveralls
     run: sbt coverageReport coveralls
     env:
       COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       COVERALLS_FLAG_NAME: Scala ${{ matrix.scala }}

   Note the separate checkout step for pull requests. It is needed because of the way pull_request affects actions checkout, so correct commit info could be sent to coveralls.io

   If you have a multi-module project, perform coverageAggregate as a separate command.

   - name: Upload coverage data to Coveralls
     run: sbt coverageAggregate coveralls
     env:
       COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       COVERALLS_FLAG_NAME: Scala ${{ matrix.scala }}

2. Job done! Commit these changes to kick off your GitHub Actions build and you should see coverage reports appear on coveralls.

Manual Usage

1. Get the repo token for your repo from coveralls.

2. Let sbt-coveralls know what your coveralls repo token is. See Specifying Your Repo Token

3. In the SBT console, run coverage then your tests finishing with coveralls. After running the command, you should see output similar to the following:

   Uploading to coveralls.io succeeded: Job #17.1
   https://coveralls.io/jobs/12207
   

Specifying Your Repo Token

There are several ways to tell sbt-coveralls your repo token to support different use cases:

Write your repo token into a file

Add the following to your build.sbt. The path can be absolute and point to somewhere outside the project or relative and point somewhere inside the project (such as src/main/resources/token.txt).

Just remember: Do not store repo tokens inside your project if it is in a public git repository!

import org.scoverage.coveralls.Imports.CoverallsKeys._

coverallsTokenFile := "/path/to/my/repo/token.txt"

Put your repo token directly in your build.sbt

Do not store repo tokens inside your project if it is in a public git repository!

import org.scoverage.coveralls.Imports.CoverallsKeys._

coverallsToken := Some("my-token")

Add an environment variable

Add an environment variable COVERALLS_REPO_TOKEN, for example:

export COVERALLS_REPO_TOKEN=my-token

Specifying Your Coveralls Endpoint

If you're using coveralls as your endpoint, then you don't need to set this option. If you're using a hosted (enterprise) instance of coveralls, you will need to specify your endpoint in one of two ways.

Put your endpoint directly in your build.sbt

import org.scoverage.coveralls.Imports.CoverallsKeys._

coverallsEndpoint := Some("http://my-instance.com")

Add an environment variable

Add an environment variable COVERALLS_ENDPOINT, for example:

export COVERALLS_ENDPOINT=http://my-instance.com

Overriding the current branch

By default sbt-coveralls uses the currently checked-out branch for reporting. To override the branch name add the CI_BRANCH variable, for example:

export CI_BRANCH=my-branch-name

Specifying Source File Encoding

sbt-coveralls finds the encoding in scalacOptions setting value. If not defined it assumes source files are encoded using platform-specific encoding. To specify encoding, add the following to your build.sbt

scalacOptions += Seq("-encoding", "UTF-8")

Using Travis-Pro

It is important to set the correct service when using Travis-Pro. The default is to use travis-ci. To override this value, add the following to your build.sbt

import org.scoverage.coveralls.Imports.CoverallsKeys._
import org.scoverage.coveralls.TravisPro

coverallsService := Some(TravisPro)

Uploading coverage from parallel CI builds

Coveralls supports merging reports from multiple CI builds. Each report must be flagged as coming from a parallel job, then a webhook must be called after all jobs have completed to merge the reports together.

To mark uploaded reports as parallel, either:

Put the flag directly in build.sbt

import org.scoverage.coveralls.Imports.CoverallsKeys._

coverallsParallel := true

Set an environment variable

export COVERALLS_PARALLEL=true

License

sbt-coveralls is open source software released under the Apache 2 License.