An HTTP mocking library for Rust
httpmock is an easy-to-use library that allows you to mock HTTP endpoints in your tests.
This crate contains two major components:
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).
Add httpmock to Cargo.toml:
toml
[dev-dependencies]
httpmock = "0.2.0
You can then use httpmock in your tests like shown in the following example:
```rust
extern crate httpmock;
use httpmock::Method::GET; use httpmock::{mock, withmockserver};
fn simpletest() { let healthmock = mock(GET, "/search") .expectqueryparam("query", "metallica") .return_status(204) .create();
let response = reqwest::get("http://localhost:5000/search?query=metallica").unwrap();
asserteq!(response.status(), 204);
asserteq!(healthmock.timescalled(), 1);
}
``
In the above example, a mock server is automatically created when the test launches.
This is ensured by thewithmockserver`
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.
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 function
(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).
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).
Fore more examples, please refer to this crates test directory.
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():
```rust
fn yourtest() { let _ = envlogger::try_init(); // ... } ```
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 --release from the sources
(or by using a binary that you can build with cargo build --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 use
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.
If you want to expose the server to machines other than localhost, you need to provide the
--expose parameter:
* using cargo: cargo run --release -- --expose
* using the binary: httpmock --expose
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:
shell
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:
shell
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.
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.