Gatling Maven Plugin

The Maven plugin allows you to run Gatling tests from the command line, without the bundle, as well as to package your simulations for Gatling Enterprise

Using this plugin, Gatling can be launched when building your project, for example with your favorite Continuous Integration (CI) solution. This plugin can also be used to package your Gatling project to run it on Gatling Enterprise.

Versions#

Check out available versions on Maven Central.

Beware that milestones (M versions) are not documented for OSS users and are only released for Gatling Enterprise customers.

Setup#

If you prefer to manually configure your Maven project rather than clone one of our samples, you need to 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>

<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>MANUALLY_REPLACE_WITH_LATEST_VERSION</version>
</plugin>

Configuration#

The plugin supports many configuration options, eg:

<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>MANUALLY_REPLACE_WITH_LATEST_VERSION</version>
  <configuration>
    <simulationClass>foo.Bar</simulationClass>
  </configuration>
</plugin>

See each goal’s section below for the relevant configuration options.

Usage#

Running your simulations#

You can directly launch the gatling-maven-plugin with the test goal:

./mvnw gatling:test

mvnw.cmd gatling:test

Use mvn gatling:help -Ddetail=true -Dgoal=test to print the description of all the available configuration options on the test goal.

The gatling:test goal runs in interactive mode and suggests the simulation class to launch unless:

• there’s only one simulation available,
• or the Simulation class is forced with the -Dgatling.simulationClass=<FullyQualifiedClassName> Java System Property,
• or the non-interactive mode is forced, in which case the task will fail if there is more than 1 simulation available,
• or it’s in batch mode (-B Maven option), in which case the task will fail if there is more than 1 simulation available,
• or the CI env var is set to true, in which case the task will fail if there is more than 1 simulation available.

Running the Gatling Recorder#

You can launch the Gatling Recorder:

./mvnw gatling:recorder

mvnw.cmd gatling:recorder

Use gatling:help -Ddetail=true -Dgoal=recorder to print the description of all the available configuration options on the recorder goal.

Running your simulations on Gatling Enterprise Self-Hosted#

Build from sources#

Once you have configured the Maven plugin on your project, Gatling Enterprise Self-Hosted can build it from sources without additional configuration. Add your source repository and configure your simulation to build from sources using Maven.

To make sure your setup is correct, you can run the packaging command and check that you get a jar containing all the classes and extra dependencies of your project in target/<artifactId>-<version>-shaded.jar:

./mvnw gatling:enterprisePackage

mvnw.cmd gatling:enterprisePackage

Publish to a binary repository#

Alternatively, you can package your simulations and publish them to a binary repository (JFrog Artifactory, Sonatype Nexus or AWS S3).

Configure the repository and/or snapshotRepository block, depending on whether you want to deploy releases or snapshots.

<distributionManagement>
  <repository>
    <id>your.releases.repository.id</id>
    <url>REPLACE_WITH_YOUR_RELEASES_REPOSITORY_URL</url>
  </repository>
  <snapshotRepository>
    <id>your.snapshots.repository.id</id>
    <url>REPLACE_WITH_YOUR_SNAPSHOTS_REPOSITORY_URL</url>
  </snapshotRepository>
</distributionManagement>

Bind the gatling:enterprisePackage goal to the Maven lifecycle in the plugin configuration:

<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>${gatling-maven-plugin.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>enterprisePackage</goal>
      </goals>
    </execution>
  </executions>
</plugin>

The packaged artifact will be automatically attached to your project and deployed with the shaded classifier when you publish it:

./mvnw deploy

mvnw.cmd deploy

Integrating with the Maven lifecycle#

The plugin’s goals can also be bound to the Maven lifecycle phases by configuring an execution block in the plugin configuration:

<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 will be bound to the integration-test phase, e.g. it will be triggered by mvn integration-test or mvn verify
• enterprisePackage will be bound to the package phase, e.g. it will be triggered by mvn package

Overriding the logback.xml file#

You can either have a logback-test.xml that has precedence over the embedded logback.xml file, or add a JVM option -Dlogback.configurationFile=myFilePath.

Sources#

If you’re interested in contributing, you can find the gatling-maven-plugin sources on GitHub.

Edit this page on GitHub