cassetter for Rust
Record and replay outbound HTTP and unary gRPC calls with the same cassette files as the Python, Node, and Go SDKs.
Install
cargo add cassetter reqwest
Add tonic and your generated gRPC client crate when you need gRPC recording. The crate requires Rust 1.88 or newer.
HTTP with reqwest
use ;
use ;
# async
The wrapper buffers request and response bodies. This makes matching
deterministic and reports body read failures before the call returns. Use
Client::inner() to build requests with the wrapped client's configuration.
gRPC with tonic
use ;
use Channel;
use HealthClient;
# async
Pass GrpcService to any generated tonic client that accepts a transport in
its new constructor. Matching uses the full RPC method and exact serialized
protobuf request body. Request metadata is recorded. Response headers and
trailers are merged into the v1 cassette metadata field and exposed in both
places during replay. Non-OK gRPC statuses are recorded and replayed.
Record modes
| Mode | Behavior |
|---|---|
RecordMode::None |
Replay only. A missing or mismatched request fails. |
RecordMode::Once |
Record if the cassette does not exist, otherwise replay only. |
RecordMode::NewEpisodes |
Replay unplayed matches and record everything else. |
RecordMode::All |
Record every request and replace existing interactions. |
RecordMode::Rewrite |
Remove the cassette first and record every request. |
RecordMode::Verify |
Send matched HTTP requests live and fail with Error::ResponseMismatch if the response differs from the recording. |
A session that can record only replays interactions it hasn't played yet, and never replays one it just recorded. A repeated request, like the next turn of a conversation posting to the same URL, reaches the server instead of getting an earlier response back.
Verify
RecordMode::Verify checks a service against a cassette recorded from a reference implementation. Matching works as in RecordMode::None, and a request without a recording fails with Error::NoMatch. A matched request goes live. Its response goes through the same decompression and scrubbing as a recording, then is compared to the recorded one. The cassette is never written.
use ;
#
The status is always compared. headers lists the header names compared by value, with globs. JSON bodies are compared structurally without the json_ignore paths, and numbers within float_tolerance count as equal. sse compares a Server-Sent Events body as its list of data: payloads. Any other body is compared as text or bytes. before_compare_response normalizes (recorded, live) for differences Compare cannot express. A mismatch error carries a unified diff of both responses. gRPC requests replay as in RecordMode::None.
Each Recorder owns independent playback state. Clone one recorder to share a
cassette safely across concurrent tasks. Build separate recorders when tests
must not consume each other's interactions.
Always call Recorder::finish. It saves an empty replacement cassette when
needed and reports persistence failures or calls cancelled while recording.
Current limits
- HTTP request and response bodies are buffered in memory.
- gRPC supports unary calls only. Client-streaming, server-streaming, and bidirectional calls are rejected because the transport requires exactly one framed request and response message.
- Compressed gRPC messages are rejected.
- Protobuf payloads are stored as binary bytes. Header filtering applies to metadata, but body field filtering cannot inspect binary protobuf data. Filter sensitive protobuf fields before they reach the transport. A future descriptor-aware API can add safe field-level filtering.
- The v1 cassette format has one response metadata map. Headers and trailers are merged when recording and replayed in both locations.
- gRPC interactions require YAML. TOML cassettes support HTTP only.