#server #client #expectation


The server implementation for httptest

1 unstable release

0.1.0 Dec 14, 2019


317 lines


Provide convenient mechanism for testing http clients against a locally running http server. The typical usage is as follows:

  • Start a server
  • Configure the server by adding expectations
  • Test your http client by making requests to the server
  • On Drop the server verifies all expectations were met.

Example Test

async fn test_readme() {
    use httptest::{mappers::*, responders::*, Expectation, Server};
    use serde_json::json;
    // Starting a logger within the test can make debugging a failed test
    // easier. The mock http server will log::debug every request and response
    // received along with what, if any, matcher was found for the request. When
    // env_logger is initialized running the test with `RUST_LOG=httptest=debug
    // cargo test` can provide that information on stderr.
    let _ = pretty_env_logger::try_init();
    // Start a server running on a local ephemeral port.
    let server = Server::run();
    // Configure the server to expect a single GET /foo request and respond
    // with a 200 status code.
        Expectation::matching(request::method_path("GET", "/foo")).respond_with(status_code(200)),
    // Configure the server to also receive between 1 and 3 POST /bar requests
    // with a json body matching {'foo': 'bar'}, and respond with a json body
    // {'result': 'success'}
            request::body(json_decoded(eq(json!({"foo": "bar"})))),
        .respond_with(json_encoded(json!({"result": "success"}))),

    // The server provides server.addr() that returns the address of the
    // locally running server, or more conveniently provides a server.url()
    // method that gives a fully formed http url to the provided path.
    let url = server.url("/foo");

    // Now test your http client against the server.
    let client = hyper::Client::new();
    // Issue the GET /foo to the server.
    let resp = client.get(url).await.unwrap();
    // Optionally use response matchers to assert the server responded as
    // expected.

    // Assert the response was a 200.
    assert_eq!(200, resp.status().as_u16());

    // Issue a POST /bar with {'foo': 'bar'} json body.
    let post_req = http::Request::post(server.url("/bar"))
        .body(json!({"foo": "bar"}).to_string().into())
    // Read the entire response body into a Vec<u8> to allow using the body
    // response matcher.
    let resp = read_response_body(client.request(post_req)).await;
    // Assert the response was a 200 with a json body of {'result': 'success'}
    assert_eq!(200, resp.status().as_u16());
        json!({"result": "success"}),

    // on Drop the server will assert all expectations have been met and will
    // panic if not.


~143K SLoC