Crate mockito [] [src]

Mockito is a library for creating HTTP mocks to be used in integration tests or for offline work. It runs an HTTP server on your local port 1234 which delivers, creates and remove the mocks.

The server is run on a separate thread within the same process and will be removed at the end of the run.

Getting Started

Using compiler flags, set the URL of your web client to mockito::SERVER_URL or mockito::SERVER_ADDRESS.

Example

#[cfg(test)]
use mockito;

#[cfg(not(test))]
const URL: &'static str = "https://api.twitter.com";

#[cfg(test)]
const URL: &'static str = mockito::SERVER_URL;

Then start mocking:

Example

#[cfg(test)]
mod tests {
  use mockito::mock;

  #[test]
  fn test_something() {
    let _m = mock("GET", "/hello")
      .with_status(201)
      .with_header("content-type", "text/plain")
      .with_header("x-api-key", "1234")
      .with_body("world")
      .create();

    // Any calls to GET /hello beyond this line will respond with 201, the
    // `content-type: text/plain` header and the body "world".
  }
}

Lifetime

Just like any Rust object, a mock is available only through its lifetime. You'll want to assign the mocks to variables in order to extend and control their lifetime.

Example

use mockito::mock;

let _m1 = mock("GET", "/long").with_body("hello").create();

{
    let _m2 = mock("GET", "/short").with_body("hi").create();

    // Requests to GET /short will be mocked til here
}

// Requests to GET /long will be mocked til here

Note how I didn't use the same variable name for both mocks (e.g. let _), as it would have ended the lifetime of the first mock with the second assignment.

Run your tests

Due to the nature of this library (all your mocks are recorded on the same server running in background), it is highly recommended that you run your tests on a single thread:

cargo test -- --test-threads=1

# Same, but using an environment variable
RUST_TEST_THREADS=1 cargo test

Asserts

You can use the Mock::assert method to assert that a mock was called. In other words, the Mock#assert method can validate that your code perfomed the expected HTTP requests.

By default, the method expects that only one request to your mock was triggered.

Example

use std::net::TcpStream;
use std::io::{Read, Write};
use mockito::{mock, SERVER_ADDRESS};

let mock = mock("GET", "/hello").create();

{
    // Place a request
    let mut stream = TcpStream::connect(SERVER_ADDRESS).unwrap();
    stream.write_all("GET /hello HTTP/1.1\r\n\r\n".as_bytes()).unwrap();
    let mut response = String::new();
    stream.read_to_string(&mut response);
}

mock.assert();

If you're expecting more than 1 request, you can use the Mock::expect method to specify the exact amout of requests:

Example

use std::net::TcpStream;
use std::io::{Read, Write};
use mockito::{mock, SERVER_ADDRESS};

let mock = mockito::mock("GET", "/hello").expect(3).create();

for _ in 0..3 {
    // Place a request
    let mut stream = TcpStream::connect(SERVER_ADDRESS).unwrap();
    stream.write_all("GET /hello HTTP/1.1\r\n\r\n".as_bytes()).unwrap();
    let mut response = String::new();
    stream.read_to_string(&mut response);
}

mock.assert();

The errors produced by the assert method contain information about the tested mock, but also about the last unmatched request, which can be very useful to track down an error in your implementation or a missing or incomplete mock.

Here's an example of how a Mock#assert error looks like:

Expected 1 request(s) to:

POST /users
bob

...but received 0

The last unmatched request was:

POST /users
content-length: 5
alice

Matchers

Mockito can match your request by method, path, headers or body.

Various matchers are provided by the Matcher type: exact, partial (regular expressions), any or missing.

Matching by path

By default, the request path is compared by its exact value:

Example

use mockito::mock;

// Matched only calls to GET /hello
let _m = mock("GET", "/hello").create();

You can also match the path partially, by using a regular expression:

Example

use mockito::{mock, Matcher};

// Will match calls to GET /hello/1 and GET /hello/2
let _m = mock("GET", Matcher::Regex(r"^/hello/(1|2)$".to_string())).create();

Or you can catch all requests, by using the Matcher::Any variant:

Example

use mockito::{mock, Matcher};

// Will match any GET request
let _m = mock("GET", Matcher::Any).create();

Matching by header

By default, headers are compared by their exact value. The header name letter case is ignored though.

Example

use mockito::mock;

let _m1 = mock("GET", "/hello")
  .match_header("content-type", "application/json")
  .with_body("{'hello': 'world'}")
  .create();

let _m2 = mock("GET", "/hello")
  .match_header("content-type", "text/plain")
  .with_body("world")
  .create();

// JSON requests to GET /hello will respond with JSON, while plain requests
// will respond with text.

You can also match a header value with a regular expressions, by using the Matcher::Regex matcher:

Example

use mockito::{mock, Matcher};

let _m = mock("GET", "/hello")
  .match_header("content-type", Matcher::Regex(r".*json.*".to_string()))
  .with_body("{'hello': 'world'}")
  .create();

Or you can match a header only by its field name, by setting the Mock::match_header value to Matcher::Any.

Example

use mockito::{mock, Matcher};

let _m = mock("GET", "/hello")
 .match_header("content-type", Matcher::Any)
 .with_body("something")
 .create();

// Requests containing any content-type header value will be mocked.
// Requests not containing this header will return `501 Not Implemented`.

You can mock requests that should be missing a particular header field, by setting the Mock::match_header value to Matcher::Missing.

Example

use mockito::{mock, Matcher};

let _m = mock("GET", "/hello")
  .match_header("authorization", Matcher::Missing)
  .with_body("no authorization header")
  .create();

// Requests without the authorization header will be matched.
// Requests containing the authorization header will return `501 Not Implemented`.

Matching by body

You can match a request by its body by using the Mock#match_body method. By default the request body is ignored, similar to passing the Matcher::Any argument to the match_body method.

You can match a body by an exact value:

Example

use mockito::mock;

// Will match requests to POST / whenever the request body is "hello"
let _m = mock("POST", "/").match_body("hello").create();

Or you can match the body by using a regular expression:

Example

use mockito::{mock, Matcher};

// Will match requests to POST / whenever the request body *contains* the word "hello" (e.g. "hello world")
let _m = mock("POST", "/").match_body(Matcher::Regex("hello".to_string())).create();

Non-matching calls

Any calls to the Mockito server that are not matched will return 501 Not Implemented.

Note that mocks are matched in reverse order - the most recent one wins.

Cleaning up

As mentioned earlier, mocks are cleaned up at the end of their normal Rust lifetime. However, you can always use the reset method to clean up all the mocks registered so far.

Example

use mockito::{mock, reset};

let _m1 = mock("GET", "/1").create();
let _m2 = mock("GET", "/2").create();
let _m3 = mock("GET", "/3").create();

reset();

// Nothing is mocked at this point

Or you can use std::mem::drop to remove a single mock without having to wait for its scope to end:

Example

use mockito::mock;
use std::mem;

let m = mock("GET", "/hello").create();

// Requests to GET /hello are mocked

mem::drop(m);

// Still in the scope of `m`, but requests to GET /hello aren't mocked any more

Structs

Mock

Stores information about a mocked request. Should be initialized via mockito::mock().

Enums

Matcher

Allows matching the request path or headers in multiple ways: matching the exact value, matching any value (as long as it is present), matching by regular expression or checking that a particular header is missing.

Constants

SERVER_ADDRESS

Points to the address the mock server is running at. Can be used with std::net::TcpStream.

SERVER_URL

Points to the URL the mock server is running at.

Functions

mock

Initializes a mock for the provided method and path.

reset

Removes all the mocks stored on the server.

start