# Add Code Coverage to CI for a Tokio Service

Yes. An agent adds a cargo-llvm-cov job to your Tokio service's CI, measures line coverage with the server tests included, sets a floor just under it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-coverage-to-ci/tokio/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

In a service like tokio-rs/mini-redis, the agent reads `Cargo.toml`: edition 2018, version 0.4.1, `tokio = { version = "1", features = ["full"] }` beside `tokio-stream`, `bytes`, `async-stream`, `atoi`, `clap` 4 with `derive`, `tracing` and `tracing-subscriber`, and four optional OpenTelemetry crates behind an `otel` feature; the one dev-dependency turns on tokio's `test-util`. Two binaries, `mini-redis-cli` at `src/bin/cli.rs` and `mini-redis-server` at `src/bin/server.rs`, sit on a library whose modules are `clients`, `cmd` (`get`, `set`, `ping`, `publish`, `subscribe`, `unknown`), `connection`, `db`, `frame`, `parse`, `server` and `shutdown`, plus four examples. The tests live in `tests/`: `server.rs` speaks raw RESP bytes over a `TcpStream` and its `key_value_timeout` case freezes time with `tokio::time::pause()`; `client.rs` and `buffered_client.rs` each bind a listener on `127.0.0.1:0` and spawn `server::run` in a task; `frame_validation.rs` is synchronous tests of `Frame::check`. No `#[cfg(test)]` module exists under `src/`. `.github/workflows/ci.yml` runs `cargo build`, `cargo build --features otel`, `cargo test`, `cargo test --features otel` and `cargo fmt --all --check` on Ubuntu, macOS and Windows, and `Cargo.lock` is committed.

The tool is `cargo-llvm-cov`, which uses the compiler's own `-C instrument-coverage` on stable with the `llvm-tools-preview` component and needs no nightly for line and region coverage. That matters for this code: the instrumentation is in the compiled test binary, so the server code that `tests/server.rs` drives over a socket counts, and so do the tasks `server::run` spawns per connection, because they run in the same process. Code only reached through a binary's `main`, which here is argument parsing and `set_up_logging` in the two `src/bin/` files, never runs under `cargo test`, so the agent excludes it with `--ignore-filename-regex 'src/bin/'` rather than let two files of zeros drag the total down; examples are not compiled into the test build at all. The command is `cargo llvm-cov --features otel --lcov --output-path lcov.info`, with the feature on so the `#[cfg(feature = "otel")]` paths in `server.rs` are at least compiled, followed by `cargo llvm-cov report --summary-only` for the per-file table.

The agent adds a `coverage` job to `ci.yml`, on `ubuntu-latest` only, since coverage on three operating systems would be the same numbers three times: `dtolnay/rust-toolchain@stable` with `components: llvm-tools-preview`, `taiki-e/install-action@cargo-llvm-cov`, `Swatinem/rust-cache`, the measurement, the summary table written to `$GITHUB_STEP_SUMMARY`, and `lcov.info` uploaded with `actions/upload-artifact` so a reviewer can open it in an editor's coverage view. The job fails under a floor given as `--fail-under-lines`: the agent runs the measurement in its sandbox first and sets the floor a few points below the total it read, so the first run passes and a change that deletes tests or adds a large untested module does not. An optional step sends the report to Codecov when a `CODECOV_TOKEN` secret exists, checked through an `env` value in `if`, so a fork without the secret still passes.

The sandbox run is the evidence. The agent installs the toolchain and the component, runs the command, and reads the table: which of `src/cmd/*.rs`, `connection.rs`, `frame.rs`, `parse.rs` and `db.rs` the socket tests reach and which lines they do not, with the paused-time expiry test counted like any other since instrumentation does not change the test's clock. It runs `cargo test --features otel` once more under the same toolchain to show the suite itself is unchanged, and notes that `cargo-llvm-cov` builds into its own `target/llvm-cov-target` directory, so the cache step is keyed to include it. The pull request pastes the table, names the floor and how it was chosen, and lists the lowest-covered files as the place to add tests next.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add code coverage to CI for this Tokio service. Read Cargo.toml, every file under tests/, src/lib.rs, src/bin/ and .github/workflows/ci.yml first. Use cargo-llvm-cov on the stable toolchain with the llvm-tools-preview component. Exclude the binary entry points under src/bin/ from the measurement, since no test runs them, and enable the same optional features the existing test steps use. Run the measurement in your sandbox, keep the per-file table, and set a line coverage floor a few points below the total you measured. Add a coverage job to the workflow on Ubuntu only that installs the tool, measures, writes the summary table to the job summary, uploads the lcov file as an artifact, fails under the floor, and uploads to Codecov only when a CODECOV_TOKEN secret is present. Open a pull request with the table, the floor and the files with the least coverage.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `.github/workflows/ci.yml` and nothing else. Its description pastes the `cargo llvm-cov report --summary-only` table from the sandbox, states the total line coverage and the floor chosen from it, and lists the files with the least coverage with a sentence on what kind of test would reach each.

The `CI` workflow runs on the pull request with the three existing build-and-test jobs unchanged and the new `coverage` job alongside, whose summary tab shows the same table. The `lcov.info` artifact hangs off the run, and the run's record keeps the sandbox measurement so a reviewer can compare the two.

Before merging, a reviewer decides whether to keep the floor where the agent put it or raise it as tests are added, whether to measure with or without the optional features, and whether the two binary files should count. The tests, the library and the release build are unchanged.

## Run it on every new Rust service repository

A team that starts Rust services from a template sends this body to `POST /o/{org}/sessions` for each new repository, with the repository in `resources` and a `request_id` that is a UUID v5 of its full name, so a retried call returns the run already started rather than opening a second pull request. Each run reads its own `Cargo.toml` and workflow: a workspace gets `--workspace`, a crate with `#[cfg(test)]` modules gets them counted, a crate with no optional features gets no feature flag, and a workflow that already has a Linux job gets the coverage steps appended to it instead of a new job.

The key's `webhook_url` reports each run the key starts with the pull request in `result`. After the floor is in place, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if the coverage job failed on this pull request, say which files lost lines and whether the floor or the change is at fault" turns a red check into a sentence; the trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it.

## Why run it on Rush?

Coverage for an async server is easy to get wrong: a tool that counts only the test process misses code the tests drive through a socket, binaries that never run under `cargo test` pull the number down, and a floor picked without measuring either fails on the first run or guards nothing. The agent measures in its own sandbox with the real toolchain, reads the per-file table before it writes the workflow, and sets the floor from a number it saw.

The table, the toolchain output and the two test runs stay with the run and are quoted in the pull request. A team with several Tokio services gets a coverage job per repository, each fitted to that repository's features and layout, each with its own first measurement on record.

## Frequently asked questions

### Why cargo-llvm-cov rather than tarpaulin?

Because it uses the compiler's source-based instrumentation on stable, works on Linux, macOS and Windows alike, and attributes lines run by spawned tasks and in-process servers to the code that ran them. It needs the `llvm-tools-preview` component and nothing else; branch coverage would need nightly, and the pull request leaves that off.

### Does the paused-time test still work under instrumentation?

Yes. `tokio::time::pause()` controls the runtime's clock, and coverage instrumentation only counts which regions of code execute. The agent runs the full suite under `cargo llvm-cov` and again with plain `cargo test` to show the same tests pass both ways.

### Why exclude src/bin/?

The two files there hold `main`, argument parsing with `clap` and the tracing setup, and no test invokes a binary, so they would report zero lines covered and lower the total without saying anything about the library. The pull request names the regex that excludes them; a reviewer who adds an integration test that spawns the binary can remove it.

### What does the floor do?

`--fail-under-lines` makes the job fail when total line coverage falls under the number, so a pull request that deletes tests or adds a large untested module turns the check red. The agent sets it a few points below what it measured so the first run passes; raising it as tests are added is a one-number change.

## More Tokio jobs

- [Add Criterion Benchmarks to a Tokio Server](https://getrush.ai/run/add-criterion-benchmarks/tokio/)
- [Add Dependabot to a Tokio Project](https://getrush.ai/run/add-dependabot/tokio/)
- [Write a Dockerfile for a Tokio Server](https://getrush.ai/run/add-dockerfile/tokio/)

## The same job on other stacks

- [Add Vitest Coverage to CI for a tRPC and Prisma App](https://getrush.ai/run/add-coverage-to-ci/trpc/)
- [Add Test Coverage Reporting to CI for a TypeScript Library](https://getrush.ai/run/add-coverage-to-ci/typescript-library/)
- [Add Test Coverage to CI for a Vapor App](https://getrush.ai/run/add-coverage-to-ci/vapor/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
