mockito

Mockito provides an asynchronous interface for use in async runtimes like tokio. When writing async tests, ensure you use the _async variants of the methods:

• Server::new_async().await to create the server.
• .create_async().await to create the mock.
• Mock::assert_async().await to verify the mock was called.

Example:

#[tokio::test]
async fn test_simple_route_mock_async() {
    let mut server = Server::new_async().await;
    let m1 = server.mock("GET", "/a").with_body("aaa").create_async().await;
    let m2 = server.mock("GET", "/b").with_body("bbb").create_async().await;

    let (m1, m2) = futures::join!(m1, m2);

    // You can use `Mock::assert_async` to verify that your mock was called
    // m1.assert_async().await;
    // m2.assert_async().await;
}

To use Mockito in your Rust project, add it to your Cargo.toml dependencies.

Note: The minimum supported Rust toolchain is 1.85.0 (as of current version).

# Add to Cargo.toml
[dependencies]
mockito = "1.7.2"

A Server manages a pool of HTTP servers. A Mock is defined on a specific Server and is only available throughout the lifetime of that server. Once the Server goes out of scope, all mocks defined on it are removed. You can remove individual mocks earlier by calling Mock::remove or clear all mocks on a server using Server::reset.

let address;

{
    let mut s = mockito::Server::new();
    address = s.host_with_port();

    s.mock("GET", "/").with_body("hi").create();

    // Requests to `address` will be responded with "hi" til here
}

// Requests to `address` will fail as of this point

A ServerGuard is a smart pointer that provides access to a pooled Server. It implements Deref and DerefMut, allowing it to be used as if it were a Server instance.

Crucially, ServerGuard handles automatic resource recycling: when the guard is dropped, the underlying Server is automatically reset and returned to the internal SERVER_POOL for reuse. This ensures that the pool maintains its capacity and that servers are cleaned up between tests.

// ServerGuard can be used directly as a Server due to Deref/DerefMut
// When it goes out of scope, the server is automatically recycled.
{
    let mut server_guard = pool.get_async().await?;
    server_guard.some_server_method();
}

Mockito provides both sync and async interfaces. If you are writing asynchronous tests (e.g., using #[tokio::test]), you must use the *_async variants of the methods to avoid blocking the runtime.

Required async methods:

• Server::new_async
• Server::new_with_opts_async
• Mock::create_async
• Mock::assert_async
• Mock::matched_async
• Mock::remove_async

#[cfg(test)]
mod tests {
# use mockito::Server;
  #[tokio::test]
  async fn test_something() {
    let mut server = Server::new_async().await;
    let m1 = server.mock("GET", "/a").with_body("aaa").create_async().await;
    let m2 = server.mock("GET", "/b").with_body("bbb").create_async().await;

    let (m1, m2) = futures::join!(m1, m2);

    // You can use `Mock::assert_async` to verify that your mock was called
    // m1.assert_async().await;
    // m2.assert_async().await;
  }
}

Mockito uses a server pool to manage running servers. The pool has a capacity of 50. Most of the time, you should use Server::new() to fetch the next available instance from the pool.

If you need to bypass the pool or configure specific settings (like a custom host, port, or enabling auto-assertions), use Server::new_with_opts().

// Fetch from the server pool
let mut server = mockito::Server::new();

// Or bypass the pool with custom options
let opts = mockito::ServerOpts { port: 1234, ..Default::default() };
let server_with_port = mockito::Server::new_with_opts(opts);

You can simulate interactions with multiple different services by starting multiple mockito::Server instances. Each server will have its own unique URL.

Example:

#[test]
fn test_something() {
    let mut twitter = mockito::Server::new();
    let mut github = mockito::Server::new();

    // These mocks will be available at `twitter.url()`
    let twitter_mock = twitter.mock("GET", "/api").create();

    // These mocks will be available at `github.url()`
    let github_mock = github.mock("GET", "/api").create();
}

If you need a server running on a specific, dedicated port (e.g., for a long-running process or manual testing), use Server::new_with_opts with a ServerOpts configuration.

ServerOpts allows you to specify:

• host: The IP address to bind to (e.g., "0.0.0.0").
• port: The specific port number.

Example:

fn main() {
    let opts = mockito::ServerOpts {
        host: "0.0.0.0",
        port: 1234,
        ..Default::default()
    };
    let mut server = mockito::Server::new_with_opts(opts);

    let _m = server.mock("GET", "/").with_body("hello world").create();

    loop {}
}