Use this file to discover all available pages before exploring further.
The fastest way to experience Gatling is to clone a demo project, write a minimal simulation, run it locally, and open the generated HTML report. This page takes you from zero to a working test against the Gatling demo e-commerce API at https://api-ecomm.gatling.io — a safe, public endpoint you can use freely for practice. Choose the Java/Maven path if you work in a JVM ecosystem, or the JavaScript/npm path if you prefer Node.js tooling. Both paths converge at the same engine, the same reporting, and the same Gatling Enterprise platform.
1
Install Prerequisites and Clone the Demo Project
Before you write a single line of simulation code, verify that your environment meets Gatling’s requirements, then pull down the official demo repository.
Java (Maven)
JavaScript (npm)
Requirements: 64-bit OpenJDK LTS (versions 11–25). Java 17 or 21 is recommended. The demo project ships with a Maven Wrapper so you do not need Maven installed separately.
# Verify Javajava -version# Clone the demo repositorygit clone https://github.com/gatling/se-ecommerce-demo-gatling-tests.gitcd se-ecommerce-demo-gatling-tests/java/maven# Install dependencies (uses the bundled Maven Wrapper)./mvnw clean install
On Windows, replace ./mvnw with mvnw.cmd throughout this guide.
Requirements: Node.js LTS v24 or later with npm v11 or later.
# Verify Node and npmnode -vnpm -v# Clone the demo repositorygit clone https://github.com/gatling/se-ecommerce-demo-gatling-tests.gitcd se-ecommerce-demo-gatling-tests/javascript# Install dependenciesnpm install
2
Write a Minimal Simulation
Open the file shown below in your IDE or editor and replace its contents with the complete simulation. The simulation has three parts: an HTTP protocol configuration, a scenario that describes a user journey, and an injection profile that controls how virtual users arrive.
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.*;public class BasicSimulation extends Simulation { // 1. HTTP protocol configuration — base URL and request headers 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"); // 2. Scenario — a single GET request representing one user action ScenarioBuilder scenario = scenario("Scenario").exec(http("Session").get("/session")); // 3. Injection profile — 2 new users per second for 60 seconds { setUp(scenario.injectOpen(constantUsersPerSec(2).during(60))) .protocols(httpProtocol); }}
constantUsersPerSec(2).during(60) is an open injection model: Gatling adds 2 new virtual users every second for 60 seconds regardless of how many are already active. This is how you simulate a realistic arrival rate.
File:src/basicSimulation.gatling.js
import { constantUsersPerSec, scenario, simulation } from "@gatling.io/core";import { http } from "@gatling.io/http";export default simulation((setUp) => { // 1. HTTP protocol configuration — base URL and request headers 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" ); // 2. Scenario — a single GET request representing one user action const scn = scenario("Scenario").exec(http("Session").get("/session")); // 3. Injection profile — 2 new users per second for 60 seconds setUp(scn.injectOpen(constantUsersPerSec(2).during(60))) .protocols(httpProtocol);});
The .gatling.js file extension is required. Gatling’s CLI discovers simulations by scanning for files with this extension inside the src/ directory.
3
Run the Test Locally
Execute the simulation from your terminal. Gatling compiles and runs the scenario, printing progress to the console as virtual users execute their requests.
Java (Maven)
JavaScript (npm)
./mvnw gatling:test
When prompted, select [1] example.BasicSimulation. The test runs for approximately 60 seconds.To skip the interactive prompt:
When prompted, select [2] basicSimulation. The test runs for approximately 60 seconds.
If the ./mvnw command is rejected on Linux or macOS with a permission error, make the wrapper executable first: chmod +x mvnw.
During the run you will see a live summary in the terminal showing active users, request counts, and response time statistics updating every few seconds.
4
View the HTML Report
After the test finishes, Gatling prints the path to the generated report in the terminal. Open it in any browser.
Java (Maven)
JavaScript (npm)
Reports generated, please open the following file:target/gatling/basicsimulation-<timestamp>/index.html
Reports generated, please open the following file:target/gatling/basicsimulation-<timestamp>/index.html
The report includes:
Response time percentiles (50th, 75th, 95th, 99th) for every request
Active users over time — visualizes your injection profile
Requests per second — throughput chart across the test duration
Success/failure breakdown per request name
The 95th percentile response time is more useful than the mean. The mean can look healthy while a significant slice of your users experience unacceptable delays. Focus on the upper percentiles when evaluating performance.
