Struct TestServer 

pub struct TestServer { /* private fields */ }

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

Building

A TestServer can be used to run an axum::Router, an ::axum::routing::IntoMakeService, a [shuttle_axum::ShuttleAxum], and others.

The most straight forward approach is to call crate::TestServer::new, and pass in your application:

use axum::Router;
use axum::routing::get;

use axum_test::TestServer;

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

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

Requests

Requests are built by calling TestServer::get(), TestServer::post(), TestServer::put(), TestServer::delete(), and TestServer::patch() methods. Each returns a TestRequest, which allows for customising the request content.

For example:

use axum::Router;
use axum::routing::get;

use axum_test::TestServer;

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

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

let response = server.get(&"/hello")
    .authorization_bearer("password12345")
    .add_header("x-custom-header", "custom-value")
    .await;

response.assert_text("hello!");

Request methods also exist for using Axum Extra [axum_extra::routing::TypedPath], or for building Reqwest [reqwest::RequestBuilder]. See those methods for detauls.

Customising

A TestServer can be built from a builder, by calling crate::TestServer::builder, and customising settings. This allows one to set mocked (default when possible) or real http networking for your service.

use axum::Router;
use axum::routing::get;

use axum_test::TestServer;

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

// Customise server when building
let mut server = TestServer::builder()
    .http_transport()
    .expect_success_by_default()
    .save_cookies()
    .build(app)?;

// Add items to be sent on _all_ all requests
server.add_header("x-custom-for-all", "common-value");

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

Implementations

impl TestServer

pub fn builder() -> TestServerBuilder

A helper function to create a builder for creating a TestServer.

pub fn new<A>(app: A) -> Result<TestServer, Error>

where A: IntoTransportLayer,

This will run the given Axum app, allowing you to make requests against it.

This is the same as creating a new TestServer with a configuration, and passing crate::TestServerConfig::default().

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

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

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

The of applications that can be passed in include:

• axum::Router
• axum::routing::IntoMakeService
• axum::extract::connect_info::IntoMakeServiceWithConnectInfo
• axum::serve::Serve
• axum::serve::WithGracefulShutdown
• [shuttle_axum::ShuttleAxum]

pub fn new_with_config<A, C>(app: A, config: C) -> Result<TestServer, Error>

where A: IntoTransportLayer, C: Into<TestServerConfig>,

Similar to TestServer::new(), with a customised configuration. This includes type of transport in use (i.e. specify a specific port), or change default settings (like the default content type for requests).

This can take a crate::TestServerConfig or a crate::TestServerBuilder. See those for more information on configuration settings.

pub fn get(&self, path: &str) -> TestRequest

Creates a HTTP GET request to the path.

pub fn post(&self, path: &str) -> TestRequest

Creates a HTTP POST request to the given path.

pub fn patch(&self, path: &str) -> TestRequest

Creates a HTTP PATCH request to the path.

pub fn put(&self, path: &str) -> TestRequest

Creates a HTTP PUT request to the path.

pub fn delete(&self, path: &str) -> TestRequest

Creates a HTTP DELETE request to the path.

pub fn method(&self, method: Method, path: &str) -> TestRequest

Creates a HTTP request, to the method and path provided.

pub fn server_address(&self) -> Option<Url>

Returns the local web address for the test server, if an address is available.

The address is available when running as a real web server, by setting the TestServerConfig transport field to Transport::HttpRandomPort or Transport::HttpIpPort.

This will return None when there is mock HTTP transport (the default).

pub fn server_url(&self, path: &str) -> Result<Url, Error>

This turns a relative path, into an absolute path to the server. i.e. A path like /users/123 will become something like http://127.0.0.1:1234/users/123.

The absolute address can be used to make requests to the running server, using any appropriate client you wish.

Example

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

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

let full_url = server.server_url(&"/users/123?filter=enabled")?;

// Prints something like ... http://127.0.0.1:1234/users/123?filter=enabled
println!("{full_url}");

This will return an error if you are using the mock transport. Real HTTP transport is required to use this method (see TestServerConfig transport field).

It will also return an error if you provide an absolute path, for example if you pass in http://google.com.

pub fn add_cookie(&mut self, cookie: Cookie<'_>)

Adds a single cookie to be included on all future requests.

If a cookie with the same name already exists, then it will be replaced.

pub fn add_cookies(&mut self, cookies: CookieJar)

Adds extra cookies to be used on all future requests.

Any cookies which have the same name as the new cookies, will get replaced.

pub fn clear_cookies(&mut self)

Clears all of the cookies stored internally.

pub fn save_cookies(&mut self)

Requests made using this TestServer will save their cookies for future requests to send.

This behaviour is off by default.

pub fn do_not_save_cookies(&mut self)

Requests made using this TestServer will not save their cookies for future requests to send up.

This is the default behaviour.

pub fn expect_success(&mut self)

Requests made using this TestServer will assert a HTTP status in the 2xx range will be returned, unless marked otherwise.

By default this behaviour is off.

pub fn expect_failure(&mut self)

Requests made using this TestServer will assert a HTTP status is outside the 2xx range will be returned, unless marked otherwise.

By default this behaviour is off.

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

where V: Serialize,

Adds a query parameter to be sent on all future requests.

pub fn add_query_params<V>(&mut self, query_params: V)

where V: Serialize,

Adds query parameters to be sent on all future requests.

pub fn add_raw_query_param(&mut self, raw_query_param: &str)

Adds a raw query param, with no urlencoding of any kind, to be send on all future requests.

pub fn clear_query_params(&mut self)

Clears all query params set.

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

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

Adds a header to be sent with all future requests built from this TestServer.

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

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

server.add_header("x-custom-header", "custom-value");
server.add_header(http::header::CONTENT_LENGTH, 12345);
server.add_header(http::header::HOST, "example.com");

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

pub fn clear_headers(&mut self)

Clears all headers set so far.

pub fn scheme(&mut self, scheme: &str)

Sets the scheme to use when making all requests from the TestServer. i.e. http or https.

The default scheme is ‘http’.

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

let app = Router::new();
let mut server = TestServer::new(app)?;
server
    .scheme(&"https");

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

pub fn is_running(&self) -> bool

Returns true or false if the underlying service inside the TestServer is still running. For many types of services this will always return true.

When a TestServer is built using axum::serve::WithGracefulShutdown, this will return false if the service has shutdown.

Trait Implementations

impl Debug for TestServer

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

Formats the value using the given formatter.