Struct TestRequest

pub struct TestRequest { /* private fields */ }

A TestRequest is for building and executing a HTTP request to the TestServer.

Building

Requests are created by the TestServer, using it’s builder functions. They correspond to the appropriate HTTP method: TestServer::get(), TestServer::post(), etc.

See there for documentation.

Customising

The TestRequest allows the caller to fill in the rest of the request to be sent to the server. Including the headers, the body, cookies, and the content type, using the relevant functions.

The TestRequest struct provides a number of methods to set up the request, such as json, text, bytes, expect_failure, content_type, etc.

Sending

Once fully configured you send the request by awaiting the request object.

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

You will receive a TestResponse.

Cookie Saving

TestRequest::save_cookies() and TestRequest::do_not_save_cookies() methods allow you to set the request to save cookies to the TestServer, for reuse on any future requests.

This behaviour is off by default, and can be changed for all TestRequests when building the TestServer. By building it with a TestServerConfig where save_cookies is set to true.

Expecting Failure and Success

When making a request you can mark it to expect a response within, or outside, of the 2xx range of HTTP status codes.

If the response returns a status code different to what is expected, then it will panic.

This is useful when making multiple requests within a test. As it can find issues earlier than later.

See the TestRequest::expect_failure(), and TestRequest::expect_success().

Implementations

impl TestRequest

pub fn json<J>(self, body: &J) -> Self

where J: ?Sized + Serialize,

Set the body of the request to send up data as Json, and changes the content type to application/json.

pub fn json_from_file<P>(self, path: P) -> Self

where P: AsRef<Path>,

Sends a payload as a Json request, with the contents coming from a file.

pub fn yaml<Y>(self, body: &Y) -> Self

where Y: ?Sized + Serialize,

Available on crate feature yaml only.

Set the body of the request to send up data as Yaml, and changes the content type to application/yaml.

pub fn yaml_from_file<P>(self, path: P) -> Self

where P: AsRef<Path>,

Available on crate feature yaml only.

Sends a payload as a Yaml request, with the contents coming from a file.

pub fn msgpack<M>(self, body: &M) -> Self

where M: ?Sized + Serialize,

Available on crate feature msgpack only.

Set the body of the request to send up data as MsgPack, and changes the content type to application/msgpack.

pub fn form<F>(self, body: &F) -> Self

where F: ?Sized + Serialize,

Sets the body of the request, with the content type of ‘application/x-www-form-urlencoded’.

pub fn multipart(self, multipart: MultipartForm) -> Self

For sending multipart forms. The payload is built using MultipartForm and Part.

This will be sent with the content type of ‘multipart/form-data’.

Simple example

use axum::Router;
use axum_test::TestServer;
use axum_test::multipart::MultipartForm;

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

let multipart_form = MultipartForm::new()
    .add_text("name", "Joe")
    .add_text("animals", "foxes");

let response = server.post(&"/my-form")
    .multipart(multipart_form)
    .await;

Sending byte parts

use axum::Router;
use axum_test::TestServer;
use axum_test::multipart::MultipartForm;
use axum_test::multipart::Part;

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

let image_bytes = include_bytes!("../README.md");
let image_part = Part::bytes(image_bytes.as_slice())
    .file_name(&"README.md")
    .mime_type(&"text/markdown");

let multipart_form = MultipartForm::new()
    .add_part("file", image_part);

let response = server.post(&"/my-form")
    .multipart(multipart_form)
    .await;

pub fn text<T>(self, raw_text: T) -> Self

where T: Display,

Set raw text as the body of the request, and sets the content type to text/plain.

pub fn text_from_file<P>(self, path: P) -> Self

where P: AsRef<Path>,

Sends a payload as plain text, with the contents coming from a file.

pub fn bytes(self, body_bytes: Bytes) -> Self

Set raw bytes as the body of the request.

The content type is left unchanged.

pub fn bytes_from_file<P>(self, path: P) -> Self

where P: AsRef<Path>,

Reads the contents of the file as raw bytes, and sends it within the request.

The content type is left unchanged, and no parsing of the file is done.

pub fn content_type(self, content_type: &str) -> Self

Set the content type to use for this request in the header.

pub fn add_cookie(self, cookie: Cookie<'_>) -> Self

Adds a Cookie to be sent with this request.

pub fn add_cookies(self, cookies: CookieJar) -> Self

Adds many cookies to be used with this request.

pub fn clear_cookies(self) -> Self

Clears all cookies used internally within this Request, including any that came from the TestServer.

pub fn save_cookies(self) -> Self

Any cookies returned will be saved to the TestServer that created this, which will continue to use those cookies on future requests.

pub fn do_not_save_cookies(self) -> Self

Cookies returned by this will not be saved to the TestServer. For use by future requests.

This is the default behaviour. You can change that default in TestServerConfig.

pub fn add_query_param<V>(self, key: &str, value: V) -> Self

where V: Serialize,

Adds query parameters to be sent with this request.

pub fn add_query_params<V>(self, query_params: V) -> Self

where V: Serialize,

Adds the structure given as query parameters for this request.

This is designed to take a list of parameters, or a body of parameters, and then serializes them into the parameters of the request.

Sending a body of parameters using json!

use axum::Router;
use axum_test::TestServer;
use serde_json::json;

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

let response = server.get(&"/my-end-point")
    .add_query_params(json!({
        "username": "Brian",
        "age": 20
    }))
    .await;

Sending a body of parameters with Serde

use axum::Router;
use axum_test::TestServer;
use serde::Deserialize;
use serde::Serialize;

#[derive(Serialize, Deserialize)]
struct UserQueryParams {
    username: String,
    age: u32,
}

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

let response = server.get(&"/my-end-point")
    .add_query_params(UserQueryParams {
        username: "Brian".to_string(),
        age: 20
    })
    .await;

Sending a list of parameters

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

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

let response = server.get(&"/my-end-point")
    .add_query_params(&[
        ("username", "Brian"),
        ("age", "20"),
    ])
    .await;

pub fn add_raw_query_param(self, query_param: &str) -> Self

Adds a query param onto the end of the request, with no urlencoding of any kind.

This exists to allow custom query parameters, such as for the many versions of query param arrays.

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

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

let response = server.get(&"/my-end-point")
    .add_raw_query_param(&"my-flag")
    .add_raw_query_param(&"array[]=123")
    .add_raw_query_param(&"filter[value]=some-value")
    .await;

pub fn clear_query_params(self) -> Self

Clears all query params set, including any that came from the TestServer.

pub fn add_header<N, V>(self, name: N, value: V) -> Self

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

Adds a header to be sent with this request.

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

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

let response = server.get(&"/my-end-point")
    .add_header("x-custom-header", "custom-value")
    .add_header(http::header::CONTENT_LENGTH, 12345)
    .add_header(http::header::HOST, "example.com")
    .await;

pub fn authorization<T>(self, authorization_header: T) -> Self

where T: AsRef<str>,

Adds an ‘AUTHORIZATION’ HTTP header to the request, with no internal formatting of what is given.

pub fn authorization_bearer<T>(self, authorization_bearer_token: T) -> Self

where T: Display,

Adds an ‘AUTHORIZATION’ HTTP header to the request, in the ‘Bearer {token}’ format.

pub fn clear_headers(self) -> Self

Clears all headers set.

pub fn scheme(self, scheme: &str) -> Self

Sets the scheme to use when making the request. i.e. http or https. The default scheme is ‘http’.

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

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

let response = server
    .get(&"/my-end-point")
    .scheme(&"https")
    .await;

pub fn expect_success(self) -> Self

Marks that this request is expected to always return a HTTP status code within the 2xx range (200 to 299).

If a code outside of that range is returned, then this will panic.

use axum::Json;
use axum::Router;
use axum::routing::put;
use serde_json::json;

use axum_test::TestServer;

let app = Router::new()
    .route(&"/todo", put(|| async { unimplemented!() }));

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

// If this doesn't return a value in the 2xx range,
// then it will panic.
server.put(&"/todo")
    .expect_success()
    .json(&json!({
        "task": "buy milk",
    }))
    .await;

pub fn expect_failure(self) -> Self

Marks that this request is expected to return a HTTP status code outside of the 2xx range.

If a code within the 2xx range is returned, then this will panic.

Trait Implementations

impl Debug for TestRequest

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

Formats the value using the given formatter.

impl IntoFuture for TestRequest

type Output = TestResponse

The output that the future will produce on completion.

type IntoFuture = AutoFuture<TestResponse>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.

impl TryFrom<TestRequest> for Request<Body>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(test_request: TestRequest) -> Result<Request<Body>>

Performs the conversion.