Axum Test

Easy E2E testing for applications built on Axum
including REST and WebSockets

Using this library, you can host your application and query against it with requests. Then decode the responses, and assert what is returned.

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

  use ::axum_test::TestServer;

  async fn get_ping() -> &'static str {
      "pong!"
  }

  #[tokio::test]
  async fn it_should_get() {
      // Build an application with a route.
      let app = Router::new()
          .route("/ping", get(get_ping));

      // Run the application for testing.
      let server = TestServer::new(app).unwrap();

      // Get the request.
      let response = server
          .get("/ping")
          .await;

      assert_eq!(response.text(), "pong!");
  }

The TestServer can run requests directly against your application with a mocked network, or the application can run on a random port (with real network reqeusts being made). In both cases allowing multiple servers to run in parallel, across your tests.

This behaviour can be changed in the TestServerConfig, by selecting the transport to be used.

Axum Compatability

Axum Test requires the latest version of Axum (0.7).

Axum Version	Axum Test Version
0.7 (latest)	14, 15+ (latest)
0.6	13.4.1

Crate Features

Here are a list of all features so far that can be enabled:

• all off by default, turns on all features below.
• pretty-assertions on by default, uses the pretty assertions crate for the output to the assert_* functions.
• yaml off by default, adds support for sending, receiving, and asserting, yaml content.
• msgpack off by default, adds support for sending, receiving, and asserting, msgpack content.
• shuttle off by default, adds support for building a TestServer from shuttle_axum::AxumService, for use with Shuttle.rs.
• typed-routing off by default, adds support for the TypedPath from axum-extra.
• ws off by default, adds support for WebSockets.

Examples

You can find examples of writing tests in the /examples folder. These include tests for:

• a simple REST Todo application
• the REST Todo application using Shuttle
• a WebSocket ping pong application which sends requests up and down
• a simple WebSocket chat application

Request Building Features

Querying your application on the TestServer supports all of the common request building you would expect.

• Serializing and deserializing Json and Form content using Serde
• Cookie setting and reading
• Access to setting and reading headers
• Status code reading and assertions
• Assertions for defining what you expect to have returned
• Upgrading a connection for use with WebSockets

It also includes

• Saving cookies returned for use across future requests
• Setting headers and query parameters for use across all TestRequests
• Can optionally run requests using a real web server
• Automatic status assertions for checking requests always succeed or fail
• Prettifying the assertion output
• Typed Routing from Axum Extra

Contributions

A big thanks to all of these who have helped!

Made with contrib.rocks.