mockito-http-mocking - HTTP API Mocking in Rust Tests

mockito spins up a real local HTTP server per test and matches incoming requests against declared mocks. Two of its semantics are routinely misread, and one interaction with polling clients produces hangs that only appear under concurrent load. All three were debugged live against a teloxide long-polling bot (truenas-ai-sentinel PR #12); the patterns apply to any Rust client that re-requests an endpoint in a loop.

When to Use This Skill

Use this skill when...	Use sibling skill instead when...
Mocking an HTTP API (Bot APIs, REST backends) in integration tests	Running/parallelizing the tests -- use `cargo-nextest`
A `matched()` wait loop hangs or a mock "never gets hit"	Authoring async test code in general -- use `rust-development`
Tests pass alone but hang/flake when the suite runs concurrently	Measuring coverage of the tests -- use `cargo-llvm-cov`
Layering specific and catch-all mocks on one path

Semantics That Bite

1. `matched()` means "hit count EQUALS the expectation" — not "was hit"

The default expectation is exactly 1. A mock hit twice makes matched() return false again, so a wait-until-matched loop that raced past one hit silently un-matches:

// Wrong for anything a client may hit repeatedly: matched() flips back
// to false on the second hit.
let m = server.mock("POST", "/x").with_body("ok").create_async().await;

// Right: "at least once" is what a readiness wait actually means.
let m = server.mock("POST", "/x").with_body("ok")
    .expect_at_least(1).create_async().await;
while !m.matched_async().await { tokio::time::sleep(Duration::from_millis(50)).await; }

Reserve exact expect(n) / expect(0) for the final assert_async() after the client has been stopped — expect(0) plus a settle delay is the correct shape for "this endpoint must never be called".

2. Mocks match in creation order — first match wins

When several mocks cover the same method + path, mockito uses the first created mock whose matchers accept the request. Create specific body-matched mocks before the catch-all:

// Specific first: requests carrying {"offset":2} get the empty response...
let drained = server.mock("POST", "/api/poll")
    .match_body(Matcher::PartialJsonString(r#"{"offset":2}"#.into()))
    .with_body(r#"{"ok":true,"result":[]}"#)
    .create_async().await;
// ...everything else falls through to the catch-all batch.
let batch = server.mock("POST", "/api/poll")
    .with_body(one_update_json())
    .create_async().await;

Matcher::PartialJsonString compares values, not just keys — {"offset":0,...} does not match a {"offset":2} partial. Verify with a raw reqwest probe when in doubt; guessing the matching semantics from a failing dispatcher test conflates several failure modes.

Polling Clients Against an Instant Mock Server

Real long polling holds the HTTP connection server-side. mockito responds instantly, so a long-poll client (getUpdates-style loops, SQS-style receive loops) degenerates into a hot request loop at ~100% CPU. Two consequences:

The flood starves everything sharing the runtime/machine — tests that pass in isolation hang under concurrent suite load (the tell: cargo nextest run --test x <one_test> passes in milliseconds, the full run gets killed after minutes with SIGTERM, and ps shows the test binary spinning at 100% CPU).
Graceful-shutdown paths that wait for the poll loop to notice a stop flag may never get scheduled.

Fix A: make the "drained" mock trigger the client's error backoff

Respond 500 on the post-consumption poll request. Well-behaved clients (teloxide, most SDKs) back off exponentially on errors, turning the hot loop into a gentle retry — while the mock still counts as matched, which is usually the "update was consumed" signal the test waits on:

let drained = server.mock("POST", "/api/poll")
    .match_body(Matcher::PartialJsonString(r#"{"offset":2}"#.into()))
    .with_status(500)
    .with_body(r#"{"ok":false,"error_code":500,"description":"drained (test backoff)"}"#)
    .expect_at_least(1)
    .create_async().await;

Fix B: `task.abort()` instead of graceful shutdown in tests

A test does not need to prove graceful shutdown on every run. After the awaited assertion signal fires, cancel the client task outright:

wait_until_matched(&send).await;
task.abort();
let _ = task.await;            // JoinError::is_cancelled — expected
send.assert_async().await;

Keep one dedicated test for graceful shutdown if the shutdown path itself is under test; don't pay its flake risk in every dispatcher test.

Client-Specific Notes

teloxide Polling sends {"offset":0,"timeout":N} on its first request — the offset field is present, not absent. Body matchers and "no offset yet" assumptions must account for it. Method paths are PascalCase: /bot<token>/GetUpdates, /GetMe, /SendMessage.
Dispatcher-driven bots fetch GetMe at startup — mock it or the dispatcher never polls.

Diagnosis Checklist

Symptom	Likely cause
Wait loop times out though the endpoint was clearly called	`matched()` vs expectation mismatch — use `expect_at_least(1)`
Specific mock never matches; catch-all serves everything	Catch-all was created first — reorder
Test passes alone, hangs in the full suite; binary at 100% CPU	Hot poll loop — apply Fix A + Fix B
Client errors repeatedly right after startup	A required bootstrap call (e.g. `GetMe`) has no mock

When the failure resists reasoning, probe empirically: point the client at a raw tokio::net::TcpListener that logs request lines and bodies — five minutes of captured traffic beats an hour of guessing what the client sends.

mockito-http-mocking