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.

A Gatling Simulation is the top-level container for every load test. It is the class (or exported function in JavaScript/TypeScript) that Gatling discovers and runs. Inside a Simulation you wire together scenarios, injection profiles, protocol configurations, acceptance criteria, and global settings — everything that controls how your test executes from start to finish.
We recommend that your Simulation’s name does not start with Test. Some build tools such as Maven Surefire treat any class matching that pattern as a unit test and will try to execute it outside of the Gatling runner.

​
SDK Imports

Every Simulation must start with the correct SDK imports. Copy these exactly — do not let your IDE “optimize” them, as removing or reordering imports will break the DSL. 
// required for Gatling core structure DSL
import io.gatling.javaapi.core.*;
import static io.gatling.javaapi.core.CoreDsl.*;

// required for Gatling HTTP DSL
import io.gatling.javaapi.http.*;
import static io.gatling.javaapi.http.HttpDsl.*;

// can be omitted if you don't use jdbcFeeder
import io.gatling.javaapi.jdbc.*;
import static io.gatling.javaapi.jdbc.JdbcDsl.*;

// used for specifying durations with a unit, e.g. Duration.ofMinutes(5)
import java.time.Duration;
Any class or function that does not belong to the official SDK packages is considered private API and may change without notice between releases.

​
setUp

The only mandatory element in a Simulation is a single call to setUp. It registers all test components — scenarios, injection profiles, protocols, and assertions — with the Gatling runtime. 
ScenarioBuilder scn = scenario("scn"); // etc...

setUp(
  scn.injectOpen(atOnceUsers(1))
);

​
Multiple Populations

You can register several scenarios (populations) in the same setUp call. All populations start and run in parallel. 
ScenarioBuilder scn1 = scenario("scn1"); // etc...
ScenarioBuilder scn2 = scenario("scn2"); // etc...

setUp(
  scn1.injectOpen(atOnceUsers(1)),
  scn2.injectOpen(atOnceUsers(1))
);

​
Protocols Configuration

Protocol configurations (e.g., the HTTP base URL and headers) can be attached either globally on the setUp — applying to every population — or individually per population when different scenarios need different settings. 
// HttpProtocol configured globally
setUp(
  scn1.injectOpen(atOnceUsers(1)),
  scn2.injectOpen(atOnceUsers(1))
).protocols(httpProtocol);

// different HttpProtocols configured on each population
setUp(
  scn1.injectOpen(atOnceUsers(1))
    .protocols(httpProtocol1),
  scn2.injectOpen(atOnceUsers(1))
    .protocols(httpProtocol2)
);

​
Acceptance Criteria (Assertions)

Assertions define pass/fail thresholds evaluated after the simulation finishes. Attach them to setUp using the .assertions() method. 
setUp(scn.injectOpen(atOnceUsers(1)))
  .assertions(global().failedRequests().count().is(0L));
See the Assertions reference for the full list of metrics and conditions.

​
Global Pause Configuration

By default, Gatling honors the exact durations you specify in pause() calls. You can override this behavior globally on the simulation to shape pauses differently across all virtual users. 
setUp(scn.injectOpen(atOnceUsers(1)))
  // disable all pauses
  .disablePauses()
  // use the exact specified duration
  .constantPauses()
  // uniform distribution around the specified mean
  .uniformPauses(0.5)
  .uniformPauses(Duration.ofSeconds(2))
  // normal distribution with a given standard deviation
  .normalPausesWithStdDevDuration(Duration.ofSeconds(2))
  // normal distribution where SD is a percentage of the mean
  .normalPausesWithPercentageDuration(20)
  // exponential distribution around the specified mean
  .exponentialPauses()
  // custom function returning duration in milliseconds
  .customPauses(session -> 5L);

​
Shaping Throughput (Throttle)

When you need to reason in terms of requests per second rather than virtual users, you can use the throttle method. Throttling disables all pauses and caps the throughput — it cannot generate more traffic than the simulation would naturally produce once pauses are removed. Throttling is supported for HTTP and JMS requests.
  • Throttling should only be used with single-request scenarios. With multiple requests, traffic distribution between them is likely to be unbalanced.
  • Excess traffic is pushed into an unbounded queue, which can cause OutOfMemoryError if your natural throughput greatly exceeds the cap.
  • Gatling automatically terminates the test at the end of the throttle profile, just like maxDuration.
// throttling profile configured globally
setUp(scn.injectOpen(constantUsersPerSec(100).during(Duration.ofMinutes(30))))
  .throttle(
    reachRps(100).in(10),      // ramp to 100 req/s over 10 seconds
    holdFor(Duration.ofMinutes(1)),
    jumpToRps(50),             // immediately jump to 50 req/s
    holdFor(Duration.ofHours(2))
  );

// different throttling profiles per population
setUp(
  scn1.injectOpen(atOnceUsers(1))
    .throttle(reachRps(100).in(10)),
  scn2.injectOpen(atOnceUsers(1))
    .throttle(reachRps(20).in(10))
);
The throttle building blocks are:

reachRps(target).in(duration)

Ramp up to a target throughput over a given duration.

jumpToRps(target)

Immediately jump to the specified target throughput.

holdFor(duration)

Hold the current throughput for a given duration.

​
Maximum Duration

Use maxDuration to force the simulation to terminate after a fixed time limit, even if some virtual users are still executing their scenario. This is useful when you cannot predict how long a test will naturally run. 
setUp(scn.injectOpen(rampUsers(1000).during(Duration.ofMinutes(20))))
  .maxDuration(Duration.ofMinutes(10));

​
Lifecycle Hooks

Gatling provides two hooks for running arbitrary code outside of the load test itself.
Hooks execute outside of Gatling’s virtual user engine. You cannot use Gatling SDK components inside them — they are intended for setup/teardown tasks like seeding a database or cleaning up test data. Use sequential scenarios if you need to execute Gatling SDK calls before the main load starts.
1

Gatling starts

The JVM (or Node.js) process launches.
2

Simulation constructor runs

All code in the class body that is not inside before or after executes.
3

`before` hook

Custom pre-test logic runs here (e.g., seeding data).
4

Simulation runs

All virtual users execute their scenarios.
5

Simulation terminates

All users have completed or maxDuration was reached.
6

`after` hook

Custom post-test logic runs here (e.g., cleanup).
7

Reports generated

HTML reports are produced if enabled, then Gatling shuts down.
Java
@Override
public void before() {
  System.out.println("Simulation is about to start!");
}

@Override
public void after() {
  System.out.println("Simulation is finished!");
}
Lifecycle hooks (before / after) are not supported in the JavaScript/TypeScript SDK.

​
Deployment Information (Enterprise Edition)

When running on Gatling Enterprise Edition, you can access metadata about the current load generator — useful for partitioning data or applying different logic per node.
deploymentInfo is only effective when running on Gatling Enterprise Edition. In open-source mode it is a no-op and returns default/null values.
Java
// the UUID of the run (null when not deploying on Gatling Enterprise Edition)
UUID runId = deploymentInfo.runId;

// the Location name of this Load Generator (null when not deploying on Gatling Enterprise Edition)
String locationName = deploymentInfo.locationName;

// how many Load Generators are deployed on this Location (1 when not deploying on Gatling Enterprise Edition)
int numberOfLoadGeneratorsInLocation = deploymentInfo.numberOfLoadGeneratorsInLocation;

// index of this Load Generator within the Location (0 when not deploying on Gatling Enterprise Edition)
int indexOfLoadGeneratorInLocation = deploymentInfo.indexOfLoadGeneratorInLocation;

// total number of Load Generators in this run (1 when not deploying on Gatling Enterprise Edition)
int numberOfLoadGeneratorsInRun = deploymentInfo.numberOfLoadGeneratorsInRun;

// index of this Load Generator within the full run (0 when not deploying on Gatling Enterprise Edition)
int indexOfLoadGeneratorInRun = deploymentInfo.indexOfLoadGeneratorInRun;

// log files produced by this Load Generator
List<File> logFiles = deploymentInfo.logFiles();
Deployment information is not supported in the JavaScript/TypeScript SDK.

Build docs developers (and LLMs) love

Get started for freeTalk to us