[−][src]Crate httpmock
An easy-to-use library that allows you to mock HTTP endpoints in your tests.
This crate contains two major lib:
- a mock server that is automatically started in the background of your tests, and
- a test library to create HTTP mocks on the server.
All interaction with the mock server happens through the provided library. Therefore, you do not need to interact with the mock server directly (but you certainly can!).
By default, an HTTP mock server instance will be started in the background of your tests. It will be created when your tests need the mock server for the first time and will be shut down at the end of the test run. The mock server is executed in a separate thread, so it does not conflict with your tests.
The mock server can also be started in standalone mode (more information below).
Getting Started
Add httpmock
in your Cargo.toml
:
[dev-dependencies]
httpmock = "0.3.0
You can then use httpmock
in your tests like shown in the following example:
extern crate httpmock; use httpmock::Method::GET; use httpmock::{mock, with_mock_server}; #[test] #[with_mock_server] fn simple_test() { let search_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!(search_mock.times_called(), 1); }
In the above example, a mock server is automatically created when the test launches. This is ensured by the with_mock_server annotation. It wraps the test with an initializer function that is performing several important preparation steps, such as starting the mock server if none yet exists and cleaning up the mock server state, so that each test can start with a clean mock server. The annotation also sequentializes tests that are marked with it, so they do not conflict with each other when using the mock server.
If you try to create a mock without having annotated your test function with the with_mock_server annotation, you will receive a panic at runtime pointing you to this problem.
Usage
The main point of interaction with the mock server happens via Mock. It provides you all mocking functionality that is supported by the mock server.
The expected style of usage is to
- create a Mock object using the Mock::create method (or Mock::new for slightly more control)
- Set all your mock requirements using
expect_xxx
-methods, such as headers, body content, etc. These methods describe what attributes an HTTP request needs to have to be considered a "match" for the mock you are creating. - use
return_xxx
-methods to describe what the mock server should return when it receives an HTTP request that matches the mock. If the server does not find any matching mocks for an HTTP request, it will return a response with an empty body and an HTTP status code 500. - create the mock using the Mock::create method. If you do not call this method when you complete configuring it, it will not be created at the mock server and your test will not receive the expected response.
- using the mock object returned by by the Mock::create method to assert that a mock has been called by your code under test (please refer to any example).
Responses
An HTTP request made by your application is only considered to match a mock if the request fulfills all specified mock requirements. If a request does not match any mock currently stored on the mock server, it will respond with an empty response body and an HTTP status code 500 (Internal Server Error).
Examples
Fore more examples, please refer to this crates test directory.
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] #[with_mock_server] fn your_test() { let _ = env_logger::try_init(); // ... }
Standalone Mode
You can use this crate to provide both, an HTTP mock server for your local tests, but also a standalone mock server that is reachable for other applications as well. This can be useful if you are running integration tests that span multiple applications.
To activate standalone mode, you need to do the following steps:
- Start the mock server in standalone mode by running
cargo run --features="standalone" --release
from the sources (or by using a binary that you can build withcargo build --features="standalone" --release
). - On the host that is executing the tests, provide a host name by setting the environment variable
HTTPMOCK_HOST
. If set, tests are assuming a mock server is being executed elsewhere, so no local mock server will be started for your tests anymore. Instead, this library will be using the remote server to create mocks.
By default, if a server port is not provided by the environment variable
HTTPMOCK_PORT
, port 5000
will be used.
Exposing the mock server to the network
If you want to expose the server to machines other than localhost, you need to provide the
--expose
parameter:
- using cargo:
cargo run --features="standalone" --release -- --expose
- using the binary:
httpmock --expose
Docker container
As an alternative to building the mock server yourself, you can use the Docker image from the sources to run a mock server in standalone mode:
docker build -t httpmock .
docker run -it --rm -p 5000:5000 --name httpmock httpmock
To enable extended logging, you can run the docker container with the RUST_LOG
environment
variable set to the log level of your choice:
docker run -it --rm -e RUST_LOG=httpmock=debug -p 5000:5000 --name httpmock httpmock
Please refer to the log and env_logger crates for more information about logging.
Structs
HttpMockConfig | Holds server configuration properties. |
Mock | Represents the primary interface to the mock server. |
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). |