[−][src]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). |