Module rocket::local

source ·
Expand description

Structures for local dispatching of requests, primarily for testing.

This module allows for simple request dispatching against a local, non-networked instance of Rocket. The primary use of this module is to unit and integration test Rocket applications by crafting requests, dispatching them, and verifying the response.


This module contains a Client structure that is used to create LocalRequest structures that can be dispatched against a given Rocket instance. Usage is straightforward:

  1. Construct a Rocket instance that represents the application.

    let rocket = rocket::ignite();
  2. Construct a Client using the Rocket instance.

    let client = Client::new(rocket).expect("valid rocket instance");
  3. Construct requests using the Client instance.

    let req = client.get("/");
  4. Dispatch the request to retrieve the response.

    let response = req.dispatch();

All together and in idiomatic fashion, this might look like:

use rocket::local::Client;

let client = Client::new(rocket::ignite()).expect("valid rocket");
let response ="/")
    .body("Hello, world!")

§Unit/Integration Testing

This module can be used to test a Rocket application by constructing requests via Client and validating the resulting response. As an example, consider the following complete “Hello, world!” application, with testing.

#![feature(proc_macro_hygiene, decl_macro)]

#[macro_use] extern crate rocket;

fn hello() -> &'static str {
    "Hello, world!"

mod test {
    use super::{rocket, hello};
    use rocket::local::Client;

    fn test_hello_world() {
        // Construct a client to use for dispatching requests.
        let rocket = rocket::ignite().mount("/", routes![hello]);
        let client = Client::new(rocket).expect("valid rocket instance");

        // Dispatch a request to 'GET /' and validate the response.
        let mut response = client.get("/").dispatch();
        assert_eq!(response.body_string(), Some("Hello, world!".into()));


  • A structure to construct requests for local dispatching.
  • A structure representing a local request as created by Client.
  • A structure representing a response from dispatching a local request.