[−][src]Crate httpmock
httpmock
is a Rust crate that allows you to mock HTTP responses in your tests. It contains
two major components:
- 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.
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.4"
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 old mock server state, so that each test can start with a clean server. The annotation also sequentializes tests, 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
Interaction with the mock server happens via the Mock structure. It provides you all mocking functionality that is supported by the mock server.
The expected style of usage is as follows:
-
Create a Mock object using the Mock::create method (or Mock::new for slightly more control).
-
Set your mock requirements using the provided
expect
-methods, such as expect_header, expect_body, etc. These methods describe what attributes an HTTP request needs to have to be considered a "match" for the mock you are creating. -
use the provided
return
-methods to describe what the mock server should return when it receives an HTTP request that matches all mock requirements. Some examplereturn
-methods are return_status and return_body. If the server does not find any matching mocks for an incoming HTTP request, it will return a response with an empty body and HTTP status code 500. -
create the mock using the Mock::create method. If you do not call this method when you are finished 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 the Mock::create method to assert that a mock has been called by your code under test (please refer to any example).
Responses
For any HTTP request sent to the mock server by your application, the request is only considered to match a mock if it fulfills all of the mocks request requirements. If a request does not match any mock, the server 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. For example, if you use the env_logger
logging
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 httpmock
to provide a standalone mock server that is available to multiple
applications. This can be useful if you are running integration tests that involve
multiple applications and you want to mock only a subset of them.
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). |