diff --git a/CHANGELOG.md b/CHANGELOG.md index d4aec06f..dbb85913 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## 0.12.2-dev - enable [`gzip`](https://docs.rs/reqwest/*/reqwest/struct.ClientBuilder.html#method.gzip) support and set Accept-Encoding header by default in the client; disable with `--no-gzip` or `GooseDefault::NoGzip` + - document how to add custom cookies (https://docs.rs/goose/*/goose/goose/struct.GooseUser.html#custom-cookies) ## 0.12.1 July 15, 2021 - rename `rustls` feature to `rustls-tls` so `tests/controller.rs` can build with the `rustls` library; update `tungstenite` to `0.14` and `tokio-tungstenite` = `0.15` to allow building with `rustls` diff --git a/src/goose.rs b/src/goose.rs index 7473632a..568703b0 100644 --- a/src/goose.rs +++ b/src/goose.rs @@ -1945,7 +1945,7 @@ impl GooseUser { /// In the following example, the Goose client is configured with a different user agent, /// sets a default header on every request, stores cookies, and supports gzip compression. /// - /// # Example + /// ## Example /// ```rust /// use goose::prelude::*; /// @@ -1958,18 +1958,21 @@ impl GooseUser { /// let mut headers = header::HeaderMap::new(); /// headers.insert("X-Custom-Header", header::HeaderValue::from_str("custom value").unwrap()); /// + /// // Build a custom client. /// let builder = Client::builder() /// .default_headers(headers) /// .user_agent("custom user agent") /// .cookie_store(true) /// .gzip(true); /// + /// // Assign the custom client to this GooseUser. /// user.set_client_builder(builder).await?; /// /// Ok(()) /// } /// ``` /// + /// # Alternative Compression Algorithms /// Reqwest also supports /// [`brotli`](https://docs.rs/reqwest/*/reqwest/struct.ClientBuilder.html#method.brotli) and /// [`deflate`](https://docs.rs/reqwest/*/reqwest/struct.ClientBuilder.html#method.deflate) compression. @@ -1985,8 +1988,52 @@ impl GooseUser { /// ] } /// ``` /// - /// Once enabled, you can add `.brotli(true)` and/or `.deflate(true)` to your custom Client::builder(), - /// similar to how is documented above. + /// Once enabled, you can add `.brotli(true)` and/or `.deflate(true)` to your custom + /// [`reqwest::Client::builder()`], following the documentation above. + /// + /// # Custom Cookies + /// Custom cookies can also be manually set when building a custom [`reqwest::Client`]. This requires + /// loading the [`GooseUser::base_url`] being load tested in order to properly build the cookie. Then + /// a custom [`reqwest::cookie::Jar`] is created and the custom cookie is added with + /// [`reqwest::cookie::Jar::add_cookie_str`]. Finally, the new cookie jar must be specified as the + /// [`reqwest::ClientBuilder::cookie_provider`] for the custom client. + /// + /// ## Example + /// ```rust + /// use reqwest::{cookie::Jar, Client}; + /// use std::sync::Arc; + /// + /// use goose::prelude::*; + /// + /// task!(custom_cookie_with_custom_client).set_on_start(); + /// + /// async fn custom_cookie_with_custom_client(user: &GooseUser) -> GooseTaskResult { + /// // Get the base_url that is being load tested, use when building the cookie. + /// let url = user.base_url.read().await; + /// + /// // Prepare the contents of a custom cookie. + /// let cookie = "my-custom-cookie=custom-value"; + /// + /// // Pre-load one or more cookies into a custom cookie jar to use with this client. + /// let jar = Jar::default(); + /// jar.add_cookie_str( + /// cookie, + /// &url, + /// ); + /// + /// // Build a custom client. + /// let builder = Client::builder() + /// .user_agent("example-loadtest") + /// .cookie_store(true) + /// .cookie_provider(Arc::new(jar)) + /// .gzip(true); + /// + /// // Assign the custom client to this GooseUser. + /// user.set_client_builder(builder).await?; + /// + /// Ok(()) + /// } + /// ``` pub async fn set_client_builder(&self, builder: ClientBuilder) -> Result<(), GooseTaskError> { *self.client.lock().await = builder.build()?;