API Introduction

The Coveralls API

For users of the Ruby programming language, Coveralls is best accessed by our official gem. We hope to expand our official support to other languages and toolchains soon.

We want to encourage developers to help us expand Coveralls' usefulness to other languages, and for that we have provided a REST Coverage API to allow use with any language.

Sending Coverage to Coveralls

Each coverage job on Coveralls consists of a reference to a repository, and a set of source files with their associated coverage data.

At its simplest level, a coverage job on Coveralls consists of two items: the source code of a file and which lines were covered. The source code is stored as a string, and the line-by-line coverage data is stored as an array. Just toss this information in a JSON hash, and – boom! – you've got your source file.

Referencing a Repository

We can reference a repository in one of two ways:

  • service_job_id String and service_name String

    Coveralls currently supports the following continuous integration services: Travis CI, Travis Pro, CircleCI, Semaphore, JenkinsCI, or Codeship.

    Setting service_name to "travis-ci" and service_job_id to the Travis Job ID will automatically look up the appropriate build and repository, and assign the job correctly on Coveralls.

  • repo_token String

    The secret repo token for your repository, found at the bottom of your repository's page on Coveralls. This is useful if your job is running on a service we don't support out-of-the-box. If you choose to use the repo token, a new build will be created for every job.

Source Files

Here's an example of what a source file would look like as JSON:

{
  "name":     "lib/example.rb",
  "source_digest":   "1eb14b3a053f951ca925f2fd4d633eeb",
  "coverage": [null, 1, null]
}
  • name String

    The relative file path of this source file in the git repo. Must be unique in the job. Can include slashes. The file type for syntax highlighting will be determined from the file extension in this parameter. This is used to pull in the source for coverage display, so must be the exact path relative to the repo root.

  • source_digest String

    The MD5 digest of full source code of this file. We don't store source code on Coveralls, rather just digests to track changes.

  • coverage Array

    An array of coverage data, with item at index 0 representing the coverage for line 1 of the source code.

    Acceptable values for the array is an integer representing the number of times that line is covered, or null representing a line that is not relevant to coverage (such as whitespace or a comment).

Posting to Coveralls

To post a new job, send a multipart HTTP POST to https://coveralls.io/api/v1/jobs.

Because a project with all it's coverage and source can be large, you must write your API request to a JSON file and send it with the form parameter json_file.

Coveralls will respond with an HTTP 200 OK if the request was successful.

Any other response code should be considered a failure and the response body will be set to error text.

Here's an example of a complete json_file:

{
  "service_job_id": "1234567890",
  "service_name": "travis-ci",
  "source_files": [
    {
      "name": "example.rb",
      "source_digest": "asdfasdf1234asfasdf2345",
      "coverage": [null, 1, null]
    },
    {
      "name": "lib/two.rb",
      "source_digest": "asdf1234asdfsdfggsfgd9423",
      "coverage": [null, 1, 0, null]
    }
  ]
}

Getting data from Coveralls

The following are examples of endpoints that can be requested as JSON:

https://coveralls.io/github/lemurheavy/coveralls-ruby.json (latest build)
https://coveralls.io/github/lemurheavy/coveralls-ruby.json?page=1 (get 10 builds at a time)
https://coveralls.io/builds/2885284.json https://coveralls.io/jobs/6730283.json https://coveralls.io/files/880095615.json https://coveralls.io/builds/2885284/source.json?filename=lib%2Fcoveralls%2Fsimplecov.rb

For easier programmatic access, you can use the build commit sha to instead of its numerical ID, e.g.:

https://coveralls.io/builds/2ea77ec5eeea2351de50b268994ba69f876b815c.json https://coveralls.io/builds/2ea77ec5eeea2351de50b268994ba69f876b815c/source.json?filename=lib%2Fcoveralls%2Fsimplecov.rb

Source file endpoints will return the coverage array, e.g:

[6,6,6,null,6,null,6,6,null,0,null,6,42,42,42,49,42,12,null,12,null,18,null,42,null,6,null,null,6,null,18,0,0,null,0,null,null,null,18,18,42,null,null,42,null,null,42,null,null,42,null,null,null,null,null,null,null,null,null,null,null,42,null,null,null,null,null,null,null,null,null,18,18,null,18,null,null,0,null,null,6,6,6,6,1,0,5,6,6,null,6,null,null,6,21,null,null,6,84,84]


The index of the array corresponds to the index of the source file line number. The value is the number of times the line was executed, and "null" implies the line is not relavent.

Have more questions? Submit a request

Comments

  • Avatar
    Jarrod Carlson

    The sample JSON and the documentation in the SOURCE FILES section above do not agree with each other. One lists "source" as a parameter with the full text of the source file, the other lists "source_digest" as an MD5 checksum of the file.

Powered by Zendesk