rust-api-test-harness

Rust API Test Harness

Use this skill to make Rust API work test-first, reproducible, and CI-ready.

Prefer black-box tests that exercise the service through HTTP and verify

observable behavior rather than reaching through framework internals.

Core Workflow

1. Inspect the project first: Cargo.toml, workspace layout, existing src/main.rs,

src/lib.rs, router/startup modules, tests/, migrations, Docker Compose,

and CI workflows.

1. Find the application boundary. Extract startup code into a reusable function

if needed so tests can bind a random local port and pass explicit state.

1. Write or update an integration test before changing behavior. Put API tests

under tests/ unless the project already has a clear convention.

1. Create a spawn_app helper that starts the service once per test case,

captures the base URL, and owns any disposable test resources.

1. Exercise the public HTTP contract with reqwest, not framework-specific

request objects, unless the project intentionally uses in-process tests.

1. Isolate state. Use real dependencies when behavior depends on their semantics:

Postgres for SQL behavior, a mock HTTP server for external APIs, and unique

resource names per test.

1. Keep test helpers as production-quality code. Give failures useful messages,

hide boilerplate behind small helper methods, and avoid sleeps when readiness

can be observed.

1. Run the local verification script or equivalent cargo commands before

finishing.

Startup Shape

Prefer a startup function that accepts infrastructure instead of creating it

inside the handler module. Actix can listen on a synchronous

std::net::TcpListener:

pub fn run(
    listener: std::net::TcpListener,
    app_state: AppState,
) -> Result<actix_web::dev::Server, std::io::Error> {
    let state = actix_web::web::Data::new(app_state);
    let server = actix_web::HttpServer::new(move || {
        actix_web::App::new()
            .app_data(state.clone())
            .route("/health_check", actix_web::web::get().to(health_check))
    })
    .listen(listener)?
    .run();

    Ok(server)
}

For Axum, prefer the same boundary but use Tokio's async listener type:

pub fn router(app_state: AppState) -> axum::Router {
    axum::Router::new()
        .route("/health_check", axum::routing::get(health_check))
        .with_state(app_state)
}

pub async fn spawn_axum_app() -> TestApp {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
        .await
        .expect("failed to bind random port");
    let port = listener.local_addr().unwrap().port();
    let server = axum::serve(listener, router(test_state().await));
    let server_handle = tokio::spawn(async move { server.await });

    TestApp {
        address: format!("http://127.0.0.1:{port}"),
        http_client: reqwest::Client::new(),
        server_handle,
    }
}

Test Harness Pattern

Use a helper object instead of repeating setup in every test.

pub struct TestApp {
    pub address: String,
    pub http_client: reqwest::Client,
    pub server_handle: tokio::task::JoinHandle<std::io::Result<()>>,
}

pub async fn spawn_app() -> TestApp {
    let listener = std::net::TcpListener::bind("127.0.0.1:0")
        .expect("failed to bind random port");
    let port = listener.local_addr().unwrap().port();

    let server = my_app::startup::run(listener, test_state().await)
        .expect("failed to start test server");
    let server_handle = tokio::spawn(server);

    TestApp {
        address: format!("http://127.0.0.1:{port}"),
        http_client: reqwest::Client::new(),
        server_handle,
    }
}

Add small helper methods when a multi-step user journey appears in more than

one test. Keep the method names behavior-oriented, for example

post_subscription, login, create_newsletter, or confirm_subscription.

Do not discard the JoinHandle returned by tokio::spawn. Keep it in the test

fixture so tests can detect an unexpectedly finished server task and abort it

during teardown instead of hiding server-side panics behind later

connection-refused errors.

Assertions

• Assert status codes and response headers first.
• Assert persisted side effects through public APIs when possible; query the

database directly only when the public API has no observation point yet.

• Assert negative cases as first-class behavior: missing fields, malformed

payloads, duplicate submissions, unauthorized users, upstream failures, and

timeouts.

• Avoid snapshotting noisy response bodies unless the API contract actually

includes those exact bytes.

State And Dependency Isolation

Read references/database-test-isolation.md when tests touch a database.

Read references/external-http-mocks.md when tests call third-party HTTP APIs.

Default preferences:

• Use real Postgres for Postgres-backed behavior instead of SQLite or in-memory

substitutes.

• Use one logical database, schema, or unique namespace per test when tests can

write shared state.

• Run migrations in setup before the app starts.
• Use wiremock or an equivalent local mock server for external HTTP APIs.
• Configure timeouts aggressively in tests so failures do not hang.

Verification

Run the bundled preflight script from the Rust project root when the standard

cargo workflow applies:

path/to/rust-api-test-harness/scripts/check-rust-service.sh

By default, the script runs:

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Set RUST_API_TEST_HARNESS_SKIP_CLIPPY=1 to skip only the clippy step. The

script still runs formatting and tests. Use this escape hatch when the project

configures linting separately in CI or when --all-targets --all-features is

known to be inappropriate for the local preflight.

If the project does not use all features in CI, mirror the repository's existing

CI commands instead and explain the deviation.

Reference Files

• references/database-test-isolation.md: patterns for Postgres-backed tests,

migrations, per-test databases, and cleanup tradeoffs.

• references/external-http-mocks.md: patterns for testing outbound HTTP

clients and API workflows with local mocks.