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.

Every virtual user in a Gatling simulation carries its own Session — an isolated, mutable key-value store that persists throughout the user’s lifecycle. The Session is how you inject dynamic data (usernames, tokens, IDs) into requests and extract values from responses for reuse in later steps. Without per-user state, all virtual users would replay identical requests, defeating the purpose of realistic load testing and potentially only exercising application caches rather than real business logic. This page provides an overview of the session sub-system. Use the links below to jump to the topic you need.

​
Sub-Topics

Session API

Programmatically read and write session attributes using get, set, setAll, remove, reset, and state management methods.

Expression Language (EL)

Use #{key} syntax in strings to dynamically interpolate session attributes into request parameters, URLs, and headers.

Feeders

Load dynamic test data from CSV, JSON, JDBC, Redis, or custom sources and inject it into the session automatically per virtual user.

Functions

Pass lambda functions anywhere Gatling accepts an Expression to compute values dynamically from the session at runtime.

​
Concepts

​
Why Per-User State Matters

In most load testing scenarios, virtual users must not share the same data. If they do, you risk:
  • Cache pollution: responses are served from application caches and never reach the real backend logic.
  • JIT skew: the JVM’s Just-In-Time compiler makes aggressive optimizations based on observed code paths. Identical requests create an unrealistically narrow code path, making benchmark results irrelevant to production behavior.
Realistic tests require each user to carry unique data — account IDs, session tokens, search queries — injected via feeders or extracted from earlier responses.

​
What Is a Session?

A Session is essentially a Map<String, Object>: a string-keyed map of named attributes belonging to one specific virtual user. Every Action in a Gatling scenario receives the current Session and passes a (potentially modified) Session to the next Action.
Think of a Session as the “message” that flows through a scenario workflow. Each action receives it, may update it, and forwards it downstream.

​
Injecting Data Into the Session

There are three ways to load data into a virtual user’s session:
  1. Feeders — automated data injection from external sources (CSV, JSON, JDBC, etc.)
  2. Check saveAs — extract values from responses and store them (see Checks)
  3. Session API — programmatic read/write in exec functions

​
Retrieving Data From the Session

Once data is in the session, you can use it in two ways:
  1. Expression Language (EL) — the #{key} syntax in string parameters
  2. Session API — calling session.get("key") inside functions

​
Session API Quick Reference

​
Setting Attributes

// set one attribute
Session newSession1 = session.set("key", "whateverValue");
// set multiple attributes at once
Session newSession2 = session.setAll(Map.of("key", "value"));
// remove one attribute
Session newSession3 = session.remove("key");
// remove multiple attributes
Session newSession4 = session.removeAll("key1", "key2");
// remove all non-Gatling-internal attributes
Session newSession5 = session.reset();
Session instances are immutable. Methods like set return a new Session instance — the original is unchanged. Always return the new Session from your exec function, or your changes will be silently discarded.

​
Getting Attributes

boolean contains = session.contains("key");

String string   = session.getString("key");
int    intVal   = session.getInt("key");
long   longVal  = session.getLong("key");
boolean boolVal = session.getBoolean("key");
double dblVal   = session.getDouble("key");

List<MyPojo>        list = session.getList("key");
Set<MyPojo>         set  = session.getSet("key");
Map<String, MyPojo> map  = session.getMap("key");
MyPojo              obj  = session.get("key");

​
Virtual User Properties

long         userId   = session.userId();   // unique user ID
String       scenario = session.scenario(); // scenario name
List<String> groups   = session.groups();   // current group stack

​
Session State Management

boolean failed    = session.isFailed();
Session succeeded = session.markAsSucceeded(); // reset failure flag
Session failed2   = session.markAsFailed();    // set failure flag
If Gatling complains that an attribute could not be found, check for typos in feeder headers, EL expressions, or missing .feed() calls, or that the check that should have saved it didn’t actually fail silently.

Build docs developers (and LLMs) love

Get started for freeTalk to us