Axum Test

Easy E2E testing for Axum
including REST, WebSockets, and more

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

Feature	On by default
all	off	Turns on all features.
pretty-assertions	on	Uses the pretty assertions crate on response assert_* methods.
yaml	off	Enables support for sending, receiving, and asserting, yaml content.
msgpack	off	Enables support for sending, receiving, and asserting, msgpack content.
shuttle	off	Enables support for building a TestServer an shuttle_axum::AxumService, for use with Shuttle.rs.
typed-routing	off	Enables support for using TypedPath in requests. See axum-extra for details.
ws	off	Enables WebSocket support. See TestWebSocket for details.
reqwest	off	Enables the TestServer being able to create Reqwest requests for querying.

Axum Compatability

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

Here is a list of compatability with prior versions:

Axum Version	Axum Test Version
0.7.6 to 0.7.9 (latest)	16+ (latest)
0.7.0 to 0.7.5	14, 15
0.6	13.4.1

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

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.