Getting Started

Coveralls is a web-based code coverage service that helps you track the quality of your code over time. With Coveralls, you can monitor your codebase to make sure all new code is fully covered.

In this guide, we’ll go over the steps to get started with Coveralls, which are:

1. Create an account
2. Integrate Coveralls with your codebase
3. Run tests and view coverage reports

Once you’re finished, we’ll cover where to go from here.

Create an Account

Creating a Coveralls account is fast and easy—no registration required. All you’ll need is an existing account at a repo hosting service like Github, Gitlab or Bitbucket.

Just go to Coveralls.io, click the Sign In button for your git service, and authorize Coveralls to access your repos.

Integrate Coveralls with your Codebase

To integrate Coveralls with your codebase, follow these steps:

Step 1: Add Your Project to Coveralls

To add your project to Coveralls.io:

1. Go to Coveralls.io and click the Sign In button for your repo hosting service.
2. Authorize Coveralls to access your repos.
3. Go to ADD REPOS, find your repo, and toggle it ON to add it to Coveralls.
4. Click the START UPLOADING COVERAGE button that appears next to your repo.
5. On the Start Page^* for your new repo, note or copy your repo_token^**.
   
   * Note: You now have the option to continue with these instructions, or start following the instructions on your Repo Start Page.
   
   ** Note: We’ll use your repo_token later, to identify your repo to the Coveralls API.

Step 2: Choose an Integration

Several options here. To pick an integration:

1. Go to Coveralls Integrations and find a community-created Language Integration for your programming language.
   
   
2. Or, choose one of these Official Integrations we offer as extensions to popular CI services:
   • Coveralls Github Action
   • Coveralls Orb for CircleCI
     
     
3. Or, try our new Universal Coverage Reporter, a cross-platform binary that represents our future direction for a single Coveralls integration for all projects.
   
   Tip: Read more about why you might want to choose one of these options over another, here.

Step 3: Configure Your Project to Send Coverage to Coveralls

Once you’ve chosen an integration, follow its README to complete two main tasks:

1. Install the integration into your project.
2. Add code to your CI build script to run your tests and upload coverage reports to Coveralls.
   
   Note: While it’s possible your integration will support your CI service out-of-the-box, you may need to configure your CI service to work with your integration. Read more about that here.
   
   Note: As part of this step, you’ll want to create a CI environment variable (or secret) called COVERALLS_REPO_TOKEN to hold your repo_token from above.

Issues? Questions? See below.

Run Tests and View Coverage Reports

Once you’ve integrated your codebase with Coveralls, Coveralls begins automatically tracking coverage for every CI build of your project.

To view your coverage reports:

1. Log in to Coveralls and, from your REPOS PAGE, navigate to the repository you want to view.
2. Click anywhere to start exploring your project’s coverage—by build, by subproject, or by source file.
   
   Tip: Take a quick tour of the Coveralls UI to familiarize yourself with its features.

Where To Go From Here

I’m having an issue.

Check out Common Issues & Troubleshooting.
Or, reach out to us at support@coveralls.io.

It’s working! Now how do I get PR Comments / Status Updates / Notifications?

See Coveralls Notifications.
That will help you set up: PR Comments, Status Updates & other notifications from Coveralls.

What if I have a parallel build?

Coveralls supports parallel builds.
See Parallel Builds for help setting yours up.

Will Coveralls support my language / CI service?

We’ve designed Coveralls to work with all languages and all CI systems.

• Check out Coveralls Integrations to find an integration for your project’s language.
• See Supported CIs to see if your CI is officially supported by one of those integrations—or if you’ll need to manually configure your CI.

What if I want to roll my own integration?

That’s great! You’ll need to talk to the Coveralls API, so check out the The /jobs Endpoint.

But the very best way to contribute to the Coveralls community is to develop a plugin for the Universal Coverage Reporter. Our goal for that project is to add support for every available coverage report format, in order to create one standard integration method for all Coveralls projects.

I have a different question.

Start with the FAQ.
We’ve done our best to cover most questions there.

 

---

Any problems, questions or comments about this doc? Let us know.