Struct axum_test::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. Such as TestServer::get(), TestServer::post(), and so on.

See that 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 rquest by awaiting the request object.

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

You will receive back a TestResponse.

Cookie Saving

TestRequest::do_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() functions.

Implementations

impl TestRequest

pub fn json<J>(self, body: &J) -> Selfwhere J: ?Sized + Serialize,

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

pub fn form<F>(self, body: &F) -> Selfwhere F: ?Sized + Serialize,

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

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

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

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 content_type(self, content_type: &str) -> Self

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

pub fn add_cookie<'c>(self, cookie: Cookie<'c>) -> 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 do_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) -> Selfwhere V: Serialize,

Adds query parameters to be sent with this request.

pub fn add_query_params<V>(self, query_params: V) -> Selfwhere 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().into_make_service();
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().into_make_service();
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().into_make_service();
let server = TestServer::new(app)?;

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

pub fn clear_query_params(self) -> Self

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

pub fn add_header<'c>(self, name: HeaderName, value: HeaderValue) -> Self

Adds a header to be sent with this request.

pub fn clear_headers(self) -> Self

Clears all headers set.

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::routing::Router;
use ::axum::routing::put;
use ::serde_json::json;

use ::axum_test::TestServer;

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

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.