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

Axum Compatibility

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

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 thanks to all of these who have helped!

Made with contrib.rocks