httpmock 0.8.0

HTTP mocking library for Rust
Documentation

Build crates.io Mentioned in Awesome Rust

Features

  • Mocks responses from HTTP services
  • Simple, expressive, fluent API.
  • Many built-in helpers for easy request matching (Regex, JSON, serde, cookies, and more).
  • Record and Playback third-party services
  • Forward and Proxy Mode
  • HTTPS support
  • Fault and network delay simulation.
  • Custom request matchers.
  • Standalone mode with an accompanying Docker image.
  • Helpful error messages
  • Advanced verification and debugging support (including diff generation between actual and expected HTTP request values)
  • Parallel test execution.
  • Fully asynchronous core with synchronous and asynchronous APIs.
  • Support for mock configuration using YAML files.

Getting Started

Add httpmock to Cargo.toml:

[dev-dependencies]
httpmock = "0.8.0"

You can then use httpmock as follows:

use httpmock::prelude::*;

// Start a lightweight mock server.
let server = MockServer::start();

// Create a mock on the server.
let mock = server.mock(|when, then| {
    when.method(GET)
        .path("/translate")
        .query_param("word", "hello");
    then.status(200)
        .header("content-type", "text/html; charset=UTF-8")
        .body("hola");
});

// Send an HTTP request to the mock server. This simulates your code.
let response = isahc::get(server.url("/translate?word=hello")).unwrap();

// Ensure the specified mock was called exactly one time (or fail with a
// detailed error description).
mock.assert();

// Ensure the mock server did respond as specified.
assert_eq!(response.status(), 200);

The above example will spin up a lightweight HTTP mock server and configure it to respond to all GET requests to path /translate with query parameter word=hello. The corresponding HTTP response will contain the text body hola.

When the specified expectations do not match the received request, mock.assert() fails the test with a detailed error description, including a diff that shows the differences between the expected and actual HTTP requests. Example:

0 of 1 expected requests matched the mock specification.
Here is a comparison with the most similar unmatched request (request number 1):

------------------------------------------------------------
1 : Query Parameter Mismatch
------------------------------------------------------------
Expected:
    key    [equals]  word
    value  [equals]  hello-rustaceans

Received (most similar query parameter):
    word=hello

All received query parameter values:
    1. word=hello

Matcher:  query_param
Docs:     https://docs.rs/httpmock/0.8.0/httpmock/struct.When.html#method.query_param

Usage

See the official website for detailed API documentation.

Examples

You can find examples in the httpmock test directory. The official website and reference docs also contain a lot of examples.

License

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.