axum-test

To perform end-to-end testing for an Axum application, use TestServer to run your service with either a mocked network or on a random port. You can then use the server instance to build requests (e.g., .get(), .post()) and assert against the responses.

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);

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

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

Axum Test provides several optional features to extend its capabilities. By default, only pretty-assertions is enabled.

If you are using axum-extra's TypedPath, axum-test provides a .typed_get() method to facilitate testing these routes. This allows you to pass a struct that implements TypedPath and automatically handles path parameters and query strings.

// Example using a typed path struct
let path = TestingPathQuery { id: 123 }.with_query_params(QueryParams { 
    param: "with-typed-query".to_string(), 
    other: None 
});

server.typed_get(&path)
    .expect_success()
    .await;

Key methods for typed requests:

• .typed_get(&path): Sends a GET request using a typed path.
• .with_query_params(params): Attaches a struct of query parameters to the typed path.
• .add_query_param(key, value): Adds an additional query parameter to the request.
• .clear_query_params(): Removes existing query parameters from the typed path before adding new ones.

To test an Axum application, create a TestServer by passing your Router to TestServer::new(). You can then make requests using HTTP method helpers (like .put(), .get(), etc.) and assert the results using TestResponse methods.

use axum::Router;
use axum::extract::Json;
use axum::routing::put;
use axum_test::TestServer;
use serde_json::json;
use serde_json::Value;

async fn route_put_user(Json(user): Json<Value>) -> () {}

let app = Router::new().route("/users", put(route_put_user));
let server = TestServer::new(app);

let response = server.put("/users")
    .json(&json!({
        "username": "Terrance Pencilworth",
    }))
    .await;

axum-test also supports Actix Web. The usage pattern is identical to Axum: pass an application factory (a closure that returns an App) to TestServer::new().

use actix_web::{App, HttpResponse, web};
use serde_json::{Value, json};
use axum_test::TestServer;

async fn route_put_users(body: web::Json<Value>) -> HttpResponse {
    HttpResponse::Ok().json(json!("done!"))
}

let new_app = || App::new().route("/json", web::put().to(route_put_users));
let server = TestServer::new(new_app);

let response = server.put("/users")
    .json(&json!({
        "username": "Terrance Pencilworth",
    }))
    .await;

The TestServer runs your Axum or Actix application, allowing you to make HTTP requests against it for testing.

Quick Start

For the simplest setup, use TestServer::new(app), where app is an axum::Router or an object implementing IntoMakeService.

Advanced Configuration

Use TestServer::builder() to customize the server behavior, such as choosing between mocked HTTP or real networking, enabling cookie saving, or setting default success expectations.

use axum::Router;
use axum::routing::get;
use axum_test::TestServer;

let app = Router::new()
    .route("/hello", get(|| async { "hello!" }));

// Simple initialization
let server = TestServer::new(app);

// Custom initialization via builder
let mut server = TestServer::builder()
    .http_transport()
    .expect_success_by_default()
    .save_cookies()
    .build(app);

A TestRequest is used to construct and execute HTTP requests against a TestServer. You create requests using the builder methods on a TestServer instance (e.g., .get(), .post(), .put(), .delete()). Once the request is configured with headers, bodies, or cookies, you execute it by awaiting the TestRequest object, which returns a TestResponse.

# async fn test() -> Result<(), Box<dyn ::std::error::Error>> {
# use axum::Router;
# use axum_test::TestServer;
#
# let server = TestServer::new(Router::new());
#
// Build your request
let request = server.get(&"/user")
    .add_header("x-custom-header", "example.com")
    .content_type("application/yaml");

// await request to execute
let response = request.await;
#
# Ok(()) }

This example demonstrates how to use axum-test to test WebSocket connections in an Actix Web application. It covers two primary scenarios:

1. Starting a WebSocket connection: Writing a basic test that successfully establishes a WebSocket handshake.
2. Ping Pong testing: Verifying bidirectional data flow by pushing data up and down the connection (sending a message and asserting the response).