Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

Gatling automatically manages cookies and HTTP caching just like a real browser — cookies received in responses are stored and sent back on subsequent requests, and cacheable responses are cached according to their headers. However, some scenarios require precise, manual control over these mechanisms. The HTTP helper functions let you inject cookies, retrieve cookie values into the session, simulate a browser restart by flushing session cookies, wipe the entire cookie jar, or reset the HTTP cache mid-scenario.

​
addCookie

Manually add a cookie to the virtual user’s cookie jar. The cookie is then sent automatically on subsequent requests that match its domain and path. Cookie name and value can be static strings, Gatling EL strings, or session functions. 
exec(addCookie(Cookie("name", "value")));
The Cookie builder accepts several optional parameters to control matching and expiry behavior: 
// static values
Cookie("name", "value")
  .withDomain("domain")
  .withPath("/api")
  .withMaxAge(3600)       // seconds; defaults to Long.MinValue (session cookie)
  .withSecure(true);      // false = valid for both http and https

// Gatling EL strings
Cookie("#{cookieName}", "#{cookieValue}")
  .withDomain("example.com")
  .withPath("/")
  .withMaxAge(3600)
  .withSecure(false);

// session functions
Cookie(
  session -> session.getString("cookieName"),
  session -> session.getString("cookieValue")
)
  .withDomain("example.com")
  .withPath("/")
  .withMaxAge(3600)
  .withSecure(true);
  • domain defaults to the base URL domain if not specified.
  • path defaults to "/".
  • maxAge defaults to Long.MinValue, meaning the cookie is treated as a session cookie.
  • secure defaults to false, making the cookie valid for both HTTP and HTTPS URLs.

​
getCookieValue

Read a cookie value from the virtual user’s cookie jar and store it in the session under the key specified by saveAs (defaults to the cookie name). 
exec(getCookieValue(CookieKey("name")));
The CookieKey builder has optional parameters to narrow the lookup to a specific domain, path, security flag, and to control the session key used for storing the value: 
// static values
CookieKey("name")
  .withDomain("example.com")
  .withPath("/api")
  .withSecure(true)
  .saveAs("myCookieValue");

// Gatling EL strings
CookieKey("#{cookieName}")
  .withDomain("#{cookieDomain}")
  .withPath("/api")
  .withSecure(true)
  .saveAs("myCookieValue");

// session functions
CookieKey(session -> session.getString("cookieName"))
  .withDomain(session -> session.getString("cookieDomain"))
  .withPath("/api")
  .withSecure(true)
  .saveAs("myCookieValue");
  • domain defaults to the baseUrl domain. If no baseUrl is set and domain is not specified, this call will fail.
  • Domain matching follows RFC 6265 §5.1.3.
  • Path matching, when specified, follows RFC 6265 §5.1.4.
  • saveAs defaults to the cookie name parameter.

​
flushSessionCookies

Simulates closing and reopening the browser. Session cookies (those without a Max-Age or Expires attribute) are dropped, while permanent cookies remain. 
exec(flushSessionCookies());

​
flushCookieJar

Wipes all cookies — both session and permanent — from the virtual user’s cookie jar. 
exec(flushCookieJar());

​
HTTP Cache

​
flushHttpCache

Clears the virtual user’s entire HTTP cache, including known redirects, cached Expires/Cache-Control responses, and stored ETag values. Use this when you want to force a cache miss and re-fetch resources that would otherwise be served from the in-memory cache. 
exec(flushHttpCache());

​
Common Patterns

Simulate Login + Session Reset

Use flushSessionCookies after a logout action to drop the authentication session cookie while keeping persistent preferences cookies intact.

Inject Auth Tokens

Use addCookie to inject a pre-computed authentication token directly into the cookie jar, bypassing a real login flow and saving time in large-scale tests.

Extract CSRF Tokens

Combine a css check to capture a CSRF token value and addCookie to inject it back for subsequent POST requests when the token arrives as a cookie rather than a form field.

Force Cache Miss

Call flushHttpCache at the start of a scenario step to ensure resources are re-fetched from the server, useful for testing cache invalidation behavior.
scenario("Cookie workflow")
  .exec(
    http("Login").post("/api/login")
      .formParam("user", "alice")
      .formParam("pass", "#{password}")
      .check(status().is(200))
  )
  .exec(getCookieValue(CookieKey("session_id").saveAs("sid")))
  .exec(
    http("Authenticated Request").get("/api/profile")
      .check(status().is(200))
  )
  .exec(flushSessionCookies())
  .exec(
    http("Post-logout Request").get("/api/profile")
      .check(status().is(401))
  );

Build docs developers (and LLMs) love

Get started for freeTalk to us