Run Gatling Tests with the Maven Plugin (2026)

The Gatling Maven plugin is your primary tool for running Gatling performance tests directly within your Maven build lifecycle.

Here’s a Gatling simulation, written in Scala, that simulates a user browsing a website, adding an item to their cart, and then checking out:

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

class BrowseCheckoutSimulation extends Simulation {

  val httpProtocol = http
    .baseUrl("http://localhost:8080") // Replace with your application's base URL
    .acceptHeader("application/json")
    .contentTypeHeader("application/json")

  val scn = scenario("Browse and Checkout")
    .exec(http("Homepage")
      .get("/"))
    .pause(1 second, 3 seconds) // Pause between 1 and 3 seconds
    .exec(http("View Products")
      .get("/products"))
    .pause(2 seconds, 5 seconds)
    .exec(http("Add to Cart")
      .post("/cart/add")
      .body(StringBody("""{"productId": "12345", "quantity": 1}""")))
    .pause(1 second, 2 seconds)
    .exec(http("Checkout")
      .post("/checkout")
      .body(StringBody("""{"paymentMethod": "credit_card", "addressId": "home"}""")))

  setUp(scn.inject(atOnceUsers(10)).protocols(httpProtocol))
}

To run this simulation using the Gatling Maven plugin, you need to configure your pom.xml file. Add the following to your <build> section:

<build>
    <plugins>
        <plugin>
            <groupId>io.gatling</groupId>
            <artifactId>gatling-maven-plugin</artifactId>
            <version>3.9.5</version> <!-- Use the latest version -->
            <configuration>
                <simulationsFolder>src/test/scala</simulationsFolder>
                <runDescription>My Gatling Test Run</runDescription>
            </configuration>
        </plugin>
    </plugins>
</build>

With this setup, you can execute your Gatling tests from the command line using Maven. For instance, to run all simulations found in src/test/scala, you would use:

mvn gatling:test

This command triggers the Gatling plugin to compile your Scala simulations (if not already compiled), load them, and then execute them according to the setUp configuration. The results, including detailed HTML reports, will be generated in the target/gatling/ directory by default.

You can also specify a particular simulation to run if you have multiple in your simulationsFolder. To do this, you’d typically use the gatling.simulationClass system property:

mvn gatling:test -Dgatling.simulationClass=BrowseCheckoutSimulation

This tells the plugin exactly which simulation class to instantiate and run. If you omit this, it will attempt to run all simulations found in the configured folder.

The runDescription configuration parameter in the pom.xml is useful for labeling your test runs, especially when you have many. This description will appear in the generated HTML reports, making it easier to distinguish between different test executions.

You can customize the output directory for Gatling reports by setting the outputFolder configuration property:

<configuration>
    <simulationsFolder>src/test/scala</simulationsFolder>
    <runDescription>My Gatling Test Run</runDescription>
    <outputFolder>target/performance-reports</outputFolder>
</configuration>

When you run mvn gatling:test, the plugin first checks for compiled Scala classes. If they aren’t available, it will compile them using the Maven Scala plugin (which you might need to configure separately if you haven’t already). Once compiled, Gatling loads the specified simulation class, sets up the HTTP protocol as defined, and injects the users as per the atOnceUsers(10) configuration.

One key aspect of Gatling’s execution that often surprises people is how it handles dynamic data. While the example above uses hardcoded productId and paymentMethod, real-world scenarios involve fetching these values from a preceding request or an external data source. Gatling provides powerful mechanisms like feeders and session manipulation to manage this dynamic data, allowing you to simulate realistic user journeys where data changes from one iteration to the next.

The setUp method is where you define the load profile. The atOnceUsers(10) means that all 10 users will be injected simultaneously at the start of the test. Other injection profiles include rampUsers for gradual user increase, constantUsersPerSec for a steady injection rate, and combinations of these.

The next step after mastering basic simulation execution is to integrate these tests into your CI/CD pipeline, typically by configuring the Maven profile to run Gatling tests automatically on code commits or scheduled builds.