Crate axum_test

source ·
Expand description

Axum Test is a library for writing tests for web servers written using Axum:

  • You create a TestServer within a test,
  • use that to build TestRequest against your application,
  • receive back a TestResponse,
  • then assert the response is how you expect.

It includes built in suppot for serializing and deserializing request and response bodies using Serde, support for cookies and headers, and other common bits you would expect.

Getting Started

Create a TestServer running your Axum Router:

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>) -> () {
    // todo
}

let my_app = Router::new()
    .route("/users", put(route_put_user))
    .into_make_service();

let server = TestServer::new(my_app)?;

It will be running on a random address, allowing many to be run in parallel across tests.

Then make requests against it:

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

Features

Auto Cookie Saving 🍪

This feature allows the server to save cookies and reuse these on future requests. For example saving session cookies, like a browser would.

This feature is disabled by default, and can be enabled by setting save_cookies to true on the TestServerConfig, and passing this to the TestServer on construction.

use ::axum::Router;
use ::axum_test::TestServer;
use ::axum_test::TestServerConfig;

let my_app = Router::new()
    .into_make_service();

let config = TestServerConfig {
    save_cookies: true,
    ..TestServerConfig::default()
};

let server = TestServer::new_with_config(my_app, config)?;

When you make a request, any cookies returned will be reused by the next request, created by that same server.

You can turn this on or off per request, using TestRequest::do_save_cookies and TestRequest::do_not_save_cookies.

Content Type 📇

When performing a request, it will start with no content type at all.

You can set a default type for all TestRequest objects to use, by setting the default_content_type in the TestServerConfig. When creating the TestServer instance, using new_with_config.

use ::axum::Router;
use ::axum_test::TestServer;
use ::axum_test::TestServerConfig;

let my_app = Router::new()
    .into_make_service();

let config = TestServerConfig {
    default_content_type: Some("application/json".to_string()),
    ..TestServerConfig::default()
};

let server = TestServer::new_with_config(my_app, config)?;

If there is no default, then a TestRequest will try to guess the content type. Such as setting application/json when calling TestRequest::json, and text/plain when calling TestRequest::text. This will never override any default content type provided.

Finally on each TestRequest, one can set the content type to use. By calling TestRequest::content_type on it.

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 put_user(Json(user): Json<Value>) -> () {
    // todo
}

let my_app = Router::new()
    .route("/users", put(put_user))
    .into_make_service();

let server = TestServer::new(my_app)?;

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

Fail Fast ⚡️

This library includes a mode to have requests panic if they are outside of the 2xx range, unless marked by calling TestRequest::expect_failure(). This is intentional to aid with writing tests. To help catch errors quickly when making code changes.

This behaviour is off by default, and can be enabled by setting TestServerConfig::expect_success_by_default to true when creating a new TestServer.

Re-exports

Modules

Structs

Traits