Start Building for Free

Generate code coverage metrics

2 months ago4 min read
Server v4.x
Server v3.x
Server v2.x
On This Page


CircleCI provides different options for code coverage reporting using built-in CircleCI features combined with open source libraries, or using partners. Below are a few examples that demonstrate configuring coverage libraries for different languages, as well as how to view your code coverage on the CircleCI web app.


SimpleCov is a popular Ruby code coverage library. To get started, add the simplecov gem to your Gemfile.

gem 'simplecov', require: false, group: :test

Start simplecov when your test suite starts. The example below demonstrates configuring SimpleCov for usage with Rails.

require 'simplecov'        # << Require SimpleCov
SimpleCov.start 'rails'    # << Start SimpleCov, using the "Rails" preset.

ENV['RAILS_ENV'] ||= 'test'
require_relative '../config/environment'
require 'rails/test_help'

class ActiveSupport::TestCase
  # Setup all fixtures in test/fixtures/*.yml for all tests in alphabetical order.
  fixtures :all
  # Add more helper methods to be used by all tests here...

Now configure your .circleci/config.yml file for uploading your coverage report.

See the SimpleCov README for more detail.

Python is a popular library for generating code coverage reports in Python. To get started, install

pip install coverage
# previously you might have run your python project like:
python arg1 arg2

# now prefix "coverage" to your command.
coverage run arg1 arg2

In this example, you can generate a coverage report with the following commands:

coverage run -m pytest
coverage report
coverage html  # open htmlcov/index.html in a browser

The generated files will be found under htmlcov/, which can be uploaded in a store_artifacts step in your configuration:


JaCoCo is a popular library for Java code coverage. Below is an example pom.xml file that includes JUnit and JaCoCo as part of the build system:

<project xmlns=""




							<!-- Sets the path to the file which contains the execution data. -->

							<!-- Sets the output directory for the code coverage report. -->

Running mvn test will include a code coverage report (an exec) file that is also converted to an html page, like many other coverage tools. The Pom file above writes to the target directory, which you can then store as an artifact in your .circleci/config.yml file.

Below is a minimal CI configuration to correspond with the above example:


Istanbul is a popular library for generating code coverage reports for JavaScript projects. Another popular testing tool, Jest, uses Istanbul to generate reports. See the example below:


PHPUnit is a popular testing framework for PHP. With PHP, you should have access to a tool called phpdbg. You can generate a report using the command phpdbg -qrr vendor/bin/phpunit --coverage-html build/coverage-report.

In the following basic .circleci/config.yml, we upload the coverage reports in the store_artifacts step at the end of the configuration.


Go has built-in functionality for generating code coverage reports. To generate reports, add the flag -coverprofile=c.out. This will generate a coverage report which can be converted to html via go tool.

go test -cover -coverprofile=c.out
go tool cover -html=c.out -o coverage.html

An example .circleci/config.yml file:

version: 2.1

      - image: cimg/go:1.16
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
      - checkout
      - run: go build
      - run:
          name: "Create a temp directory for artifacts"
          command: |
            mkdir -p /tmp/artifacts
      - run:
          command: |
            go test -coverprofile=c.out
            go tool cover -html=c.out -o coverage.html
            mv coverage.html /tmp/artifacts
      - store_artifacts:
          path: /tmp/artifacts

Use a code coverage service


Codecov has an orb to help simplify the process of uploading your coverage reports.

The Codecov orb is a partner orb. You or your organization admin will need to opt in to using uncertified orbs in order to use it. This setting is available at Organization Settings > Security in the CircleCI web app.

version: 2.1
  codecov: codecov/codecov@1.0.2
      - codecov/upload:

Read more about Codecov’s orb in their guest blog post.


If you are a Coveralls customer, follow their guide to set up your coverage stats. You will need to add COVERALLS_REPO_TOKEN to your CircleCI environment variables.

Coveralls will automatically handle the merging of coverage stats in concurrent jobs.

View coverage on CircleCI

You can upload your code coverage reports directly to CircleCI. First, add a coverage library to your project and configure your build to write the coverage report to CircleCI’s artifacts directory. Code coverage reports will then be stored as build artifacts where they can be viewed or downloaded. See our build artifacts guide for more information on downloading coverage reports stored in your artifacts.

Artifacts tab in the web app

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.