HTTP mock server

A simple-to-use HTTP mock server that can be used for mocking HTTP calls in your tests. This crate can be used for both, local tests as well as tests that span multiple systems. It provides an API to create mocks on a local or remote mock server.

If used without a dedicated (standalone) mock server instance, an HTTP mock server will automatically be created in the background of your tests. The local mock server is created in a separate thread. It will be started when your tests need one for the first time. It will be shut down at the end of the test run.

To use this crate in standalone mode you can just use the binary or start it using cargo (cargo run).

Getting Started

You can use a local mock server in your tests like shown in the following:

extern crate httpmock;

use httpmock::Method::GET;
use httpmock::{mock, with_mock_server};

#[test]
#[with_mock_server]
fn simple_test() {
   let health_mock = mock(GET, "/search")
       .expect_query_param("query", "metallica")
       .return_status(204)
       .create();

   let response = reqwest::get("http://localhost:5000/search?query=metallica").unwrap();

   assert_eq!(response.status(), 204);
   assert_eq!(health_mock.times_called(), 1);
}

In the snippet, a mock server is automatically created when the test launches. This is ensured by the httpmock::with_mock_server annotation, which wraps the test inside an initializer function performing multiple preparation steps, such as starting a server (if none yet exists) or clearing the server from old mocks. It also sequentializes tests that involve a mock server.

If you try to create a mock without having annotated you test function with the httpmock::with_mock_server annotation, you will receive a panic at runtime pointing you to this problem. You can provide expected request attributes (such as headers, body content, etc.) and values that will be returned by the mock to the calling application using the expect_xxx and return_xxx methods, respectively. The Mock::create method will eventually make a request to the mock server (either local or remote) to create the mock at the server.

You can use the mock object returned by the Mock::create method to fetch information about it from the mock server. This might be the number of times this mock has been called. You might use this information in your test assertions.

An HTTP request made by your application is only considered to match a mock if the request fulfills all specified requirements. If a request does not match any mock, the mock server will respond with an empty response body and a status code 500 (Internal Server Error).

By default, if a server port is not provided using an environment variable (MOCHA_SERVER_PORT), the port 5000 will be used. If another server host is explicitely set using an environment variable (MOCHA_SERVER_HOST), then this API will use the remote server managing mocks.

Examples

Please refer to the tests of this crate for more examples.

Debugging

httpmock logs against the log crate. If you use the env_logger backend, you can activate debug logging by setting RUST_LOG environment variable to debug and then calling env_logger::try_init():

#[test]
fn your_test() {
    let _ = env_logger::try_init();
    // ...
}

License

httpmock is free software: you can redistribute it and/or modify it under the terms of the MIT Public License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the MIT Public License for more details.