Skip to content
httpmock Tutorial

Request Matchers

This section describes matcher functions designed to target and match the host in incoming HTTP requests. These matchers are especially useful when using the proxy and record-and-playback features of httpmock.

host

Sets the expected host name. This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

Note: Both localhost and 127.0.0.1 are treated equally. If the provided host is set to either localhost or 127.0.0.1, it will match requests containing either localhost or 127.0.0.1.

  • host - The host name (should not include a port).

Example

use httpmock::prelude::*;
use reqwest::blocking::Client;


let server = MockServer::start();


server.mock(|when, then| {
    when.host("github.com");
    then.body("This is a mock response");
});


let client = Client::builder()
    .proxy(reqwest::Proxy::all(&server.base_url()).unwrap())
    .build()
    .unwrap();


let response = client.get("http://github.com").send().unwrap();


assert_eq!(response.text().unwrap(), "This is a mock response");

Returns

The updated When instance to enable method chaining.

host_not

Sets the host name that should NOT be responded for.

This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

To add multiple suffixes, invoke this function multiple times.

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

  • host - The host name (should not include a port).

Example

use httpmock::prelude::*;
use reqwest::blocking::Client;


let server = MockServer::start();


server.mock(|when, then| {
    when.host("github.com");
    then.body("This is a mock response");
});


let client = Client::builder()
    .proxy(reqwest::Proxy::all(&server.base_url()).unwrap())
    .build()
    .unwrap();


let response = client.get("http://github.com").send().unwrap();


assert_eq!(response.text().unwrap(), "This is a mock response");

Returns

The updated When instance to enable method chaining.

host_includes

Adds a substring to match within the request’s host name.

This method ensures that the mock server only matches requests whose host name contains the specified substring.

This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

To add multiple substrings, invoke this function multiple times.

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

Note: This function does not automatically compare with pseudo names, like “localhost”.

Attention

This function does not automatically treat 127.0.0.1 like localhost.

Example

use httpmock::prelude::*;


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


// Create a mock that matches any request where the host name contains "localhost"
let mock = server.mock(|when, then| {
    when.host_includes("0.0");  // Only match hosts containing "0.0" (e.g., 127.0.0.1)
    then.status(200);           // Respond with status code 200 for all matched requests
});


// Make a request to a URL whose host name is "localhost" to trigger the mock
let response = reqwest::blocking::get(server.url("/test")).unwrap();


// Ensure the request was successful
assert_eq!(response.status(), 200);


// Ensure that the mock was called at least once
mock.assert();

Parameters

  • host: A string or other type convertible to String that will be added as a substring to match against the request’s host name.

Returns

The updated When instance to enable method chaining.

host_excludes

Adds a substring that must not be present within the request’s host name for the mock server to respond.

This method ensures that the mock server does not respond to requests if the host name contains the specified substring.

This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

To add multiple excluded substrings, invoke this function multiple times.

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

Note: This function does not automatically compare with pseudo names, like “localhost”.

Example

use httpmock::prelude::*;


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


// Create a mock that excludes any request where the host name contains "www.google.com"
let mock = server.mock(|when, then| {
    when.host_excludes("www.google.com");  // Exclude hosts containing "www.google.com"
    then.status(200);                      // Respond with status code 200 for other matched requests
});


// Make a request to a URL whose host name will be "localhost" and trigger the mock
let response = reqwest::blocking::get(server.url("/test")).unwrap();


// Ensure the request was successful
assert_eq!(response.status(), 200);


// Ensure that the mock was called at least once
mock.assert();

Parameters

  • host: A string or other type convertible to String that will be added as a substring to exclude from matching.

Returns

The updated When instance to enable method chaining.

host_prefix

Adds a prefix that the request’s host name must start with for the mock server to respond.

This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

To add multiple prefixes, invoke this function multiple times.

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

Note: This function does not automatically compare with pseudo names, like “localhost”.

Example

use httpmock::prelude::*;


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


// Create a mock that matches any request where the host name starts with "local"
let mock = server.mock(|when, then| {
    when.host_prefix("127.0");      // Only match hosts starting with "127.0"
    then.status(200);               // Respond with status code 200 for all matched requests
});


// Make a request to the mock server with a host name of "127.0.0.1" to trigger the mock response.
let response = reqwest::blocking::get(server.url("/test")).unwrap();


// Ensure the request was successful
assert_eq!(response.status(), 200);


// Ensure that the mock was called at least once
mock.assert();

Parameters

  • prefix: A string or other type convertible to String specifying the prefix that the host name should start with.

Returns

The updated When instance to enable method chaining.

host_prefix_not

Adds a prefix that the request’s host name must not start with for the mock server to respond.

This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

To add multiple excluded prefixes, invoke this function multiple times.

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

Note: This function does not automatically compare with pseudo names, like “localhost”.

Example

use httpmock::prelude::*;


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


// Create a mock that matches any request where the host name does not start with "www."
let mock = server.mock(|when, then| {
    when.host_prefix_not("www.");      // Exclude hosts starting with "www"
    then.status(200);                  // Respond with status code 200 for all other requests
});


// Make a request with host name "localhost" that does not start with "www" and therefore
// triggers the mock response.
let response = reqwest::blocking::get(server.url("/example")).unwrap();


// Ensure the request was successful
assert_eq!(response.status(), 200);


// Ensure that the mock was called at least once
mock.assert();

Parameters

  • prefix: A string or other type convertible to String specifying the prefix that the host name should not start with.

Returns

The updated When instance to enable method chaining.

host_suffix

Adds a suffix that the request’s host name must end with for the mock server to respond.

This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

To add multiple suffixes, invoke this function multiple times.

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

Note: This function does not automatically compare with pseudo names, like “localhost”.

Example

use httpmock::prelude::*;


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


// Create a mock that matches any request where the host name ends with "host" (e.g., "localhost").
let mock = server.mock(|when, then| {
    when.host_suffix("0.1");    // Only match hosts ending with "0.1"
    then.status(200);           // Respond with status code 200 for all matched requests
});


// Make a request to the mock server with a host name of "127.0.0.1" to trigger the mock response.
let response = reqwest::blocking::get(server.url("/test")).unwrap();


// Ensure the request was successful
assert_eq!(response.status(), 200);


// Ensure that the mock was called at least once
mock.assert();

Parameters

  • host: A string or other type convertible to String specifying the suffix that the host name should end with.

Returns

The updated When instance to enable method chaining.

host_suffix_not

Adds a suffix that the request’s host name must not end with for the mock server to respond.

This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

To add multiple excluded suffixes, invoke this function multiple times.

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

Note: This function does not automatically compare with pseudo names, like “localhost”.

Example

use httpmock::prelude::*;


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


// Create a mock that matches any request where the host name does not end with "host".
let mock = server.mock(|when, then| {
    when.host_suffix_not("host");   // Exclude hosts ending with "host"
    then.status(200);               // Respond with status code 200 for all other requests
});


// Make a request with a host name that does not end with "host" to trigger the mock response.
let response = reqwest::blocking::get(server.url("/example")).unwrap();


// Ensure the request was successful
assert_eq!(response.status(), 200);


// Ensure that the mock was called at least once
mock.assert();

Parameters

  • host: A string or other type convertible to String specifying the suffix that the host name should not end with.

Returns

The updated When instance to enable method chaining.

host_matches

Sets a regular expression pattern that the request’s host name must match for the mock server to respond.

This constraint is especially useful when working with proxy or forwarding rules, but it can also be used to serve mocks (e.g., when using a mock server as a proxy).

To add multiple patterns, invoke this function multiple times.

Note: Host matching is case-insensitive, conforming to RFC 3986, Section 3.2.2. This standard dictates that all host names are treated equivalently, regardless of character case.

Note: This function does not automatically compare with pseudo names, like “localhost”.

Parameters

  • regex: A regular expression pattern to match against the host name. Should be a valid regex string.

Example

use httpmock::prelude::*;


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


// Create a mock that matches requests where the host name is exactly "localhost"
let mock = server.mock(|when, then| {
    when.host_matches(r"^127.0.0.1$");
    then.status(200);
});


// Make a request with "127.0.0.1" as the host name to trigger the mock response.
let response = reqwest::blocking::get(server.url("/")).unwrap();


// Ensure the request was successful
assert_eq!(response.status(), 200);


// Verify that the mock was called at least once
mock.assert();

Returns

The updated When instance to enable method chaining.