Get Started with Gatling: Run Your First Load Test (2026)

Gatling is a load testing tool that generates load from a single machine, but its architecture is designed to scale horizontally to thousands of machines.

Here’s how you can run your first load test with Gatling.

1. Install Gatling

Download the latest Gatling bundle from the official website: https://gatling.io/download/. Extract the archive to a directory of your choice. For example, on Linux:

wget https://repo1.maven.org/maven2/io/gatling/gatling-bundle/3.9.5/gatling-bundle-3.9.5-bundle.zip
unzip gatling-bundle-3.9.5-bundle.zip
cd gatling-bundle-3.9.5-bundle

2. Create Your First Simulation

Gatling simulations are written in Scala. Gatling comes with an example simulation that you can modify. Navigate to the user-files/simulations directory within your Gatling installation. You’ll find a file named ComputerDatabaseSimulation.scala. Let’s create a new file for our first simulation, MyFirstSimulation.scala.

// user-files/simulations/MyFirstSimulation.scala

import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._

class MyFirstSimulation extends Simulation {

  val httpProtocol = http
    .baseUrl("http://computer-database.gatling.io") // The base URL for your requests
    .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
    .doNotTrackHeader("DNT", "1")
    .userAgentHeader("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36")

  val scn = scenario("My First Test") // Define a scenario named "My First Test"
    .exec(http("Request 1: Homepage") // Define an HTTP request
      .get("/")) // Make a GET request to the root path
    .pause(5) // Pause for 5 seconds between requests

  setUp(
    scn.inject(atOnceUsers(1)) // Inject 1 user at once
  ).protocols(httpProtocol)
}

Explanation:

httpProtocol: Configures the base URL and common headers for all HTTP requests in this simulation.
scenario("My First Test"): Defines a sequence of actions a virtual user will perform.
.exec(...): Adds an action to the scenario. Here, it’s an HTTP GET request to the root of the baseUrl.
.pause(5): Simulates think time, pausing for 5 seconds before the next action.
setUp(...): Configures how and when the scenario is executed.
atOnceUsers(1): Injects a single user immediately. This is a simple way to test a single request.

3. Run the Simulation

Navigate back to the root directory of your Gatling installation in your terminal. To run the simulation, use the gatling.sh (or gatling.bat on Windows) script and choose your simulation from the list.

./bin/gatling.sh

You will see a list of available simulations. Enter the number corresponding to MyFirstSimulation.scala.

Simulation index: 1

Gatling will then start the simulation. You’ll see output in the console indicating the progress.

4. Analyze the Results

Once the simulation completes, Gatling will generate a report in the results directory. Open the index.html file in your browser. This report provides detailed metrics about your test, including:

Requests per Second: The number of requests processed by the server over time.
Response Time: The time taken for the server to respond to requests, broken down by percentiles (e.g., 50th, 95th, 99th).
Errors: Any HTTP errors encountered during the test.

For this basic simulation, you’ll see a single request with its response time and success status.

5. Add More Users and Complexity

Let’s make the simulation more interesting by adding more users and a few more requests.

Modify MyFirstSimulation.scala:

// user-files/simulations/MyFirstSimulation.scala

import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._

class MyFirstSimulation extends Simulation {

  val httpProtocol = http
    .baseUrl("http://computer-database.gatling.io")
    .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
    .doNotTrackHeader("DNT", "1")
    .userAgentHeader("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36")

  val scn = scenario("Browsing Computer Database")
    .exec(http("Request 1: Homepage")
      .get("/"))
    .pause(1, 5) // Pause for 1 to 5 seconds

    .exec(http("Request 2: Search Laptops")
      .get("/computers?f=macbook"))
    .pause(1, 5)

    .exec(http("Request 3: View Laptop Details")
      .get("/computers/30")) // Assuming computer with ID 30 exists
    .pause(1, 5)

  setUp(
    scn.inject(
      rampUsers(10) during (10 seconds), // Gradually inject 10 users over 10 seconds
      constantUsersPerSec(5) during (20 seconds) // Maintain 5 users per second for 20 seconds
    )
  ).protocols(httpProtocol)
}

Changes:

More Requests: Added requests to search for "laptops" and view a specific computer’s details.
Dynamic Pauses: pause(1, 5) introduces a random pause between 1 and 5 seconds.
Advanced Injection:
- rampUsers(10) during (10 seconds): Gradually increases the number of active users from 0 to 10 over 10 seconds.
- constantUsersPerSec(5) during (20 seconds): Maintains a steady rate of 5 new users starting every second for 20 seconds.

Run ./bin/gatling.sh again and select your simulation. The results report will now show metrics for multiple requests and a more complex load pattern.

This foundational understanding allows you to start building more sophisticated load tests, simulating realistic user behavior and identifying performance bottlenecks in your applications. The next step is to explore advanced Gatling features like feeders, checks, and custom protocols.