Expand description
Axum Test is a library for writing tests for web servers written using Axum.
- You can spin up a
TestServer
within a test. - Create requests that will run against that.
- Retrieve what they happen to return.
- Assert that the response works how you expect.
It icludes built in suppot with Serde, Cookies, and other common crates for working with the web.
Getting Started
In essence; create your Axum application, create a TestServer
,
and then make requests against 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)
.unwrap();
let response = server.put("/users")
.json(&json!({
"username": "Terrance Pencilworth",
}))
.await;
Features
Auto Cookie Saving 🍪
When you build a TestServer
, you can turn on a feature to automatically save cookies
across requests. This is used for automatically saving things like session cookies.
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)
.unwrap();
Then when you make a request, any cookies that are returned will be reused by the next request. This is on a per server basis (it doesn’t save across servers).
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)
.unwrap();
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)
.unwrap();
let response = server.put("/users")
.content_type(&"application/json")
.json(&json!({
"username": "Terrance Pencilworth",
}))
.await;
Fail Fast
This library is written to panic quickly. For example by default a response will presume to succeed and will panic if they don’t (which you can change). Functions to retreive cookies and headers will by default panic if they aren’t found.
This behaviour is unorthodox for Rust, however it is intentional to aid with writing tests. Where you want the test to fail as quickly, and skip on writing error handling code.
Re-exports
pub use ::hyper::http;
Modules
Structs
- A
TestRequest
represents a HTTP request to the test server. - The
TestResponse
represents the result of aTestRequest
. It is returned when you call await on aTestRequest
object. - The
TestServer
represents your application, running as a web server, and you can make web requests to your application. - The basic setup for the
TestServer
.
Traits
- This exists to gloss over the differences between Axum’s
IntoMakeService
andIntoMakeServiceWithConnectInfo
types. In theory it also allows others as well.