Skip to content
httpmock Tutorial

Query Parameters

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

query_param

Specifies a required query parameter for the request. This function ensures that the specified query parameter (key-value pair) must be included in the request URL for the mock server to respond.

Note: The request query keys and values are implicitly allowed but not required to be URL-encoded. However, the value passed to this method should always be in plain text (i.e., not encoded).

Parameters

  • name: The name of the query parameter to match against.
  • value: The expected value of the query parameter.

Example

// Arrange
use reqwest::blocking::get;
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query` to have the value "This is cool"
let m = server.mock(|when, then| {
    when.query_param("query", "This is cool");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that includes the specified query parameter and value
get(&server.url("/search?query=This+is+cool")).unwrap();


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

Returns

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

query_param_not

This function ensures that the specified query parameter (key) does exist in the request URL, and its value is not equal to the specified value.

Note: Query keys and values are implicitly allowed but not required to be URL-encoded in the HTTP request. However, values passed to this method should always be in plain text (i.e., not encoded).

Parameters

  • name: The name of the query parameter to ensure is not present.
  • value: The value of the query parameter to ensure is not present.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query` to NOT have the value "This is cool"
let m = server.mock(|when, then| {
    when.query_param_not("query", "This is cool");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that does not include the specified query parameter and value
let response = reqwest::blocking::get(&server.url("/search?query=awesome")).unwrap();


// Assert: Verify that the mock was called
assert_eq!(response.status(), 200);
m.assert();

Returns

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

query_param_exists

Specifies that a query parameter must be present in an HTTP request. This function ensures that the specified query parameter key exists in the request URL for the mock server to respond, regardless of the parameter’s value.

Note: The query key in the request is implicitly allowed but not required to be URL-encoded. However, provide the key in plain text here (i.e., not encoded).

Parameters

  • name: The name of the query parameter that must exist in the request.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query` to exist, regardless of its value
let m = server.mock(|when, then| {
    when.query_param_exists("query");
    then.status(200);  // Respond with a 200 status code if the parameter exists
});


// Act: Make a request with the specified query parameter
reqwest::blocking::get(&server.url("/search?query=restaurants+near+me")).unwrap();


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

Returns

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

query_param_missing

Specifies that a query parameter must not be present in an HTTP request. This function ensures that the specified query parameter key is absent in the request URL for the mock server to respond, regardless of the parameter’s value.

Note: The request query key is implicitly allowed but not required to be URL-encoded. However, provide the key in plain text (i.e., not encoded).

Parameters

  • name: The name of the query parameter that should be missing from the request.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query` to be missing
let m = server.mock(|when, then| {
    when.query_param_missing("query");
    then.status(200);  // Respond with a 200 status code if the parameter is absent
});


// Act: Make a request without the specified query parameter
reqwest::blocking::get(&server.url("/search")).unwrap();


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

Returns

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

query_param_includes

Specifies that a query parameter’s value (not the key) must contain a specific substring for the request to match. This function ensures that the specified query parameter (key) does exist in the request URL, and it does have a value containing the given substring for the mock server to respond.

Note: The request query key-value pairs are implicitly allowed but not required to be URL-encoded. However, provide the substring in plain text (i.e., not encoded).

Parameters

  • name: The name of the query parameter to match against.
  • substring: The substring that must appear within the value of the query parameter.

Example

// Arrange
use reqwest::blocking::get;
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query`
// to have a value containing "cool"
let m = server.mock(|when, then| {
    when.query_param_includes("query", "cool");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that includes a value containing the substring "cool"
get(server.url("/search?query=Something+cool")).unwrap();


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

Returns

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

query_param_excludes

Specifies that a query parameter’s value (not the key) must not contain a specific substring for the request to match.

This function ensures that the specified query parameter (key) does exist in the request URL, and it does not have a value containing the given substring for the mock server to respond.

Note: The request query key-value pairs are implicitly allowed but not required to be URL-encoded. However, provide the substring in plain text here (i.e., not encoded).

Parameters

  • name: The name of the query parameter to match against.
  • substring: The substring that must not appear within the value of the query parameter.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query`
// to have a value that does not contain "uncool"
let m = server.mock(|when, then| {
    when.query_param_excludes("query", "uncool");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that includes a value not containing the substring "uncool"
reqwest::blocking::get(&server.url("/search?query=Something+cool")).unwrap();


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

Returns

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

query_param_prefix

Specifies that a query parameter’s value (not the key) must start with a specific prefix for the request to match. This function ensures that the specified query parameter (key) has a value starting with the given prefix in the request URL for the mock server to respond.

Note: The request query key-value pairs are implicitly allowed but not required to be URL-encoded. Provide the prefix in plain text here (i.e., not encoded).

Parameters

  • name: The name of the query parameter to match against.
  • prefix: The prefix that the query parameter value should start with.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query`
// to have a value starting with "cool"
let m = server.mock(|when, then| {
    when.query_param_prefix("query", "cool");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that includes a value starting with the prefix "cool"
reqwest::blocking::get(&server.url("/search?query=cool+stuff")).unwrap();


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

Returns

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

query_param_prefix_not

Specifies that a query parameter’s value (not the key) must not start with a specific prefix for the request to match. This function ensures that the specified query parameter (key) has a value not starting with the given prefix in the request URL for the mock server to respond.

Note: The request query key-value pairs are implicitly allowed but not required to be URL-encoded. Provide the prefix in plain text here (i.e., not encoded).

Parameters

  • name: The name of the query parameter to match against.
  • prefix: The prefix that the query parameter value should not start with.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query`
// to have a value not starting with "cool"
let m = server.mock(|when, then| {
    when.query_param_prefix_not("query", "cool");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that does not start with the prefix "cool"
reqwest::blocking::get(&server.url("/search?query=warm_stuff")).unwrap();


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

Returns

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

query_param_suffix

Specifies that a query parameter’s value (not the key) must end with a specific suffix for the request to match. This function ensures that the specified query parameter (key) has a value ending with the given suffix in the request URL for the mock server to respond.

Note: The request query key-value pairs are implicitly allowed but not required to be URL-encoded. Provide the suffix in plain text here (i.e., not encoded).

Parameters

  • name: The name of the query parameter to match against.
  • suffix: The suffix that the query parameter value should end with.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query`
// to have a value ending with "cool"
let m = server.mock(|when, then| {
    when.query_param_suffix("query", "cool");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that includes a value ending with the suffix "cool"
reqwest::blocking::get(&server.url("/search?query=really_cool")).unwrap();


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

Returns

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

query_param_suffix_not

Specifies that a query parameter’s value (not the key) must not end with a specific suffix for the request to match. This function ensures that the specified query parameter (key) has a value not ending with the given suffix in the request URL for the mock server to respond.

Note: The request query key-value pairs are implicitly allowed but not required to be URL-encoded. Provide the suffix in plain text here (i.e., not encoded).

Parameters

  • name: The name of the query parameter to match against.
  • suffix: The suffix that the query parameter value should not end with.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter `query`
// to have a value not ending with "cool"
let m = server.mock(|when, then| {
    when.query_param_suffix_not("query", "cool");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that doesn't end with the suffix "cool"
reqwest::blocking::get(&server.url("/search?query=uncool_stuff")).unwrap();


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

Returns

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

query_param_matches

Specifies that a query parameter must match a specific regular expression pattern for the key and another pattern for the value. This function ensures that the specified query parameter key-value pair matches the given patterns in the request URL for the mock server to respond.

Parameters

  • key_regex: A regular expression pattern for the query parameter’s key to match against.
  • value_regex: A regular expression pattern for the query parameter’s value to match against.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects the query parameter key to match the regex "user.*"
// and the value to match the regex "admin.*"
let m = server.mock(|when, then| {
    when.query_param_matches(r"user.*", r"admin.*");
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that matches the regex patterns for both key and value
reqwest::blocking::get(&server.url("/search?user=admin_user")).unwrap();


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

Returns

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

query_param_count

Specifies that the count of query parameters with keys and values matching specific regular expression patterns must equal a specified number for the request to match. This function ensures that the number of query parameters whose keys and values match the given regex patterns is equal to the specified count in the request URL for the mock server to respond.

Parameters

  • key_regex: A regular expression pattern for the query parameter’s key to match against.
  • value_regex: A regular expression pattern for the query parameter’s value to match against.
  • expected_count: The expected number of query parameters whose keys and values match the regex patterns.

Example

// Arrange
use httpmock::prelude::*;


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


// Create a mock that expects exactly two query parameters with keys matching the regex "user.*"
// and values matching the regex "admin.*"
let m = server.mock(|when, then| {
    when.query_param_count(r"user.*", r"admin.*", 2);
    then.status(200);  // Respond with a 200 status code if the condition is met
});


// Act: Make a request that matches the conditions
reqwest::blocking::get(&server.url("/search?user1=admin1&user2=admin2")).unwrap();


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

Returns

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