Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

The Gatling Maven plugin integrates Gatling’s load testing engine directly into your Maven build, letting you run simulations with a single command, automate them in CI pipelines, and package or deploy them to Gatling Enterprise Edition — without requiring the standalone bundle.
The fastest way to get started is to clone one of the official demo projects:
This documentation assumes you have Maven installed and uses the standard mvn command format. If you prefer the Maven Wrapper, replace mvn with ./mvnw on Linux/macOS or mvnw.cmd on Windows.

​
Versions

Check available versions on Maven Central. Milestone (M) versions are released exclusively for Gatling Enterprise Edition customers.

​
Setup

Add the following to your pom.xml: 
<dependencies>
  <dependency>
    <groupId>io.gatling.highcharts</groupId>
    <artifactId>gatling-charts-highcharts</artifactId>
    <version>MANUALLY_REPLACE_WITH_LATEST_VERSION</version>
    <scope>test</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>io.gatling</groupId>
      <artifactId>gatling-maven-plugin</artifactId>
      <version>MANUALLY_REPLACE_WITH_LATEST_VERSION</version>
    </plugin>
  </plugins>
</build>
Scala users only: Starting from plugin version 4, Scala compilation is no longer bundled. You must also configure scala-maven-plugin alongside the Gatling plugin. Refer to the Scala demo project’s pom.xml for the complete setup.

​
Configuration

The plugin supports many configuration options via the <configuration> block. For example, to pin a specific simulation class: 
<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>MANUALLY_REPLACE_WITH_LATEST_VERSION</version>
  <configuration>
    <simulationClass>com.example.MySimulation</simulationClass>
  </configuration>
</plugin>
Use mvn gatling:help -Ddetail=true -Dgoal=test to print all available configuration options for any goal.

​
Running Your Simulations

Run all simulations with the test goal: 
mvn gatling:test
The gatling:test goal runs interactively and prompts you to choose a simulation unless:
  • Only one simulation exists in the project
  • The simulation class is forced via -Dgatling.simulationClass=<FullyQualifiedClassName>
  • Maven batch mode (-B) is active
  • The CI environment variable is set to true
To target a specific simulation directly: 
mvn gatling:test -Dgatling.simulationClass=com.example.MySimulation

​
Running the Recorder

Launch the Gatling Recorder to generate a simulation from browser traffic: 
mvn gatling:recorder

​
Integrating with the Maven Lifecycle

Bind plugin goals to standard Maven lifecycle phases to trigger them automatically: 
<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>MANUALLY_REPLACE_WITH_LATEST_VERSION</version>
  <executions>
    <execution>
      <goals>
        <goal>test</goal>
        <goal>enterprisePackage</goal>
      </goals>
    </execution>
  </executions>
</plugin>
By default, test binds to the integration-test phase (triggered by mvn verify) and enterprisePackage binds to the package phase.

​
Running Simulations on Gatling Enterprise Edition

​
Prerequisites

You need a Gatling Enterprise Edition API token with the Configure role on the expected teams. Store your token securely — never commit it to source control. The plugin reads it from:
  • The GATLING_ENTERPRISE_API_TOKEN environment variable
  • The gatling.enterprise.apiToken Java system property
If absolutely necessary, you can also set it in pom.xml: 
<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>MANUALLY_REPLACE_WITH_LATEST_VERSION</version>
  <configuration>
    <apiToken>YOUR_API_TOKEN</apiToken>
  </configuration>
</plugin>

​
Deploying to Gatling Enterprise Edition

The enterpriseDeploy goal creates or updates packages and simulations based on your project configuration: 
mvn gatling:enterpriseDeploy
By default, the plugin reads the package descriptor from .gatling/package.conf. To use a different filename: 
mvn gatling:enterpriseDeploy -Dgatling.enterprise.packageDescriptorFilename="mypackage.conf"

​
Starting Simulations on Gatling Enterprise Edition

The enterpriseStart goal deploys your package and launches the simulation in one step: 
mvn gatling:enterpriseStart
To target a simulation by name without the interactive prompt: 
mvn gatling:enterpriseStart -Dgatling.enterprise.simulationName="My Simulation"

Wait for run completion

-Dgatling.enterprise.waitForRunEnd=true — Blocks until the run finishes and fails the build if assertions fail.

Label your run

-Dgatling.enterprise.runTitle=<title> and -Dgatling.enterprise.runDescription=<description> add metadata to the run report.

​
Packaging for Manual Upload

Generate a deployable JAR without triggering an automatic upload: 
mvn gatling:enterprisePackage
This produces target/<artifactId>-<version>-shaded.jar, which you can upload manually through the Gatling Enterprise Edition dashboard.

​
Private Packages

If you use private locations with a control plane, configure its URL in pom.xml: 
<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>MANUALLY_REPLACE_WITH_LATEST_VERSION</version>
  <configuration>
    <controlPlaneUrl>YOUR_CONTROL_PLANE_URL</controlPlaneUrl>
  </configuration>
</plugin>

​
Overriding Logback Configuration

Place a logback-test.xml in your resources folder to override the embedded logging configuration, or specify a custom path: 
mvn gatling:test -Dlogback.configurationFile=/path/to/logback.xml

​
Sources

The plugin source code is available on GitHub: gatling/gatling-maven-plugin.

Build docs developers (and LLMs) love

Get started for freeTalk to us