Gatling Java SDK — From Template to Production-Ready Simulations

Why this guide exists#

Build on the fast-start information from the Installation Guide and learn how to assemble production-ready scripts. This page collects the core building blocks—scenarios, feeders, checks, workload models, and workflow hygiene—without walking through every editor action. If you need a slower pace, fall back to Create your first Java-based simulation.

What you will cover#

• Anatomy of a maintainable simulation file.
• Feeding data and correlating dynamic responses.
• Choosing injection profiles that mimic real traffic.
• Operating tips: reports, troubleshooting, and governance.

We link to the appropriate reference material whenever we skip implementation details, so you can go deeper on demand.

Prerequisites#

• Java LTS runtime (versions 11 through 25 supported, 17 or newer recommended).
• A JVM build tool such as Maven or Gradle (examples below use Maven Wrapper commands).
• A non-production system you are allowed to exercise with load tests.
• Optional: a Gatling Enterprise account for distributed execution.

Setup recap#

Clone the gatling-java-demo project or adapt an existing Maven test module. Confirm you can run:

./mvnw gatling:test 

Need help with IDE configuration or directory layout? Revisit the Installation Guide before continuing.

Understand the core concepts#

Mental model: translate your business journey into scenarios, feed them data, run users through an injection profile, and guard the outcome with assertions.

Assemble a baseline simulation#

Start from a single-scenario template, then break logic into helpers as the script grows.

Baseline example#

package example;  import static io.gatling.javaapi.core.CoreDsl.*; import static io.gatling.javaapi.http.HttpDsl.*;  import io.gatling.javaapi.core.*; import io.gatling.javaapi.http.*;  public class GetStartedSimulation extends Simulation {   // Define HTTP configuration  // Reference: https://docs.gatling.io/reference/script/http/protocol/  HttpProtocolBuilder httpProtocol = http.baseUrl("https://api-ecomm.gatling.io")  .acceptHeader("application/json")  .userAgentHeader("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36");   // Define scenario  // Reference: https://docs.gatling.io/concepts/scenario/  ScenarioBuilder scenario =  scenario("Scenario").exec(http("Session").get("/session"));   // Define injection profile and execute the test  // Reference: https://docs.gatling.io/concepts/injection/  {  setUp(scenario.injectOpen(constantUsersPerSec(2).during(60))).protocols(httpProtocol);  } }

Key points:

• Keep protocol builders immutable, then share them across scenarios with .protocols().
• Use System.getProperty for quick parameterization (-Dusers=100). For richer configuration, graduate to Typesafe Config or dedicated Java classes (see the configuration guide).

Enrich scenarios with data and business behavior#

Feeders: avoid hot-cache artifacts#

package example;  import static io.gatling.javaapi.core.CoreDsl.*; import static io.gatling.javaapi.http.HttpDsl.*;  import io.gatling.javaapi.core.*; import io.gatling.javaapi.core.FeederBuilder;  public class FeederExample {   // Feeder reading src/test/resources/data/products.csv  public static FeederBuilder<String> productFeeder = csv("data/products.csv").circular();   public static ScenarioBuilder browseFeeder =  scenario("Browse With Data")  .feed(productFeeder)  .exec(http("Search ${term}")  .get("/search")  .queryParam("q", "${term}")  .check(status().is(200))); }

• Store CSV/JSON files under src/test/resources/data so they ride the classpath.
• Pick the right strategy (.circular(), .queue(), .random()) to balance uniqueness and repeatability. More strategies live in the feeder reference.

Correlation: capture dynamic values#

package example;  import static io.gatling.javaapi.core.CoreDsl.*; import static io.gatling.javaapi.http.HttpDsl.*;  import io.gatling.javaapi.core.*; import io.gatling.javaapi.http.*;  public class AddWithCsrf{   public static ScenarioBuilder addWithCsrf =  scenario("Add With CSRF")  .exec(http("Get Form")  .get("/account")  .check(status().is(200))  .check(css("input[name='csrfToken']", "value").saveAs("csrf")))  .pause(1)  .exec(http("Post Form")  .post("/account")  .formParam("csrfToken", "#{csrf}")  .formParam("email", "user@example.com")  .check(status().in(200, 302))); }

• Add a check that extracts the token (saveAs).
• Reuse it in later requests with #{csrf} (string interpolation) or .formParam("csrf", session("csrf")) if you prefer method references.
• Keep a check(status().is(200)) near every extractor to fail fast when the app changes. For advanced extractors, see the check builders.

Compose journeys#

Break long journeys into smaller chains and reuse them:

ChainBuilder search = exec(http("Search").get("/search").queryParam("q", "#{term}").check(status().is(200))); ChainBuilder view = exec(http("View").get("/items/#{sku}").check(status().in(200, 304)));  ScenarioBuilder browse = scenario("Browse").feed(productFeeder).exec(search, view); 

Declare shared helpers in src/test/java/.../utils and import them from your simulations to keep logic tidy.

Model realistic workloads#

Use injection profiles to express how traffic arrives. Combine warm-up, steady state, and cool-down phases to mimic production.

package perf.simulations;  import io.gatling.javaapi.core.*; import io.gatling.javaapi.http.*;  import static io.gatling.javaapi.core.CoreDsl.*; import static io.gatling.javaapi.http.HttpDsl.*;  public class DualJourneySimulation extends Simulation {   private static final String BASE_URL = System.getProperty("baseUrl", "https://ecomm.gatling.io");   HttpProtocolBuilder httpProtocol = http  .baseUrl(BASE_URL)  .acceptHeader("application/json, text/html;q=0.9,*/*;q=0.8")  .userAgentHeader("Gatling/Java DualJourney");   FeederBuilder.Batchable<String> searchFeeder = csv("data/search_terms.csv").random();   ScenarioBuilder browse =  scenario("01 Browse")  .feed(searchFeeder)  .exec(http("Home").get("/").check(status().is(200)))  .pause(1, 3)  .exec(http("Search ${term}").get("/search").queryParam("q", "#{term}")  .check(status().is(200)))  .pause(1, 2)  .exec(http("View ${term}").get("/items/${term}").check(status().in(200, 304)));   ScenarioBuilder purchase =  scenario("02 Purchase")  .exec(http("Get CSRF").get("/checkout")  .check(status().is(200))  .check(regex("name=\"csrf\" value=\"([^\"]+)\"").saveAs("csrf")))  .pause(1)  .exec(http("Submit Order").post("/checkout")  .formParam("csrf", "#{csrf}")  .formParam("sku", "SKU-12345")  .formParam("qty", "1")  .check(status().in(200, 302)))  .pause(2);   {  setUp(  browse.injectOpen(  rampUsers(50).during(60), // ramp to 50  constantUsersPerSec(10).during(180) // steady 3 minutes  ).protocols(httpProtocol),   purchase.injectOpen(  rampUsers(10).during(60),  constantUsersPerSec(2).during(180)  ).protocols(httpProtocol)   ).assertions(  global().successfulRequests().percent().gt(99.0),  forAll().responseTime().percentile3().lt(1500),  details("02 Purchase", "Submit Order").successfulRequests().percent().gt(98.0)  );  } }

Highlights:

• Mix scenarios with distinct arrival rates to mirror different user personas.
• Detect regressions with assertions on global() and details("scenario", "request").
• Keep human-readable names ("01 Browse") so reports stay sorted and readable.

Common injection shortcuts:

• atOnceUsers(x) for smoke tests or spikes.
• rampUsers(x).during(t) to smooth into load.
• constantUsersPerSec(rate).during(t) when you care about arrival rate more than concurrent sessions.
• heavisideUsers(x).during(t) for S-curve ramps that avoid sudden jumps.

Prefer pacing by arrival rate or closed workload models? Study the injection SDK reference and closed models guide.

Run and inspect results#

• Run locally with ./mvnw -Dgatling.simulationClass=… gatling:test or interactive mode (./mvnw gatling:test).
• After each run, open target/gatling/<simulation>-<timestamp>/index.html and focus on p95/p99 latency, throughput, per-request errors, and response time distribution.
• Need to automate? Wire the same command into CI, or explore Gatling Enterprise for distributed runs and real-time dashboards.

Troubleshooting checklist#

• Connection failures: verify base URL, DNS, VPN/proxy rules, and SSL trust stores.
• Server 429/503 responses: coordinate with ops and honour rate limits—reduce load or widen ramp.
• Too-perfect results: add pause() and realistic think times; confirm you are exercising business-critical endpoints, not just static assets.
• Data collisions: switch feeders to .queue() or generate unique IDs per user; reset test data between runs.

Operational hygiene#

• Version your tests alongside application code and review them like any other pull request.
• Externalize secrets via environment variables or the Gatling Enterprise console—never hard-code credentials.
• Document target SLOs in code using assertions so CI builds surface performance regressions immediately.
• Share knowledge: keep README notes or ADRs that explain scenarios, target metrics, and known limitations.

Where to go next#

• Want a slower, instructional pace? Follow Create your first Java-based simulation.
• Need IDE, packaging, or Maven plugin help? Revisit the Installation Guide or the gatling-maven-plugin guide.
• Move beyond HTTP with the protocol guides and expand checks using the Java SDK reference.
• Ready for team-wide load infrastructure? Scale out, share dashboards, and automate governance with Gatling Enterprise.

Edit this page on GitHub