This runs your application locally, allowing you to query against it with requests. Decode the responses, and assert what is returned.

use axum::Router;
use axum::routing::get;

use axum_test::TestServer;

#[tokio::test]
async fn it_should_ping_pong() {
    // Build an application with a route.
    let app = Router::new()
        .route(&"/ping", get(|| async { "pong!" }));

    // Run the application for testing.
    let server = TestServer::new(app).unwrap();

    // Get the request.
    let response = server
        .get("/ping")
        .await;

    // Assertions.
    response.assert_status_ok();
    response.assert_text("pong!");
}

A TestServer enables you to run an Axum service with a mocked network, or on a random port with real network reqeusts. In both cases allowing you to run multiple servers, across multiple tests, all in parallel.

🎁 Crate Features

Deprecated

⚙️ Axum Compatibility

The current version of Axum Test requires at least Axum v0.8.7.

Here is a list of compatability with prior versions:

📺 Examples

You can find examples of writing tests in the /examples folder. These include tests for:

• a simple REST Todo application, and the same using Shuttle
• a WebSocket ping pong application which sends requests up and down
• a simple WebSocket chat application

🚀 Request Building Features

Querying your application on the TestServer supports all of the common request building you would expect.

• Serializing and deserializing Json, Form, Yaml, and others, using Serde
• Assertions on the Json, text, Yaml, etc, that is returned.
• Cookie, query, and header setting and reading
• Status code reading and assertions

Powerful Json assertions

The ability to assert only the shape of the Json returned:

use axum_test::TestServer;
use axum_test::expect_json;
use std::time::Duration;

// Your application
let app = Router::new()
    .route(&"/user/alan", get(|| async {
        // ...
    }));

let server = TestServer::new(app)?;
server.get(&"/user/alan")
    .await
    .assert_json(&json!({
        "name": "Alan",

        // expect a valid UUID
        "id": expect_json::uuid(),

        // expect an adult age
        "age": expect_json::integer()
                .in_range(18..=120),

        // expect user to be created within the last minute
        "created_at": expect_json::iso_date_time()
                .within_past(Duration::from_secs(60))
                .utc()
    }));

Docs:

• axum_test::TestResponse::assert_json
• axum_test::expect_json

Also includes

• WebSockets testing support
• Saving returned cookies for use on future requests
• Setting headers, query, and cookies, globally for all requests or on per request basis
• Can run requests using a real web server, or with mocked HTTP
• Automatic status assertions for expecting requests to succeed (to help catch bugs in tests sooner)
• Prettified assertion output
• Typed Routing from Axum Extra
• Reqwest integration

❤️ Contributions

A big thank you to all of these who have helped!

Made with contrib.rocks