Struct TestResponse

pub struct TestResponse { /* private fields */ }

The TestResponse is the result of a request created using a TestServer. The TestServer builds a TestRequest, which when awaited, will produce the response.

use axum::Json;
use axum::Router;
use axum::routing::get;
use axum_test::TestServer;
use serde::Deserialize;
use serde::Serialize;

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

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

// This builds a `TestResponse`
let response = server.get(&"/todo").await;

Extracting Response

The functions TestResponse::json(), TestResponse::text(), and TestResponse::form(), allow you to extract the underlying response content in different formats.

let todo_response = server.get(&"/todo")
        .await
        .json::<Todo>();

let response_as_raw_text = server.get(&"/todo")
        .await
        .text();

TestResponse::as_bytes() and TestResponse::into_bytes(), offer the underlying raw bytes to allow custom decoding.

Full code examples can be found within their documentation.

Assertions

The result of a response can also be asserted using the many assertion functions.

use axum::Json;
use axum::Router;
use axum_test::TestServer;
use axum::routing::get;
use serde::Deserialize;
use serde::Serialize;

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

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

let response = server.get(&"/todo").await;

// These assertions will panic if they are not fulfilled by the response.
response.assert_status_ok();
response.assert_text("hello!");

Implementations

impl TestResponse

pub fn text(&self) -> String

Returns the underlying response, extracted as a UTF-8 string.

Example

use axum::Json;
use axum::Router;
use axum::routing::get;
use serde_json::json;
use serde_json::Value;

use axum_test::TestServer;

async fn route_get_todo() -> Json<Value> {
    Json(json!({
        "description": "buy milk",
    }))
}

let app = Router::new()
    .route(&"/todo", get(route_get_todo));

let server = TestServer::new(app)?;
let response = server.get(&"/todo").await;

// Extract the response as a string on it's own.
let raw_text = response.text();

pub fn json<T>(&self) -> T

where T: DeserializeOwned,

Deserializes the response, as Json, into the type given.

If deserialization fails then this will panic.

Example

use axum::Json;
use axum::Router;
use axum::routing::get;
use serde::Deserialize;
use serde::Serialize;

use axum_test::TestServer;

#[derive(Serialize, Deserialize, Debug)]
struct Todo {
    description: String,
}

async fn route_get_todo() -> Json<Todo> {
    Json(Todo {
        description: "buy milk".to_string(),
    })
}

let app = Router::new()
    .route(&"/todo", get(route_get_todo));

let server = TestServer::new(app)?;
let response = server.get(&"/todo").await;

// Extract the response as a `Todo` item.
let todo = response.json::<Todo>();

pub fn yaml<T>(&self) -> T

where T: DeserializeOwned,

Available on crate feature yaml only.

Deserializes the response, as Yaml, into the type given.

If deserialization fails then this will panic.

Example

use axum::Router;
use axum::routing::get;
use axum_yaml::Yaml;
use serde::Deserialize;
use serde::Serialize;

use axum_test::TestServer;

#[derive(Serialize, Deserialize, Debug)]
struct Todo {
    description: String,
}

async fn route_get_todo() -> Yaml<Todo> {
    Yaml(Todo {
        description: "buy milk".to_string(),
    })
}

let app = Router::new()
    .route(&"/todo", get(route_get_todo));

let server = TestServer::new(app)?;
let response = server.get(&"/todo").await;

// Extract the response as a `Todo` item.
let todo = response.yaml::<Todo>();

pub fn msgpack<T>(&self) -> T

where T: DeserializeOwned,

Available on crate feature msgpack only.

Deserializes the response, as MsgPack, into the type given.

If deserialization fails then this will panic.

Example

use axum::Router;
use axum::routing::get;
use axum_msgpack::MsgPack;
use serde::Deserialize;
use serde::Serialize;

use axum_test::TestServer;

#[derive(Serialize, Deserialize, Debug)]
struct Todo {
    description: String,
}

async fn route_get_todo() -> MsgPack<Todo> {
    MsgPack(Todo {
        description: "buy milk".to_string(),
    })
}

let app = Router::new()
    .route(&"/todo", get(route_get_todo));

let server = TestServer::new(app)?;
let response = server.get(&"/todo").await;

// Extract the response as a `Todo` item.
let todo = response.msgpack::<Todo>();

pub fn form<T>(&self) -> T

where T: DeserializeOwned,

Deserializes the response, as an urlencoded Form, into the type given.

If deserialization fails then this will panic.

Example

use axum::Form;
use axum::Router;
use axum::routing::get;
use serde::Deserialize;
use serde::Serialize;

use axum_test::TestServer;

#[derive(Serialize, Deserialize, Debug)]
struct Todo {
    description: String,
}

async fn route_get_todo() -> Form<Todo> {
    Form(Todo {
        description: "buy milk".to_string(),
    })
}

let app = Router::new()
    .route(&"/todo", get(route_get_todo));

let server = TestServer::new(app)?;
let response = server.get(&"/todo").await;

// Extract the response as a `Todo` item.
let todo = response.form::<Todo>();

pub fn as_bytes(&self) -> &Bytes

Returns the raw underlying response as Bytes.

pub fn into_bytes(self) -> Bytes

Consumes this returning the underlying Bytes in the response.

pub fn status_code(&self) -> StatusCode

The status_code of the response.

pub fn request_method(&self) -> Method

The Method used to produce this response.

pub fn request_url(&self) -> Url

The full URL that was used to produce this response.

pub fn maybe_header<N>(&self, name: N) -> Option<HeaderValue>

where N: TryInto<HeaderName>, N::Error: Debug,

Finds a header with the given name. If there are multiple headers with the same name, then only the first HeaderValue will be returned.

None is returned when no header was found.

pub fn headers(&self) -> &HeaderMap<HeaderValue>

Returns the headers returned from the response.

pub fn maybe_content_type(&self) -> Option<String>

pub fn content_type(&self) -> String

pub fn header<N>(&self, name: N) -> HeaderValue

where N: TryInto<HeaderName> + Display + Clone, N::Error: Debug,

Finds a header with the given name. If there are multiple headers with the same name, then only the first will be returned.

If no header is found, then this will panic.

pub fn iter_headers(&self) -> impl Iterator<Item = (&HeaderName, &HeaderValue)>

Iterates over all of the headers contained in the response.

pub fn iter_headers_by_name<N>( &self, name: N, ) -> impl Iterator<Item = &HeaderValue>

where N: TryInto<HeaderName>, N::Error: Debug,

Iterates over all of the headers for a specific name, contained in the response.

pub fn contains_header<N>(&self, name: N) -> bool

where N: TryInto<HeaderName>, N::Error: Debug,

pub fn assert_contains_header<N>(&self, name: N)

where N: TryInto<HeaderName> + Display + Clone, N::Error: Debug,

Asserts the header named is present in the response.

If the header is not present, then the assertion fails.

pub fn assert_header<N, V>(&self, name: N, value: V)

where N: TryInto<HeaderName> + Display + Clone, N::Error: Debug, V: TryInto<HeaderValue>, V::Error: Debug,

pub fn maybe_cookie(&self, cookie_name: &str) -> Option<Cookie<'static>>

Finds a Cookie with the given name. If there are multiple matching cookies, then only the first will be returned.

None is returned if no Cookie is found.

pub fn cookie(&self, cookie_name: &str) -> Cookie<'static>

Finds a Cookie with the given name. If there are multiple matching cookies, then only the first will be returned.

If no Cookie is found, then this will panic.

pub fn cookies(&self) -> CookieJar

Returns all of the cookies contained in the response, within a CookieJar object.

See the cookie crate for details.

pub fn iter_cookies(&self) -> impl Iterator<Item = Cookie<'_>>

Iterate over all of the cookies in the response.

pub async fn into_websocket(self) -> TestWebSocket

Available on crate feature ws only.

Consumes the request, turning it into a TestWebSocket. If this cannot be done, then the response will panic.

Note, this requires the server to be running on a real HTTP port. Either using a randomly assigned port, or a specified one. See the TestServerConfig::transport for more details.

Example

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

let app = Router::new();
let server = TestServer::builder()
    .http_transport()
    .build(app)?;

let mut websocket = server
    .get_websocket(&"/my-web-socket-end-point")
    .await
    .into_websocket()
    .await;

websocket.send_text("Hello!").await;

pub fn assert_text<C>(&self, expected: C)

where C: AsRef<str>,

This performs an assertion comparing the whole body of the response, against the text provided.

pub fn assert_text_contains<C>(&self, expected: C)

where C: AsRef<str>,

This asserts if the text given is contained, somewhere, within the response.

pub fn assert_text_from_file<P>(&self, path: P)

where P: AsRef<Path>,

Asserts the response from the server matches the contents of the file.

pub fn assert_json<T>(&self, expected: &T)

where T: DeserializeOwned + PartialEq<T> + Debug,

Deserializes the contents of the request as Json, and asserts it matches the value given.

If other does not match, or the response is not Json, then this will panic.

pub fn assert_json_contains<T>(&self, expected: &T)

where T: Serialize,

Asserts the content is within the json returned. This is useful for when servers return times and IDs that you wish to ignore.

use axum::Router;
use axum::extract::Json;
use axum::routing::get;
use axum_test::TestServer;
use serde_json::json;
use std::time::Instant;

let app = Router::new()
    .route(&"/user", get(|| async {
        let id = Instant::now().elapsed().as_millis();

        Json(json!({
           "id": id,
           "name": "Joe",
           "age": 20,
       }))
    }));
let server = TestServer::new(app)?;

// Checks the response contains _only_ the values listed here,
// and ignores the rest.
server.get(&"/user")
    .await
    .assert_json_contains(&json!({
        "name": "Joe",
        "age": 20,
    }));

pub fn assert_json_from_file<P>(&self, path: P)

where P: AsRef<Path>,

Read json file from given path and assert it with json response.

use axum::Json;
use axum::routing::get;
use axum::routing::Router;
use axum_test::TestServer;
use serde_json::json;

let app = Router::new()
    .route(&"/json", get(|| async {
        Json(json!({
            "name": "Joe",
            "age": 20,
        }))
    }));

let server = TestServer::new(app).unwrap();
server
    .get(&"/json")
    .await
    .assert_json_from_file("files/example.json");

pub fn assert_yaml<T>(&self, other: &T)

where T: DeserializeOwned + PartialEq<T> + Debug,

Available on crate feature yaml only.

Deserializes the contents of the request as Yaml, and asserts it matches the value given.

If other does not match, or the response is not Yaml, then this will panic.

pub fn assert_yaml_from_file<P>(&self, path: P)

where P: AsRef<Path>,

Available on crate feature yaml only.

Read yaml file from given path and assert it with yaml response.

pub fn assert_msgpack<T>(&self, other: &T)

where T: DeserializeOwned + PartialEq<T> + Debug,

Available on crate feature msgpack only.

Deserializes the contents of the request as MsgPack, and asserts it matches the value given.

If other does not match, or the response is not MsgPack, then this will panic.

pub fn assert_form<T>(&self, other: &T)

where T: DeserializeOwned + PartialEq<T> + Debug,

Deserializes the contents of the request as an url encoded form, and asserts it matches the value given.

If other does not match, or the response cannot be deserialized, then this will panic.

pub fn assert_status(&self, expected_status_code: StatusCode)

Assert the response status code matches the one given.

pub fn assert_not_status(&self, expected_status_code: StatusCode)

Assert the response status code does not match the one given.

pub fn assert_status_success(&self)

Assert that the status code is within the 2xx range. i.e. The range from 200-299.

pub fn assert_status_failure(&self)

Assert that the status code is outside the 2xx range. i.e. A status code less than 200, or 300 or more.

pub fn assert_status_in_range<R, S>(&self, expected_status_range: R)

where R: RangeBounds<S> + TryIntoRangeBounds<StatusCode> + Debug, S: TryInto<StatusCode>,

Assert the status code is within the range given.

use axum::Json;
use axum::routing::get;
use axum::routing::Router;
use axum_test::TestServer;
use http::StatusCode;

let app = Router::new()
    .route(&"/json", get(|| async {
        StatusCode::OK
    }));
let server = TestServer::new(app).unwrap();

// Within success statuses
server
    .get(&"/json")
    .await
    .assert_status_in_range(200..=299);

// Outside success
server
    .get(&"/json")
    .await
    .assert_status_in_range(300..);

// Before server error
server
    .get(&"/json")
    .await
    .assert_status_in_range(..StatusCode::INTERNAL_SERVER_ERROR);

pub fn assert_status_not_in_range<R, S>(&self, expected_status_range: R)

where R: RangeBounds<S> + TryIntoRangeBounds<StatusCode> + Debug, S: TryInto<StatusCode>,

Assert the status code is not within the range given.

use axum::Json;
use axum::routing::get;
use axum::routing::Router;
use axum_test::TestServer;
use http::StatusCode;

let app = Router::new()
    .route(&"/json", get(|| async {
        StatusCode::NOT_FOUND
    }));
let server = TestServer::new(app).unwrap();

// Is not success
server
    .get(&"/json")
    .await
    .assert_status_not_in_range(200..=299);

// 300 or higher
server
    .get(&"/json")
    .await
    .assert_status_not_in_range(300..);

// After server error
server
    .get(&"/json")
    .await
    .assert_status_not_in_range(..StatusCode::INTERNAL_SERVER_ERROR);

pub fn assert_status_ok(&self)

Assert the response status code is 200.

pub fn assert_status_not_ok(&self)

Assert the response status code is not 200.

pub fn assert_status_see_other(&self)

Assert the response status code is 303.

pub fn assert_status_bad_request(&self)

Assert the response status code is 400.

pub fn assert_status_not_found(&self)

Assert the response status code is 404.

pub fn assert_status_unauthorized(&self)

Assert the response status code is 401.

pub fn assert_status_forbidden(&self)

Assert the response status code is 403.

pub fn assert_status_conflict(&self)

Assert the response status code is 409.

pub fn assert_status_payload_too_large(&self)

Assert the response status code is 413.

The payload is too large.

pub fn assert_status_unprocessable_entity(&self)

Assert the response status code is 422.

pub fn assert_status_too_many_requests(&self)

Assert the response status code is 429.

pub fn assert_status_switching_protocols(&self)

Assert the response status code is 101.

This type of code is used in Web Socket connection when first request.

pub fn assert_status_internal_server_error(&self)

Assert the response status code is 500.

pub fn assert_status_service_unavailable(&self)

Assert the response status code is 503.

Trait Implementations

impl Clone for TestResponse

fn clone(&self) -> TestResponse

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TestResponse

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<TestResponse> for Bytes

fn from(response: TestResponse) -> Self

Converts to this type from the input type.