coveralls

Send a code coverage job to Coveralls from a Rust program.

coveralls reads a coverage report in the Coveralls JSON format (such as the one produced by grcov), enriches it with the metadata expected by the Coveralls API (CI service identifiers, Git information, ...) and uploads the resulting job to https://coveralls.io.

It can be run on a local machine, but it is primarily meant to be used inside a CI/CD environment such as Travis, Circle-CI, Jenkins, GitHub Actions, and others.

Features

• Takes the Coveralls JSON format as input (the format emitted by grcov), read from a file or from the standard input.
• Prunes dependencies and other unwanted source files out of the report: all absolute paths, or specific directories — so the coverage published online only reflects your project.
• Can prefix every reported file path.
• Automatically resolves the Git metadata of the HEAD commit (author, committer, message, branch, remotes), either from the report, from the environment, from command line arguments, or by reading the local repository.
• Detects the CI service from a subcommand or from the environment.

Installation

Install the command line tool with Cargo:

cargo install coveralls

This installs the coveralls binary, using the default backend that invokes the git command (see Cargo features to use the in-process libgit2 backend instead).

Usage

The coverage report is read from the standard input or from a file passed as an argument, and a subcommand selects the CI service that produced the build:

# On Circle-CI: read the report from a file (the CIRCLE_* variables are picked up automatically).
coveralls circleci coverage.json

# Pipe a report generated by grcov instead of reading it from a file.
grcov ... --output-type coveralls | coveralls circleci

# Provide the repository token explicitly (it overrides COVERALLS_REPO_TOKEN).
coveralls circleci --repo-token "$MY_TOKEN" coverage.json

# Prune absolute paths and the `target` directory, then prefix the remaining files.
coveralls -X -D target -P my-crate circleci coverage.json

# Let the `env` subcommand detect the service from the environment (CI_NAME,
# COVERALLS_SERVICE_NAME, or the native CI markers such as CIRCLECI).
coveralls env coverage.json

# Dry run: process the report but do not upload it.
coveralls -z circleci coverage.json

# Inspect the payload: write it to a file without uploading anything.
coveralls -z -O payload.json circleci coverage.json

Run coveralls --help, or coveralls <service> --help, for the exhaustive list of options and of the environment variables read for each service.

Global options

These options apply to every invocation:

Option	Description
[file_name]	Input file to read instead of the standard input.
-O, --output <file>	Also write the resulting payload (what is sent to Coveralls) to a file.
-P, --source-prefix <prefix>	Prefix prepended to every reported file path.
-D, --prune-dir <dir>	Prune a directory from the report (can be repeated).
-X, --prune-absolutes	Prune all source files with an absolute path.
-F, --force-fetch-git-infos	Always fetch the Git metadata from the local repository.
-z, --no-send	Process the report but do not upload it to Coveralls.

Supported CI services

The CI service is selected either explicitly with a subcommand or guessed from the environment with the env subcommand:

Service	Subcommand
AppVeyor	appveyor
BuildKite	buildkite
Circle-CI	circleci
GitHub Actions	actions
Jenkins	jenkins
Semaphore	semaphore
Travis	travis
(guess)	env

Configuration

Most parameters are read from environment variables, which is convenient inside a CI environment. Command line arguments always override the values read from the environment.

The following variables are common to every service:

Variable	Meaning
COVERALLS_REPO_TOKEN	Coveralls repository token (required).
COVERALLS_FLAG_NAME	Coveralls flag name.
GIT_ID	Commit identifier.
GIT_MESSAGE	Commit message.
GIT_AUTHOR_NAME	Commit author name.
GIT_AUTHOR_EMAIL	Commit author email.
GIT_COMMITTER_NAME	Commit committer name.
GIT_COMMITTER_EMAIL	Commit committer email.
GIT_REMOTE	Git remote name.
GIT_URL	Git remote URL.
GIT_BRANCH / BRANCH_NAME	Git branch.
GIT_TAG	Git tag.

In addition, each subcommand reads the native variables of its service (for instance CIRCLE_* for Circle-CI, GITHUB_* for GitHub Actions, APPVEYOR_* for AppVeyor, ...). The env subcommand detects the service from CI_NAME (then the generic CI_* variables), from COVERALLS_SERVICE_NAME (then the COVERALLS_* variables), or — failing those — from the native marker variables of the supported services (CIRCLECI, TRAVIS, GITHUB_ACTIONS, ...), in which case that service's own variables are read. The full list for a given service is printed by coveralls <service> --help.

The Coveralls repository token is mandatory: set COVERALLS_REPO_TOKEN, or pass --repo-token.

Logging

Progress is reported through the log crate and the env_logger backend, so the verbosity is controlled with the RUST_LOG environment variable:

RUST_LOG=debug coveralls env coverage.json

Secret values, such as the repository token, are never logged.

Cargo features

The Git metadata of the HEAD commit is collected from the local repository when it is missing from the report or when --force-fetch-git-infos is given. Two backends are available:

• default: the git executable is invoked as a subprocess, so git must be available in the PATH.
• libgit: the repository is read in-process through git2, which removes the dependency on an external git binary.

To build (or install) with the libgit backend:

cargo install coveralls --features libgit

Library usage

This crate is published as a library as well. The whole command line program is exposed through the single coveralls::work entry point:

fn main() {
    if let Err(err) = coveralls::work() {
        eprintln!("{err}");
        std::process::exit(1);
    }
}

For finer grained control, the individual building blocks are available too: Config, Coverage, CoverallsManager, Env and Service. See the API documentation for the details.

That's weird, coveralls-python exists, so why another API client?

The main reason is that coveralls-python can only send the lcov format. In addition, the format produced by grcov does not remove all dependencies.

Indeed, I used Lalrpop in one of my projects, and the generated file was included in the report produced by grcov. Here, we focus on Rust projects and remove all dependencies on demand through a command line argument: dependencies can be included, or filtered — all of them or those matching an expression.

For the moment, we only use the Coveralls format as input, but other formats may be added later.

Roadmap

• Input formats
  • Coveralls
  • Lcov
• Add other entry points of the Coveralls API
• Add comments in the code (with docs)

License

Licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0).