axum-test 16.4.0

For spinning up and testing Axum servers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

<div align="center">
  <h1>
    Axum Test
  </h1>

  <h3>
    Easy E2E testing for Axum<br/>
    including REST, WebSockets, and more
  </h3>

  [![crate](https://img.shields.io/crates/v/axum-test.svg)](https://crates.io/crates/axum-test)
  [![docs](https://docs.rs/axum-test/badge.svg)](https://docs.rs/axum-test)

  <br/>
</div>

This runs your application locally, allowing you to query against it with requests.
Decode the responses, and assert what is returned.

```rust
use axum::Router;
use axum::routing::get;

use axum_test::TestServer;

#[tokio::test]
async fn it_should_ping_pong() {
    // Build an application with a route.
    let app = Router::new()
        .route(&"/ping", get(|| async { "pong!" }));

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

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

    // Assertions.
    response.assert_status_ok();
    response.assert_text("pong!");
}
```

A `TestServer` enables you to run an Axum service with a mocked network,
or on a random port with real network reqeusts.
In both cases allowing you to run multiple servers, across multiple tests, all in parallel.

## Crate Features

| Feature             | On by default     |                                                                                                                                   |
|---------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `all`               | _off_             | Turns on all features.                                                                                                            |
| `pretty-assertions` | **on**            | Uses the [pretty assertions crate](https://crates.io/crates/pretty_assertions) on response `assert_*` methods.                    |
| `yaml`              | _off_             | Enables support for sending, receiving, and asserting, [yaml content](https://yaml.org/).                                         |
| `msgpack`           | _off_             | Enables support for sending, receiving, and asserting, [msgpack content](https://msgpack.org/index.html).                         |
| `shuttle`           | _off_             | Enables support for building a `TestServer` an [`shuttle_axum::AxumService`](https://docs.rs/shuttle-axum/latest/shuttle_axum/struct.AxumService.html), for use with [Shuttle.rs](https://shuttle.rs). |
| `typed-routing`     | _off_             | Enables support for using `TypedPath` in requests. See [axum-extra](https://crates.io/crates/axum-extra) for details.             |
| `ws`                | _off_             | Enables WebSocket support. See [TestWebSocket](https://docs.rs/axum-test/latest/axum_test/struct.TestWebSocket.html) for details. |
| `reqwest`           | _off_             | Enables the `TestServer` being able to create [Reqwest](https://docs.rs/axum-test/latest/axum_test/struct.TestWebSocket.html) requests for querying. |

## Axum Compatability

The current version of Axum Test requires at least Axum v0.7.6.

Here is a list of compatability with prior versions:

| Axum Version   | Axum Test Version                                   |
|----------------|-----------------------------------------------------|
| 0.7.6 (latest) | 16+ (latest)                                        |
| 0.7            | 14, 15                                              |
| 0.6            | 13.4.1                                              |

## Examples

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

 * [a simple REST Todo application](/examples/example-todo), and [the same using Shuttle](/examples/example-shuttle)
 * [a WebSocket ping pong application](/examples/example-websocket-ping-pong) which sends requests up and down
 * [a simple WebSocket chat application](/examples/example-websocket-chat)

## Request Building Features

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

 - Serializing and deserializing Json, Form, Yaml, and others, using Serde
 - Assertions on the Json, text, Yaml, etc, that is returned.
 - Cookie, query, and header setting and reading
 - Status code reading and assertions

### Also includes

 - WebSockets testing support
 - Saving returned cookies for use on future requests
 - Setting headers, query, and cookies, globally for all requests or on per request basis
 - Can run requests using a real web server, or with mocked HTTP
 - Automatic status assertions for expecting requests to succeed (to help catch bugs in tests sooner)
 - Prettified assertion output
 - Typed Routing from Axum Extra
 - Reqwest integration

## Contributions

A big thanks to all of these who have helped!

<a href="https://github.com/josephlenton/axum-test/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=josephlenton/axum-test" />
</a>

Made with [contrib.rocks](https://contrib.rocks).