Write and Run Your First Gatling Simulation in Java or JS

A Gatling simulation is a self-contained program that describes who does what, for how long, and at what rate. It is made up of three components: an HTTP protocol configuration that establishes connection defaults, a scenario that encodes a user journey as a sequence of HTTP requests, and an injection profile that controls how virtual users are introduced over time. This tutorial walks through each component in sequence — starting from a bare file and finishing with a complete, runnable simulation that targets the Gatling demo e-commerce API at https://api-ecomm.gatling.io.

This tutorial targets the Gatling demo API at https://api-ecomm.gatling.io. This endpoint is public and read-only — safe to use freely for learning and experimentation.

Before You Begin

Make sure Gatling is installed and the demo project is cloned. If you haven’t done that yet, complete the Installation Guide first, then return here.

Java prerequisites
JavaScript prerequisites

64-bit OpenJDK LTS 11–25 installed (Java 17 or 21 recommended)
Demo project cloned: https://github.com/gatling/se-ecommerce-demo-gatling-tests.git
Working directory: se-ecommerce-demo-gatling-tests/java/maven

java -version   # must succeed before continuing

Node.js LTS v24 or later with npm v11 or later
Demo project cloned: https://github.com/gatling/se-ecommerce-demo-gatling-tests.git
Working directory: se-ecommerce-demo-gatling-tests/javascript

node -v   # must be v24 or later
npm -v    # must be v11 or later

Build the Simulation Step by Step

Set Up the File and Imports

Open the starter simulation file in your IDE. Delete any placeholder content below the import statements so only the package declaration and imports remain.

Java
JavaScript

File: src/test/java/example/BasicSimulation.java

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

The static imports bring all Gatling DSL methods (scenario, http, constantUsersPerSec, etc.) into scope without needing to qualify them. The class imports provide the builder types (ScenarioBuilder, HttpProtocolBuilder, Simulation).

File: src/basicSimulation.gatling.js

import { constantUsersPerSec, scenario, simulation } from "@gatling.io/core";
import { http } from "@gatling.io/http";

Named imports bring exactly the functions you need from the Gatling JavaScript SDK packages. The simulation function is the entry point for every Gatling JavaScript simulation.

Declare the Simulation Class or Function

Every Gatling simulation has a top-level container. In Java, your class extends Simulation. In JavaScript, you export a simulation() call.

Java
JavaScript

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 {
  // Protocol, scenario, and setUp go here
}

The class name (BasicSimulation) must match the filename (BasicSimulation.java) and the fully qualified class name you pass to gatling:test -Dgatling.simulationClass=example.BasicSimulation.

import { constantUsersPerSec, scenario, simulation } from "@gatling.io/core";
import { http } from "@gatling.io/http";

export default simulation((setUp) => {
  // Protocol, scenario, and setUp call go here
});

The simulation function receives a callback. Inside the callback, setUp is provided as a parameter — it is the function you call at the end to register your injection profile.

Define the HTTP Protocol Configuration

The HTTP protocol builder sets connection-level defaults that apply to every request in the simulation. At minimum you need baseUrl. Additional options like acceptHeader and userAgentHeader make your virtual users look more like real browser clients.

Java
JavaScript

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");

http.baseUrl(...) means every request URL in the scenario can be written as a relative path (e.g. /session instead of https://api-ecomm.gatling.io/session).

const 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"
  );

Describe a Scenario

A scenario is a named sequence of actions that models what one virtual user does. Start with a single GET request to keep things simple, then add more steps once the simulation runs successfully.

Java
JavaScript

ScenarioBuilder scenario =
  scenario("Scenario").exec(http("Session").get("/session"));

scenario("Scenario") — names the scenario. This name appears in the HTML report.
.exec(...) — appends one action to the scenario chain.
http("Session") — names the individual request. Request names appear as rows in the report.
.get("/session") — issues an HTTP GET. The full URL is baseUrl + "/session".

const scn = scenario("Scenario").exec(http("Session").get("/session"));

The API mirrors the Java SDK: scenario creates a named scenario, .exec appends an action, http("Session").get("/session") defines the request.

Add a status check to the request to make the simulation fail on unexpected responses:Java: .get("/session").check(status().is(200))JavaScript: .get("/session").check(status().is(200))

Choose an Injection Profile

The injection profile tells Gatling how many virtual users to launch and when. constantUsersPerSec(2).during(60) is an open injection model that adds 2 new users every second for 60 seconds — 120 users total, each running the scenario independently.

Java
JavaScript

{
  setUp(scenario.injectOpen(constantUsersPerSec(2).during(60)))
    .protocols(httpProtocol);
}

The instance initializer block ({ setUp(...) }) is how setUp is called in Java simulations. It runs when Gatling instantiates your Simulation class.

setUp(scn.injectOpen(constantUsersPerSec(2).during(60)))
  .protocols(httpProtocol);

setUp is the parameter passed into the simulation callback. Always call it last, after all protocol and scenario definitions are in place.

The Completed Simulation

Here is the full simulation file with all pieces assembled:

Java
JavaScript

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 {

  // HTTP protocol configuration
  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");

  // Scenario: one virtual user action
  ScenarioBuilder scenario =
    scenario("Scenario").exec(http("Session").get("/session"));

  // Injection profile: 2 users/sec for 60 seconds
  {
    setUp(scenario.injectOpen(constantUsersPerSec(2).during(60)))
      .protocols(httpProtocol);
  }
}

import { constantUsersPerSec, scenario, simulation } from "@gatling.io/core";
import { http } from "@gatling.io/http";

export default simulation((setUp) => {
  // HTTP protocol configuration
  const 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"
    );

  // Scenario: one virtual user action
  const scn = scenario("Scenario").exec(http("Session").get("/session"));

  // Injection profile: 2 users/sec for 60 seconds
  setUp(scn.injectOpen(constantUsersPerSec(2).during(60)))
    .protocols(httpProtocol);
});

Run the Simulation via the CLI

Execute the simulation from the terminal. Gatling prints a live progress summary while the test runs and an HTML report path when it finishes.

Java (Maven)
JavaScript (npm)

# Linux / macOS
./mvnw gatling:test

# Windows
mvnw.cmd gatling:test

Select [1] example.BasicSimulation when prompted, or skip the prompt:

./mvnw gatling:test -Dgatling.simulationClass=example.BasicSimulation

The report is written to target/gatling/basicsimulation-<timestamp>/index.html.

npx gatling run

Select [2] basicSimulation when prompted.The report is written to target/gatling/basicsimulation-<timestamp>/index.html.

Common troubleshooting:

Symptom	Fix
`Permission denied: ./mvnw`	Run `chmod +x mvnw` on Linux/macOS
`Compilation error`	Verify all braces and imports are in place
`Module not found` (JS)	Run `npm install` in the project directory
Simulation not listed (JS)	Confirm the file ends with `.gatling.js` and is in `src/`
Network errors	Check `https://api-ecomm.gatling.io/session` is reachable in a browser

Understanding the Report

Once the test completes, open the index.html file in your browser. The report contains:

Summary table — total requests, success count, error count, and response time percentiles per request
Active users over time — visualizes the shape of your injection profile
Response time percentiles over time — shows how latency evolves as load increases
Requests/responses per second — throughput across the test duration

Use the 95th and 99th percentile response times — not the mean — as your primary performance indicators. The mean can hide a long tail of slow responses that affect a meaningful fraction of users.

Next Steps

Deploy to Gatling Enterprise

Package your simulation with ./mvnw gatling:enterprisePackage or npx gatling enterprise-package and upload it to Gatling Enterprise for distributed, cloud-scale execution.

Low-Code Tools

Already have a Postman collection? Import it directly into a Gatling simulation without writing the HTTP requests by hand.

Introduction

Tutorials

Core Concepts

Load Testing Concepts

Write and Run Your First Gatling Simulation in Java or JS

Before You Begin

Build the Simulation Step by Step

Understanding the Report

Next Steps

Deploy to Gatling Enterprise

Low-Code Tools

Build docs developers (and LLMs) love

Introduction

Tutorials

Core Concepts

Load Testing Concepts

Documentation Index

​Before You Begin

​Build the Simulation Step by Step

​Understanding the Report

​Next Steps

Deploy to Gatling Enterprise

Low-Code Tools

Build docs developers (and LLMs) love

Before You Begin

Build the Simulation Step by Step

Understanding the Report

Next Steps