Create your first Java-based simulation

Learn how to get started with Gatling and create a Gatling simulation.

This guide is intended for Gatling versions 3.14.7 and later.

New to Gatling and the Java SDK? This tutorial walks through every edit required to produce, run, and package your first simulation. If you already know the basics and just need configuration reminders, jump to the Installation Guide. For a broader tour of feeders, checks, and workload modelling, continue with Full SDK Capabilities.

Prefer JavaScript or TypeScript? Follow the introduction to JavaScript scripting instead.

Before you begin

Install a 64-bit OpenJDK LTS version (11 through 25 supported, version 17 or 21 recommended). The sample project targets Java 17.
Install Git and an IDE. We use IntelliJ IDEA Community Edition in the instructions, but any Java IDE works.
(Optional) Create a Gatling Enterprise trial account if you plan to run the script in the cloud.

Confirm your environment in a terminal:

java -version
mvn -version

If either command fails, fix it before you continue. Maven can come from your system installation or from the Maven Wrapper bundled with the project.

Step 1: Clone the tutorial project

Open a terminal and run:

git clone https://github.com/gatling/se-ecommerce-demo-gatling-tests.git
cd se-ecommerce-demo-gatling-tests/java/maven

Prefer ZIP downloads? Grab the archive from GitHub, extract it, and open the java/maven directory in your IDE.
The module ships with a Maven Wrapper (./mvnw / mvnw.cmd). Use it unless your organisation mandates a system-wide Maven.

The sample project targets the demo backend at https://ecomm.gatling.io. It is safe to use for practice.

Step 2: Inspect the project layout

se-ecommerce-demo-gatling-tests/
└── java/maven
    ├── src/test/java/example/BasicSimulation.java
    ├── src/test/resources/data/...
    ├── pom.xml
    └── mvnw / mvnw.cmd

BasicSimulation.java is the file you will edit.
src/test/resources contains data files you can feed into requests.
pom.xml already references the Gatling Maven plugin—no additional setup needed.

Step 3: Build the simulation incrementally

Each subsection adds one concept. Keep IntelliJ (or your IDE) open with BasicSimulation.java selected.

3.1 Clean up the starter file

Delete everything below the import statements so only the package and imports remain. The file should match:

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.*;

3.2 Extend the `Simulation` class

Gatling scripts extend Simulation. Add the class declaration:

public class BasicSimulation extends Simulation {

}

3.3 Define the HTTP protocol

Configure the target base URL and headers so Gatling knows how to talk to your application:

public class BasicSimulation 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");
}

Key callouts:

http.baseUrl("https://api-ecomm.gatling.io") sets the server you will exercise.
Custom headers (user agent, accept) mimic a real browser. Adjust them when testing your own system.

3.4 Describe a scenario

Scenarios encode user journeys. Start with a single request:

public class BasicSimulation 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"));
  }

Here you:

Name the scenario ("Scenario").
Issue a GET request against /session.
Leave room to add checks or additional steps later.

3.5 Choose an injection profile

Configure the arrival rate and duration for virtual users:

public class BasicSimulation 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);
  }
}

This configuration launches two users per second for one minute. Tweak the numbers once the script works.

You now have a complete simulation. The finished file should match:

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 BasicSimulation 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);
  }
}

Need a refresher on what each SDK call does? Keep the Installation Guide and the Java HTTP reference handy.

Step 4: Run the simulation locally

From the java/maven directory, run the Maven Wrapper:
./mvnw gatling:test
mvnw.cmd gatling:test
When prompted, choose [1] example.BasicSimulation.
After the run completes, open the HTML report printed in the terminal (target/gatling/basicsimulation-<timestamp>/index.html).

Troubleshooting tips:

Command not allowed: make the wrapper executable (chmod +x mvnw).
Compilation errors: check that each code block above is in place—missing braces are the most common typo.
SSL or DNS failures: verify you can open https://api-ecomm.gatling.io/session in a browser.

Step 5: Package and run on Gatling Enterprise

Upload your script manually or drive automated deployments.

Manual packaging

From the same directory, run:

./mvnw gatling:enterprisePackage

mvnw.cmd gatling:enterprisePackage

The command produces a .jar under target/. Upload it under Packages in the Gatling Enterprise console.
Create a simulation, choose the uploaded package, select a managed location, and launch.

Automated deployment (configuration as code)

Generate an API token with the Configure permission.

Export it in your terminal session:

export GATLING_ENTERPRISE_API_TOKEN=<your-API-token>

set GATLING_ENTERPRISE_API_TOKEN=<your-API-token>

Run one of the following commands:

Deploy and start immediately:

./mvnw gatling:enterpriseStart -Dgatling.enterprise.simulationName="<simulation name>"

mvnw.cmd gatling:enterpriseStart -Dgatling.enterprise.simulationName="<simulation name>"

Deploy only:

./mvnw gatling:enterpriseDeploy

mvnw.cmd gatling:enterpriseDeploy

Follow the run in the Enterprise UI for live metrics and historical reporting.

Step 6: Keep learning

Repeat the tutorial against your own API—replace the base URL and adjust requests.
Enrich the scenario with checks (.check(status().is(200))) and pauses (.pause(1)), then re-run locally.
Graduate to Full SDK Capabilities for feeders, correlation, and workload modelling.
Revisit the Installation Guide when you need Maven configuration snippets or project structure advice.
Explore the Recorder tutorial to capture traffic and generate simulations automatically.

You have now installed Gatling, authored a Java simulation, and executed it locally and (optionally) on Gatling Enterprise. Keep iterating!

Edit this page on GitHub

Create your first Java-based simulation

Before you begin#

Step 1: Clone the tutorial project#

Step 2: Inspect the project layout#

Step 3: Build the simulation incrementally#

3.1 Clean up the starter file#

3.2 Extend the Simulation class#

3.3 Define the HTTP protocol#

3.4 Describe a scenario#

3.5 Choose an injection profile#

Step 4: Run the simulation locally#

Step 5: Package and run on Gatling Enterprise#

Manual packaging#

Automated deployment (configuration as code)#

Step 6: Keep learning#