Wiremock: async HTTP mocking to test Rust applications


I released wiremock, a new crate that provides HTTP mocking to test Rust applications.

use wiremock::{MockServer, Mock, ResponseTemplate};
use wiremock::matchers::{method, path};

async fn main() {
    // Start a background HTTP server on a random local port
    let mock_server = MockServer::start().await;

    // Arrange the behaviour of the MockServer adding a Mock:
    // when it receives a GET request on '/hello' it will respond with a 200.
        // Mounting the mock on the mock server - it's now effective!
    // If we probe the MockServer using any HTTP client it behaves as expected.
    let status = surf::get(format!("{}/hello", &mock_server.uri()))
    assert_eq!(status.as_u16(), 200);

    // If the request doesn't match any `Mock` mounted on our `MockServer` 
    // a 404 is returned.
    let status = surf::get(format!("{}/missing", &mock_server.uri()))
    assert_eq!(status.as_u16(), 404);

The name wiremock is a reference to WireMock.Net, a .NET port of the original Wiremock from Java.

You can spin up as many mock HTTP servers as you need to mock all the 3rd party APIs that your application interacts with.
Mock HTTP servers are fully isolated: tests can be run in parallel, with no interference. Each server is shut down when it goes out of scope (e.g. end of test execution).

wiremock provides out-of-the-box a set of matching strategies, but more can be defined to suit your testing needs via the Match trait.

wiremock is asynchronous: it is compatible (and tested) against both async_std and tokio as runtimes.

Why did we need another HTTP mocking crate?

The backstory

I spent part of last week working on a project that might lead to the first Rust REST API in production at my current company.

As it happens when you have been advocating for a technology, it was not enough to get the job done.
I set out to write the best possible sample: a showcase of what an idiomatic Rust API should look like when it comes to logging, error handling, metrics, testing, domain modelling, etc. - a code base my colleagues could use as a reference if they were to choose Rust for a future project.

All in all things went pretty smoothly - everything I needed was available as a somewhat polished crate, already provided by the Rust community.
Everything but one key piece: HTTP mocking.

The problem

It is extremely valuable to have a set of tests in your suite that interact with your service via its public API, as a user, without any knowledge of its inner workings.

These API tests can be used to verify acceptance criteria for user stories and prevent regressions.
They are as well generally easier to maintain: they are fairly decoupled from the implementation details, with a focus on the behaviour that is visible to a user of the API.

The caveat: no API is an island, especially in a microservice architecture - your service is likely to interact with the public APIs of a number of external dependencies.

When performing API tests you generally do not want to spin up those external dependencies in your continuous integration pipeline - if your microservice architecture is intricate enough, you might end spinning up tens of services to test a tiny piece of functionality in your API under test. The setup alone could take a significant amount of time - best to run those tests in a test cluster, as a final pre-deployment check.
Furthermore, you might simply not be able to spin up some of those dependencies (e.g. 3rd party SaaS services).

For our run-it-on-every-commit CI pipeline, we can get away with most of the value without putting in a crazy amount of effort: we can use HTTP mocking.
We spin up an HTTP server in the background for each of our tests, define a set of request-response scenarios (return response A if you receive request B) and then configure our application to use the mock server in lieu of the real service.

The available options

Two existing crates might have provided what I needed: mockito and httpmock.
Unfortunately, they both suffer by a set of limitations which I didn't want to live with:

Easter, 4 days-long break - I set out to write a new HTTP mocking crate, wiremock.


wiremock provides fully-isolated MockServers: start takes care of finding a random port available on your local machine which is assigned to the new server.
You can use one instance of MockServer for each test and for each 3rd party API you need to mock - each server is shut down when it goes out of scope (e.g. end of test execution).

use wiremock::{MockServer, Mock, ResponseTemplate};
use wiremock::matchers::method;

async fn main() {
    // Arrange
    let mock_server_one = MockServer::start().await;
    let mock_server_two = MockServer::start().await;

    assert!(mock_server_one.address() != mock_server_two.address());

    let mock = Mock::given(method("GET")).respond_with(ResponseTemplate::new(200));
    // Registering the mock with the first mock server - it's now effective!
    // But it *won't* be used by the second mock server!

    // It matches our mock
    let status = surf::get(&mock_server_one.uri())
    assert_eq!(status.as_u16(), 200);

    // This would have matched our mock, but we haven't registered it 
    // for `mock_server_two`!
    // Hence it returns a 404, the default response when 
    // no mocks matched on the mock server.
    let status = surf::get(&mock_server_two.uri())
    assert_eq!(status.as_u16(), 404);

wiremock provides a set of matching strategies out of the box - see the matchers module for a complete list.
You can also define your own matchers using the Match trait, as well as using Fn closures.

How does it work?

Each instance of MockServer is, under the hood, a pair of actors running on Bastion:

When a request hits a MockServer:

The two actors are killed when MockServer is dropped.

Going forward

Well, testing for the upcoming Rust API is surely going to be shiny!

For the overall Rust community, I foresee two main development directions when it comes to wiremock: