# coveralls
[](https://crates.io/crates/coveralls)
[](https://docs.rs/coveralls)
[](LICENSE)
Send a code coverage job to [Coveralls](https://coveralls.io) from a Rust program.
`coveralls` reads a coverage report in the Coveralls JSON format (such as the one produced by
[`grcov`](https://github.com/mozilla/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:
```shell
cargo install coveralls
```
This installs the `coveralls` binary, using the default backend that invokes the `git` command (see
[Cargo features](#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:
```shell
# 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.
# 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:
| `[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:
| 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:
| `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`](https://docs.rs/log) crate and the
[`env_logger`](https://docs.rs/env_logger) backend, so the verbosity is controlled with the
`RUST_LOG` environment variable:
```shell
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`](https://docs.rs/git2), which
removes the dependency on an external `git` binary.
To build (or install) with the `libgit` backend:
```shell
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`](https://docs.rs/coveralls/latest/coveralls/fn.work.html) entry point:
```rust,no_run
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](https://docs.rs/coveralls) for
the details.
## That's weird, [coveralls-python][1] 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
+ [x] Coveralls
+ [ ] Lcov
- [ ] Add other entry points of the Coveralls API
- [x] Add comments in the code (with docs)
## License
Licensed under the [GNU Lesser General Public License v3.0](LICENSE) (LGPL-3.0).
[1]: https://github.com/TheKevJames/coveralls-python