# Write Unit Tests for a Tokio Service

Yes. An agent adds unit tests for a Tokio service's frame parser, command parsing and expiring store, using paused time and loopback sockets, and opens a PR.

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

## What the agent does

The agent first separates what is tested from how. In a Tokio service like tokio-rs/mini-redis every existing test is an integration test under `tests/`: `server.rs` starts the server on a loopback port and compares raw protocol bytes, `client.rs` and `buffered_client.rs` drive it through the client types, and `frame_validation.rs` holds a single test for a negative bulk length. Nothing under `src/` has a test module. That leaves the pieces with the most branches untested on their own: `Frame::check` and `Frame::parse` in `src/frame.rs`, the `Parse` cursor in `src/parse.rs`, the expiring key store in `src/db.rs`, the buffering in `src/connection.rs` and the `Shutdown` flag. `Cargo.toml` already enables tokio's `test-util` feature under `[dev-dependencies]`, so paused time is available without adding a crate.

Where each test can live is decided by visibility in `src/lib.rs`. `frame` is a public module, so its tests go in `tests/frame.rs` beside the existing file. `db`, `parse` and `shutdown` are private modules whose functions are `pub(crate)`, so their tests have to be `#[cfg(test)]` modules inside those files. `Frame` derives only `Clone` and `Debug`, with equality defined against `&str` alone, so the tests match on variants instead of comparing frames with `assert_eq`, and the agent reports that deriving `PartialEq` would shorten them without making that change itself.

The frame tests are a table: a simple string, an error, an integer, a bulk string, the null bulk `$-1`, a flat array and a nested one, each checked and then parsed. For every complete frame the agent also feeds each shorter prefix and expects `Error::Incomplete`, which is the contract `Connection::parse_frame` relies on to keep reading from the socket. An unknown type byte must produce the protocol error that names it. The `Parse` tests cover a non-array frame being refused, `next_string` accepting simple and bulk frames and rejecting invalid UTF-8, `next_int` reading an integer frame or digits in a string, `finish` failing when parts remain, and `EndOfStream` once they run out. `Set::parse_frames` gets cases for `EX` in seconds, `PX` in milliseconds, lower-case options and an unknown option.

The store and the socket need a runtime. `Db::new` spawns the purge task, so its tests use `#[tokio::test(start_paused = true)]` and `tokio::time::advance`, the same technique `key_value_timeout` uses over TCP: a key set with an expiry is gone after the clock passes it, a key overwritten with a later expiry survives the first deadline because `set` removes the old entry from `expirations`, and `publish` returns the number of subscribers. `Connection::new` takes a `TcpStream` and not a generic reader, so the agent binds a listener on `127.0.0.1:0` and writes one frame in two halves to prove `read_frame` buffers a partial frame, then closes mid-frame and expects the `connection reset by peer` error. It runs `cargo test`, `cargo test --features otel` and `cargo fmt --all --check` as CI does, measures coverage before and after with `cargo llvm-cov`, and breaks the comparison in `purge_expired_keys` once to show a red test.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Write unit tests for the untested modules of this Tokio service. Read Cargo.toml, .github/workflows/ci.yml, src/lib.rs for module visibility, every file under src/ and the existing tests under tests/ first. Add tests/frame.rs with a table of valid frames (simple, error, integer, bulk, null bulk, array, nested array) run through Frame::check and Frame::parse, a loop that feeds every shorter prefix of each and expects Error::Incomplete, an unknown type byte, and Display output per variant. Add #[cfg(test)] modules inside src/parse.rs, src/db.rs, src/shutdown.rs and src/cmd/set.rs, because those items are pub(crate): Parse construction and each next_ method, Set::parse_frames with EX, PX and an unknown option, Db expiry and overwrite with paused time (start_paused and time::advance), publish with zero and several subscribers, and Shutdown::recv. Add tests/connection.rs that tests Connection::read_frame over a loopback TcpListener with a frame split across two writes, a clean close and a close mid-frame. Add no dependency and change no code outside test modules; list any change that would make testing simpler instead. Run cargo test, cargo test --features otel and cargo fmt --all --check, install cargo-llvm-cov and report line coverage before and after, break purge_expired_keys once to show a failing test, restore it, and open a pull request with the output.",
  "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 adds `tests/frame.rs` and `tests/connection.rs`, since both types are public, and a `#[cfg(test)]` module at the bottom of `src/parse.rs`, `src/db.rs`, `src/shutdown.rs` and `src/cmd/set.rs`. No function body outside those modules changes and `Cargo.toml` is untouched. The description lists the test names `cargo test` printed, the result of the same run with `--features otel`, the format check, line coverage per file before and after from `cargo llvm-cov`, and the failing output from the deliberate break in `purge_expired_keys` followed by the passing run once it is restored.

It also carries a short section of things the agent noticed and did not act on: that `Frame` has no `PartialEq`, and any branch it could reach only through a public function in a way that looks unintended. A reviewer checks that the time-based tests advance the paused clock and never sleep, that every socket test binds port 0 so parallel test threads cannot collide, and that the prefix loop really covers each truncation point. Merging changes nothing at runtime; the existing CI workflow picks the tests up on Linux, macOS and Windows without edits.

## Run it on every Linear issue labelled needs-tests

Create an automation in the Project that holds the repository with a `linear` trigger on `linear.issue.labeled` and `needs-tests` in its `labels`. It needs a Linear connection for whoever runs the automation, made in the console under Settings → Connections, and it fires only when the person who added the label is in your Rush org. The trigger adds the issue after the saved prompt and fills nothing in, so the prompt tells the agent to read the module the issue names, write tests for it in the style above, and open a pull request that mentions the issue.

A team working through a backlog labels one issue per module. Each label starts its own run in its own sandbox, and the automation's max runs per hour decides how many start before the rest wait as queued.

## Why run it on Rush?

Async tests are easy to write badly on a laptop: a `sleep` where the clock should be paused, a fixed port that works until two tests run together, a test that passes because the runtime happened to schedule the purge task first. The agent runs the suite in a clean sandbox as many times as it takes, with and without the optional feature, and then breaks the code on purpose to prove the tests notice. Every command and its output is kept in the run's record, so the pull request arrives with evidence and not only with green ticks.

It reads visibility before it writes, which is what keeps the diff reviewable. Tests land where the language allows them to see the code, nothing is made `pub` for convenience, and no dependency is added because the one the tests need is already in the manifest. A dozen services built on the same runtime get a dozen separate runs, each working from that service's own modules.

## Frequently asked questions

### Do the tests use real time or paused time?

Paused time. Tokio's `test-util` feature lets a test start with the clock stopped and move it forward with `time::advance`, so an expiry of one second is checked without waiting for it and gives the same result on every run. The agent adds the feature under `[dev-dependencies]` only when the manifest does not already have it.

### Why put some tests inside src instead of the tests folder?

Files under `tests/` compile as separate crates and see only the public API. Modules declared without `pub` in `src/lib.rs`, or functions marked `pub(crate)`, can be tested only from a `#[cfg(test)]` module in the same file. The agent chooses per module and changes no visibility.

### Will it need mock sockets or an extra crate?

Not here. The connection type wraps a `TcpStream` directly, so the tests use a real loopback listener on an ephemeral port, as the existing integration tests do. If your connection type is generic over `AsyncRead` and `AsyncWrite`, the agent uses `tokio::io::duplex` and still adds nothing.

### Does it test with every feature flag?

It runs the suite with default features and again with each feature the CI workflow builds, here `--features otel`. A test that compiles only under one feature is gated with the same `cfg` the code uses.

## More Tokio jobs

- [Add cargo-audit to CI for a Tokio Application](https://getrush.ai/run/add-cargo-audit-to-ci/tokio/)
- [Add cargo-deny to a Tokio Project](https://getrush.ai/run/add-cargo-deny/tokio/)
- [Add Clippy to CI for a Tokio Project](https://getrush.ai/run/add-clippy-to-ci/tokio/)

## The same job on other stacks

- [Write Unit Tests for a Vuex Store](https://getrush.ai/run/write-unit-tests/vuex/)
- [Write Unit Tests for an ASP.NET Core Project](https://getrush.ai/run/write-unit-tests/aspnet-core/)
- [Write Unit Tests for an Axum + SQLx API](https://getrush.ai/run/write-unit-tests/axum/)

## 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/)
