Rocket/site/guide/testing.md

210 lines
6.1 KiB
Markdown
Raw Normal View History

# Testing
2017-07-05 02:21:46 +00:00
Every application should be well tested and understandable. Rocket provides the
tools to perform unit and integration tests. It also provides a means to inspect
code generated by Rocket.
2017-07-05 02:21:46 +00:00
## Local Dispatching
2017-07-05 02:21:46 +00:00
Rocket applications are tested by dispatching requests to a local instance of
`Rocket`. The [`local`] module contains all of the structures necessary to do
so. In particular, it contains a [`Client`] structure that is used to create
[`LocalRequest`] structures that can be dispatched against a given [`Rocket`]
instance. Usage is straightforward:
2017-07-05 02:21:46 +00:00
1. Construct a `Rocket` instance that represents the application.
2017-07-10 11:59:55 +00:00
```rust
let rocket = rocket::ignite();
```
2017-07-05 02:21:46 +00:00
2. Construct a `Client` using the `Rocket` instance.
2017-07-10 11:59:55 +00:00
```rust
let client = Client::new(rocket).expect("valid rocket instance");
```
2017-07-05 02:21:46 +00:00
3. Construct requests using the `Client` instance.
2017-07-10 11:59:55 +00:00
```rust
let req = client.get("/");
```
2017-07-05 02:21:46 +00:00
2017-07-10 11:59:55 +00:00
4. Dispatch the request to retrieve the response.
2017-07-05 02:21:46 +00:00
2017-07-10 11:59:55 +00:00
```rust
let response = req.dispatch();
```
2017-07-05 02:21:46 +00:00
[`local`]: https://api.rocket.rs/rocket/local/index.html
[`Client`]: https://api.rocket.rs/rocket/local/struct.Client.html
[`LocalRequest`]: https://api.rocket.rs/rocket/local/struct.LocalRequest.html
[`Rocket`]: https://api.rocket.rs/rocket/struct.Rocket.html
## Validating Responses
A `dispatch` of a `LocalRequest` returns a [`LocalResponse`] which can be used
transparently as a [`Response`] value. During testing, the response is usually
validated against expected properties. These includes things like the response
HTTP status, the inclusion of headers, and expected body data.
The [`Response`] type provides methods to ease this sort of validation. We list
a few below:
* [`status`]: returns the HTTP status in the response.
* [`content_type`]: returns the Content-Type header in the response.
* [`headers`]: returns a map of all of the headers in the response.
* [`body_string`]: returns the body data as a `String`.
* [`body_bytes`]: returns the body data as a `Vec<u8>`.
[`LocalResponse`]: https://api.rocket.rs/rocket/local/struct.LocalResponse.html
[`Response`]: https://api.rocket.rs/rocket/struct.Response.html
[`status`]: https://api.rocket.rs/rocket/struct.Response.html#method.status
[`content_type`]: https://api.rocket.rs/rocket/struct.Response.html#method.content_type
[`headers`]: https://api.rocket.rs/rocket/struct.Response.html#method.headers
[`body_string`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_string
[`body_bytes`]: https://api.rocket.rs/rocket/struct.Response.html#method.body_bytes
These methods are typically used in combination with the `assert_eq!` or
`assert!` macros as follows:
```rust
2017-07-05 02:21:46 +00:00
let rocket = rocket::ignite();
let client = Client::new(rocket).expect("valid rocket instance");
let mut response = client.get("/").dispatch();
assert_eq!(response.status(), Status::Ok);
assert_eq!(response.content_type(), Some(ContentType::Plain));
assert!(response.headers().get_one("X-Special").is_some());
assert_eq!(response.body_string(), Some("Expected Body.".into()));
```
2017-07-05 02:21:46 +00:00
## Testing "Hello, world!"
2017-07-05 02:21:46 +00:00
To solidify an intuition for how Rocket applications are tested, we walk through
how to test the "Hello, world!" application below:
```rust
#[get("/")]
fn hello() -> &'static str {
"Hello, world!"
}
2017-07-05 02:21:46 +00:00
fn rocket() -> Rocket {
rocket::ignite().mount("/", routes![hello])
}
2017-07-05 02:21:46 +00:00
fn main() {
rocket().launch();
}
```
2017-07-05 02:21:46 +00:00
Notice that we've separated the _creation_ of the `Rocket` instance from the
_launch_ of the instance. As you'll soon see, this makes testing our application
easier, less verbose, and less error-prone.
2017-07-05 02:21:46 +00:00
### Setting Up
First, we'll create a `test` module with the proper imports:
```rust
#[cfg(test)]
mod test {
use super::rocket;
2017-07-05 02:21:46 +00:00
use rocket::local::Client;
use rocket::http::Status;
#[test]
fn hello_world() {
...
}
}
```
2017-07-05 02:21:46 +00:00
You can also move the body of the `test` module into its own file, say
`tests.rs`, and then import the module into the main file using:
```rust
2017-07-05 02:21:46 +00:00
#[cfg(test)] mod tests;
```
2017-07-05 02:21:46 +00:00
### Testing
To test our "Hello, world!" application, we first create a `Client` for our
`Rocket` instance. It's okay to use methods like `expect` and `unwrap` during
testing: we _want_ our tests to panic when something goes wrong.
```rust
2017-07-05 02:21:46 +00:00
let client = Client::new(rocket()).expect("valid rocket instance");
```
2017-07-05 02:21:46 +00:00
Then, we create a new `GET /` request and dispatch it, getting back our
application's response:
```rust
2017-07-05 02:21:46 +00:00
let mut response = client.get("/").dispatch();
```
2017-07-05 02:21:46 +00:00
Finally, we ensure that the response contains the information we expect it to.
Here, we want to ensure two things:
1. The status is `200 OK`.
2. The body is the string "Hello, world!".
2017-07-05 02:21:46 +00:00
We do this by checking the `Response` object directly:
```rust
assert_eq!(response.status(), Status::Ok);
2017-07-05 02:21:46 +00:00
assert_eq!(response.body_string(), Some("Hello, world!".into()));
```
2017-07-05 02:21:46 +00:00
That's it! Altogether, this looks like:
```rust
#[cfg(test)]
mod test {
use super::rocket;
use rocket::local::Client;
use rocket::http::Status;
#[test]
fn hello_world() {
let client = Client::new(rocket()).expect("valid rocket instance");
let mut response = client.get("/").dispatch();
assert_eq!(response.status(), Status::Ok);
assert_eq!(response.body_string(), Some("Hello, world!".into()));
}
}
```
2017-07-05 02:21:46 +00:00
The tests can be run with `cargo test`. You can find the full source code to
[this example on
2017-07-14 18:21:07 +00:00
GitHub](https://github.com/SergioBenitez/Rocket/tree/v0.3.0/examples/testing).
## Codegen Debug
2017-07-05 02:21:46 +00:00
It can be useful to inspect the code that Rocket's code generation is emitting,
especially when you get a strange type error. To have Rocket log the code that
it is emitting to the console, set the `ROCKET_CODEGEN_DEBUG` environment
variable when compiling:
```rust
ROCKET_CODEGEN_DEBUG=1 cargo build
```
2017-07-05 02:21:46 +00:00
During compilation, you should see output like:
```rust
Emitting item:
2017-07-05 02:21:46 +00:00
fn rocket_route_fn_hello<'_b>(
__req: &'_b ::rocket::Request,
__data: ::rocket::Data
) -> ::rocket::handler::Outcome<'_b> {
let responder = hello();
2017-07-05 02:21:46 +00:00
::rocket::handler::Outcome::from(__req, responder)
}
```
2017-07-05 02:21:46 +00:00
This corresponds to the facade request handler Rocket has generated for the
`hello` route.