Crate httpmock

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 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 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();
    // ...
}

Structs

HttpMockConfig	Holds server configuration properties.
Mock	Represents the mocking user interface to the mock server for your tests.
ServerAdapter	This adapter allows to access the servers management functionality.

Enums

Method

Represents an HTTP method.

Functions

mock	A convenience function to create an HTTP mock. It automatically calls Mock::new and already sets a path and an HTTP method. Please refer to Mock struct for a more detailed description.
start_server	Starts a new instance of an HTTP mock server. You should never need to use this function directly. Use it if you absolutely need to manage the low-level details of how the mock server operates.

Type Definitions

Regex

Refer to regex::Regex.

Attribute Macros

with_mock_server

This attribute macro must be applied to test functions that require a running mock server. This macro will wrap the actual test function and perform some initialization tasks at the mock server before the test starts (such as removing all existing mocks from the server so the test finds a clean environment when it starts).