Struct goose::goose::GooseClient

pub struct GooseClient {
    pub task_sets_index: usize,
    pub parent: Option<UnboundedSender<GooseRawRequest>>,
    pub default_host: Option<String>,
    pub task_set_host: Option<String>,
    pub min_wait: usize,
    pub max_wait: usize,
    pub config: GooseConfiguration,
    pub weighted_clients_index: usize,
    pub weighted_on_start_tasks: Vec<Vec<usize>>,
    pub weighted_tasks: Vec<Vec<usize>>,
    pub weighted_on_stop_tasks: Vec<Vec<usize>>,
    pub task_request_name: Option<String>,
    pub request_name: Option<String>,
    pub load_test_hash: u64,
}

An individual client state, repeatedly running all GooseTasks in a specific GooseTaskSet.

Fields

task_sets_index: usize

An index into the internal GooseTest.task_sets vector, indicating which GooseTaskSet is running.

parent: Option<UnboundedSender<GooseRawRequest>>

Channel

default_host: Option<String>

Optional global host, can be overridden per-task-set or via the cli.

task_set_host: Option<String>

Optional per-task-set .host.

min_wait: usize

Minimum amount of time to sleep after running a task.

max_wait: usize

Maximum amount of time to sleep after running a task.

config: GooseConfiguration

A local copy of the global GooseConfiguration.

weighted_clients_index: usize

An index into the internal `GooseTest.weighted_clients, indicating which weighted GooseTaskSet is running.

weighted_on_start_tasks: Vec<Vec<usize>>

A weighted list of all tasks that run when the client first starts.

weighted_tasks: Vec<Vec<usize>>

A weighted list of all tasks that this client runs once started.

weighted_on_stop_tasks: Vec<Vec<usize>>

A weighted list of all tasks that run when the client stops.

task_request_name: Option<String>

Optional name of all requests made within the current task.

request_name: Option<String>

Optional name of all requests made within the current task.

load_test_hash: u64

Load test hash.

Implementations

impl GooseClient

pub fn new(
    task_sets_index: usize,
    default_host: Option<String>,
    task_set_host: Option<String>,
    min_wait: usize,
    max_wait: usize,
    configuration: &GooseConfiguration,
    load_test_hash: u64
) -> Self

Create a new client state.

pub fn build_url(&self, path: &str) -> String

A helper that pre-pends a hostname to the path. For example, if you pass in /foo and --host is set to http://127.0.0.1 it will return http://127.0.0.1/foo. Respects per-GooseTaskSet host configuration, global GooseAttack host configuration, and --host CLI configuration option.

If path is passed in with a hard-coded host, this will be used instead.

Host is defined in the following order:

• If path includes the host, use this
• Otherwise, if --host is defined, use this
• Otherwise, if GooseTaskSet.host is defined, use this
• Otherwise, use global GooseAttack.host.

pub async fn get<'_, '_>(&'_ self, path: &'_ str) -> GooseResponse

A helper to make a GET request of a path and collect relevant statistics. Automatically prepends the correct host.

(If you need to set headers, change timeouts, or otherwise make use of the reqwest::RequestBuilder object, you can instead call goose_get which returns a RequestBuilder, then call goose_send to invoke the request.)

Calls to client.get return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(get_function);

    /// A very simple task that makes a GET request.
    async fn get_function(client: &GooseClient) {
      let _response = client.get("/path/to/foo/");
    }

pub async fn get_named<'_, '_, '_>(
    &'_ self,
    path: &'_ str,
    request_name: &'_ str
) -> GooseResponse

A helper to make a named GET request of a path and collect relevant statistics. Automatically prepends the correct host. Naming a request only affects collected statistics.

Calls to client.get_named return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(get_function);

    /// A very simple task that makes a GET request.
    async fn get_function(client: &GooseClient) {
      let _response = client.get_named("/path/to/foo/", "foo");
    }

pub async fn post<'_, '_, '_>(
    &'_ self,
    path: &'_ str,
    body: &'_ str
) -> GooseResponse

A helper to make a POST request of a path and collect relevant statistics. Automatically prepends the correct host.

(If you need to set headers, change timeouts, or otherwise make use of the reqwest::RequestBuilder object, you can instead call goose_post which returns a RequestBuilder, then call goose_send to invoke the request.)

Calls to client.post return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(post_function);

    /// A very simple task that makes a POST request.
    async fn post_function(client: &GooseClient) {
      let _response = client.post("/path/to/foo/", "BODY BEING POSTED");
    }

pub async fn post_named<'_, '_, '_, '_>(
    &'_ self,
    path: &'_ str,
    request_name: &'_ str,
    body: &'_ str
) -> GooseResponse

A helper to make a named POST request of a path and collect relevant statistics. Automatically prepends the correct host. Naming a request only affects collected statistics.

Calls to client.post return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(post_function);

    /// A very simple task that makes a POST request.
    async fn post_function(client: &GooseClient) {
      let _response = client.post_named("/path/to/foo/", "foo", "BODY BEING POSTED");
    }

pub async fn head<'_, '_>(&'_ self, path: &'_ str) -> GooseResponse

A helper to make a HEAD request of a path and collect relevant statistics. Automatically prepends the correct host.

(If you need to set headers, change timeouts, or otherwise make use of the reqwest::RequestBuilder object, you can instead call goose_head which returns a RequestBuilder, then call goose_send to invoke the request.)

Calls to client.head return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(head_function);

    /// A very simple task that makes a HEAD request.
    async fn head_function(client: &GooseClient) {
      let _response = client.head("/path/to/foo/");
    }

pub async fn head_named<'_, '_, '_>(
    &'_ self,
    path: &'_ str,
    request_name: &'_ str
) -> GooseResponse

A helper to make a named HEAD request of a path and collect relevant statistics. Automatically prepends the correct host. Naming a request only affects collected statistics.

Calls to client.head return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(head_function);

    /// A very simple task that makes a HEAD request.
    async fn head_function(client: &GooseClient) {
      let _response = client.head_named("/path/to/foo/", "foo");
    }

pub async fn delete<'_, '_>(&'_ self, path: &'_ str) -> GooseResponse

A helper to make a DELETE request of a path and collect relevant statistics. Automatically prepends the correct host.

(If you need to set headers, change timeouts, or otherwise make use of the reqwest::RequestBuilder object, you can instead call goose_delete which returns a RequestBuilder, then call goose_send to invoke the request.)

Calls to client.delete return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(delete_function);

    /// A very simple task that makes a DELETE request.
    async fn delete_function(client: &GooseClient) {
      let _response = client.delete("/path/to/foo/");
    }

pub async fn delete_named<'_, '_, '_>(
    &'_ self,
    path: &'_ str,
    request_name: &'_ str
) -> GooseResponse

A helper to make a named DELETE request of a path and collect relevant statistics. Automatically prepends the correct host. Naming a request only affects collected statistics.

Calls to client.delete return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(delete_function);

    /// A very simple task that makes a DELETE request.
    async fn delete_function(client: &GooseClient) {
      let _response = client.delete_named("/path/to/foo/", "foo");
    }

pub async fn goose_get<'_, '_>(&'_ self, path: &'_ str) -> RequestBuilder

Prepends the correct host on the path, then prepares a reqwest::RequestBuilder object for making a GET request.

(You must then call goose_send on this object to actually execute the request.)

Example

    use goose::prelude::*;

    let mut task = task!(get_function);

    /// A simple task that makes a GET request, exposing the Reqwest
    /// request builder.
    async fn get_function(client: &GooseClient) {
      let request_builder = client.goose_get("/path/to/foo").await;
      let response = client.goose_send(request_builder, None).await;
    }

pub async fn goose_post<'_, '_>(&'_ self, path: &'_ str) -> RequestBuilder

Prepends the correct host on the path, then prepares a reqwest::RequestBuilder object for making a POST request.

(You must then call goose_send on this object to actually execute the request.)

Example

    use goose::prelude::*;

    let mut task = task!(post_function);

    /// A simple task that makes a POST request, exposing the Reqwest
    /// request builder.
    async fn post_function(client: &GooseClient) {
      let request_builder = client.goose_post("/path/to/foo").await;
      let response = client.goose_send(request_builder, None).await;
    }

pub async fn goose_head<'_, '_>(&'_ self, path: &'_ str) -> RequestBuilder

Prepends the correct host on the path, then prepares a reqwest::RequestBuilder object for making a HEAD request.

(You must then call goose_send on this object to actually execute the request.)

Example

    use goose::prelude::*;

    let mut task = task!(head_function);

    /// A simple task that makes a HEAD request, exposing the Reqwest
    /// request builder.
    async fn head_function(client: &GooseClient) {
      let request_builder = client.goose_head("/path/to/foo").await;
      let response = client.goose_send(request_builder, None).await;
    }

pub async fn goose_put<'_, '_>(&'_ self, path: &'_ str) -> RequestBuilder

Prepends the correct host on the path, then prepares a reqwest::RequestBuilder object for making a PUT request.

(You must then call goose_send on this object to actually execute the request.)

Example

    use goose::prelude::*;

    let mut task = task!(put_function);

    /// A simple task that makes a PUT request, exposing the Reqwest
    /// request builder.
    async fn put_function(client: &GooseClient) {
      let request_builder = client.goose_put("/path/to/foo").await;
      let response = client.goose_send(request_builder, None).await;
    }

pub async fn goose_patch<'_, '_>(&'_ self, path: &'_ str) -> RequestBuilder

Prepends the correct host on the path, then prepares a reqwest::RequestBuilder object for making a PATCH request.

(You must then call goose_send on this object to actually execute the request.)

Example

    use goose::prelude::*;

    let mut task = task!(patch_function);

    /// A simple task that makes a PUT request, exposing the Reqwest
    /// request builder.
    async fn patch_function(client: &GooseClient) {
      let request_builder = client.goose_patch("/path/to/foo").await;
      let response = client.goose_send(request_builder, None).await;
    }

pub async fn goose_delete<'_, '_>(&'_ self, path: &'_ str) -> RequestBuilder

Prepends the correct host on the path, then prepares a reqwest::RequestBuilder object for making a DELETE request.

(You must then call goose_send on this object to actually execute the request.)

Example

    use goose::prelude::*;

    let mut task = task!(delete_function);

    /// A simple task that makes a DELETE request, exposing the Reqwest
    /// request builder.
    async fn delete_function(client: &GooseClient) {
      let request_builder = client.goose_delete("/path/to/foo").await;
      let response = client.goose_send(request_builder, None).await;
    }

pub async fn goose_send<'_, '_>(
    &'_ self,
    request_builder: RequestBuilder,
    request_name: Option<&'_ str>
) -> GooseResponse

Builds the provided reqwest::RequestBuilder object and then executes the response. If statistics are being displayed, it also captures request statistics.

It is possible to build and execute a RequestBuilder object directly with Reqwest without using this helper function, but then Goose is unable to capture statistics.

Calls to client.goose_send return a GooseResponse object which contains a copy of the request you made (response.request), and the response (response.response).

Example

    use goose::prelude::*;

    let mut task = task!(get_function);

    /// A simple task that makes a GET request, exposing the Reqwest
    /// request builder.
    async fn get_function(client: &GooseClient) {
      let request_builder = client.goose_get("/path/to/foo").await;
      let response = client.goose_send(request_builder, None).await;
    }

pub fn set_success(&self, request: &mut GooseRawRequest)

Manually mark a request as a success.

By default, Goose will consider any response with a 2xx status code as a success. It may be valid in your test for a non-2xx HTTP status code to be returned. A copy of your original request is returned with the response, and a mutable copy must be included when setting a request as a success.

Example

    use goose::prelude::*;

    let mut task = task!(get_function);

    /// A simple task that makes a GET request.
    async fn get_function(client: &GooseClient) {
        let mut response = client.get("/404").await;
        match &response.response {
            Ok(r) => {
                // We expect a 404 here.
                if r.status() == 404 {
                    client.set_success(&mut response.request);
                }
            },
            Err(_) => (),
        }
    }

pub fn set_failure(&self, request: &mut GooseRawRequest)

Manually mark a request as a failure.

By default, Goose will consider any response with a 2xx status code as a success. You may require more advanced logic, in which a 2xx status code is actually a failure. A copy of your original request is returned with the response, and a mutable copy must be included when setting a request as a failure.

Example

    use goose::prelude::*;

    let mut task = task!(loadtest_index_page);

    async fn loadtest_index_page(client: &GooseClient) {
        let mut response = client.get_named("/", "index").await;
        // Extract the response Result.
        match response.response {
            Ok(r) => {
                // We only need to check pages that returned a success status code.
                if r.status().is_success() {
                    match r.text().await {
                        Ok(text) => {
                            // If the expected string doesn't exist, this page load
                            // was a failure.
                            if !text.contains("this string must exist") {
                                // As this is a named request, pass in the name not the URL
                                client.set_failure(&mut response.request);
                            }
                        }
                        // Empty page, this is a failure.
                        Err(_) => client.set_failure(&mut response.request),
                    }
                }
            },
            // Invalid response, this is already a failure.
            Err(_) => (),
        }
    }

pub async fn set_client_builder<'_>(&'_ self, builder: ClientBuilder)

Manually build a Reqwest client.

By default, Goose configures two options when building a Reqwest client. The first configures Goose to report itself as the user agent requesting web pages (ie goose/0.7.5). The second option configures Reqwest to store cookies, which is generally necessary if you aim to simulate logged in users.

Default configuration:

use reqwest::Client;

static APP_USER_AGENT: &str = concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION"));

let builder = Client::builder()
  .user_agent(APP_USER_AGENT)
  .cookie_store(true);

Alternatively, you can use this function to manually build a Reqwest client with custom configuration. Available options are found in the Reqwest ClientBuilder documentation.

When manually building a Reqwest client, there are a few things to be aware of:

• Manually building a client in test_start will only affect requests made during test setup;
• Manually building a client in test_stop will only affect requests made during test teardown;
• A manually built client is specific to a single Goose thread -- if you are generating a large load test with many clients, each will need to manually build their own client (typically you'd do this in a Task that is registered with set_on_start() in each Task Set requiring a custom client;
• Manually building a client will completely replace the automatically built client with a brand new one, so any configuration, cookies or headers set in the previously built client will be gone;
• You must include all desired configuration, as you are completely replacing Goose defaults. For example, if you want Goose clients to store cookies, you will have to include .cookie_store(true).

In the following example, the Goose client is configured with a different user agent, sets a default header on every request, and stores cookies.

Example

use goose::prelude::*;

task!(setup_custom_client).set_on_start();

async fn setup_custom_client(client: &GooseClient) {
  use reqwest::{Client, header};

  // Build a custom HeaderMap to include with all requests made by this client.
  let mut headers = header::HeaderMap::new();
  headers.insert("X-Custom-Header", header::HeaderValue::from_str("custom value").unwrap());

  let builder = Client::builder()
    .default_headers(headers)
    .user_agent("custom user agent")
    .cookie_store(true);

  client.set_client_builder(builder);
}

Trait Implementations

impl Clone for GooseClient

fn clone(&self) -> GooseClient

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GooseClient

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.