Skip to content
httpmock Tutorial

Headers

This section describes matcher functions designed to target and match HTTP headers in incoming HTTP requests.

Sets the expected HTTP header and its value for the request to match. This function ensures that the specified header with the given value is present in the request. Header names are case-insensitive, as per RFC 2616.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.
  • value: The expected value of the HTTP header.

Example

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


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


// Create a mock that expects the "Authorization" header with a specific value
let mock = server.mock(|when, then| {
    when.header("Authorization", "token 1234567890");
    then.status(200);  // Respond with a 200 status code if the header and value are present
});


// Make a request that includes the "Authorization" header with the specified value
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_not

Sets the requirement that the HTTP request must not contain a specific header with the specified value. This function ensures that the specified header with the given value is absent in the request. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to add multiple excluded headers.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.
  • value: The value of the HTTP header that must not be present.

Example

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


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


// Create a mock that expects the "Authorization" header with a specific value to be absent
let mock = server.mock(|when, then| {
    when.header_not("Authorization", "token 1234567890");
    then.status(200);  // Respond with a 200 status code if the header and value are absent
});


// Make a request that includes the "Authorization" header with a different value
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token abcdefg")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_exists

Sets the requirement that the HTTP request must contain a specific header. The presence of the header is checked, but its value is not validated. For value validation, refer to Mock::expect_header.

Parameters

  • name: The HTTP header name. Header names are case-insensitive, as per RFC 2616.

Example

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


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


// Create a mock that expects the "Authorization" header to be present in the request
let mock = server.mock(|when, then| {
    when.header_exists("Authorization");
    then.status(200);  // Respond with a 200 status code if the header is present
});


// Make a request that includes the "Authorization" header
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_missing

Sets the requirement that the HTTP request must not contain a specific header. This function ensures that the specified header is absent in the request. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to add multiple excluded headers.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.

Example

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


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


// Create a mock that expects the "Authorization" header to be absent in the request
let mock = server.mock(|when, then| {
    when.header_missing("Authorization");
    then.status(200);  // Respond with a 200 status code if the header is absent
});


// Make a request that does not include the "Authorization" header
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_includes

Sets the requirement that the HTTP request must contain a specific header whose value contains a specified substring. This function ensures that the specified header is present and its value contains the given substring. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to check multiple headers and substrings.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.
  • substring: The substring that the header value must contain.

Example

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


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


// Create a mock that expects the "Authorization" header's value to contain "token"
let mock = server.mock(|when, then| {
    when.header_includes("Authorization", "token");
    then.status(200);  // Respond with a 200 status code if the header value contains the substring
});


// Make a request that includes the "Authorization" header with the specified substring in its value
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_excludes

Sets the requirement that the HTTP request must contain a specific header whose value does not contain a specified substring. This function ensures that the specified header is present and its value does not contain the given substring. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to check multiple headers and substrings.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.
  • substring: The substring that the header value must not contain.

Example

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


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


// Create a mock that expects the "Authorization" header's value to not contain "Bearer"
let mock = server.mock(|when, then| {
    when.header_excludes("Authorization", "Bearer");
    then.status(200);  // Respond with a 200 status code if the header value does not contain the substring
});


// Make a request that includes the "Authorization" header without the forbidden substring in its value
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_prefix

Sets the requirement that the HTTP request must contain a specific header whose value starts with a specified prefix. This function ensures that the specified header is present and its value starts with the given prefix. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to check multiple headers and prefixes.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.
  • prefix: The prefix that the header value must start with.

Example

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


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


// Create a mock that expects the "Authorization" header's value to start with "token"
let mock = server.mock(|when, then| {
    when.header_prefix("Authorization", "token");
    then.status(200);  // Respond with a 200 status code if the header value starts with the prefix
});


// Make a request that includes the "Authorization" header with the specified prefix in its value
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_prefix_not

Sets the requirement that the HTTP request must contain a specific header whose value does not start with a specified prefix. This function ensures that the specified header is present and its value does not start with the given prefix. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to check multiple headers and prefixes.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.
  • prefix: The prefix that the header value must not start with.

Example

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


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


// Create a mock that expects the "Authorization" header's value to not start with "Bearer"
let mock = server.mock(|when, then| {
    when.header_prefix_not("Authorization", "Bearer");
    then.status(200);  // Respond with a 200 status code if the header value does not start with the prefix
});


// Make a request that includes the "Authorization" header without the "Bearer" prefix in its value
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_suffix

Sets the requirement that the HTTP request must contain a specific header whose value ends with a specified suffix. This function ensures that the specified header is present and its value ends with the given suffix. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to check multiple headers and suffixes.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.
  • suffix: The suffix that the header value must end with.

Example

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


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


// Create a mock that expects the "Authorization" header's value to end with "7890"
let mock = server.mock(|when, then| {
    when.header_suffix("Authorization", "7890");
    then.status(200);  // Respond with a 200 status code if the header value ends with the suffix
});


// Make a request that includes the "Authorization" header with the specified suffix in its value
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_suffix_not

Sets the requirement that the HTTP request must contain a specific header whose value does not end with a specified suffix. This function ensures that the specified header is present and its value does not end with the given suffix. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to check multiple headers and suffixes.

Parameters

  • name: The HTTP header name. Header names are case-insensitive.
  • suffix: The suffix that the header value must not end with.

Example

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


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


// Create a mock that expects the "Authorization" header's value to not end with "abc"
let mock = server.mock(|when, then| {
    when.header_suffix_not("Authorization", "abc");
    then.status(200);  // Respond with a 200 status code if the header value does not end with the suffix
});


// Make a request that includes the "Authorization" header without the "abc" suffix in its value
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_matches

Sets the requirement that the HTTP request must contain a specific header whose key and value match the specified regular expressions. This function ensures that the specified header is present and both its key and value match the given regular expressions. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to check multiple headers and patterns.

Parameters

  • key_regex: The regular expression that the header key must match.
  • value_regex: The regular expression that the header value must match.

Example

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


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


// Create a mock that expects the "Authorization" header's key to match the regex "^Auth.*"
// and its value to match the regex "token .*"
let mock = server.mock(|when, then| {
    when.header_matches("^Auth.*", "token .*");
    then.status(200);  // Respond with a 200 status code if the header key and value match the patterns
});


// Make a request that includes the "Authorization" header with a value matching the regex
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("Authorization", "token 1234567890")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.

header_count

Sets the requirement that the HTTP request must contain a specific number of headers whose keys and values match specified patterns. This function ensures that the specified number of headers with keys and values matching the given patterns are present in the request. Header names are case-insensitive, as per RFC 2616.

This function may be called multiple times to check multiple patterns and counts.

Parameters

  • key_pattern: The pattern that the header keys must match.
  • value_pattern: The pattern that the header values must match.
  • count: The number of headers with keys and values matching the patterns that must be present.

Example

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


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


// Create a mock that expects at least 2 headers whose keys match the regex "^X-Custom-Header.*"
// and values match the regex "value.*"
let mock = server.mock(|when, then| {
    when.header_count("^X-Custom-Header.*", "value.*", 2);
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Make a request that includes the required headers
Client::new()
    .post(&format!("http://{}/test", server.address()))
    .header("x-custom-header-1", "value1")
    .header("X-Custom-Header-2", "value2")
    .send()
    .unwrap();


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

Returns

The updated When instance to allow method chaining for additional configuration.