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 Cloud#

Prerequisites#

You need to configure an an API token for most of the actions between the CLI and Gatling Enterprise Cloud.

Since you probably don’t want to include you secret token in your source code, you can configure it using either:

• the GATLING_ENTERPRISE_API_TOKEN environment variable
• the gatling.enterprise.apiToken Java System property

If really needed, you can also configure it in your pom.xml:

<plugin>
    <groupId>io.gatling</groupId>
    <artifactId>gatling-maven-plugin</artifactId>
    <version>${gatling-maven-plugin.version}</version>
    <configuration>
        <apiToken>YOUR_API_TOKEN</apiToken>
    </configuration>
</plugin>

Deploying on Gatling Enterprise Cloud#

With gatling:enterpriseDeploy command, you can:

• Create, update and upload packages
• Create and update simulations

This command automatically checks your simulation project and performs the deployment according to your configuration.

By default, enterpriseDeploy searches for the package descriptor in .gatling/package.conf. However, you can target a different filename in .gatling by using the following command:

mvn gatling:enterpriseDeploy -Dgatling.enterprise.packageDescriptorFilename="<file name>"

Start your simulations on Gatling Enterprise Cloud#

You can, using the gatling:enterpriseStart command:

• Automatically deploy your package and associated simulations
• Start a deployed simulation

By default, the Gatling plugin prompts the user to choose a simulation to start from amongst the deployed simulations. However, users can also specify the simulation name directly to bypass the prompt using the following command:

./mvnw gatling:enterpriseStart -Dgatling.enterprise.simulationName="<simulation name>"

mvnw.cmd gatling:enterpriseStart -Dgatling.enterprise.simulationName="<simulation name>"

Replace <simulation name> with the desired name of the simulation you want to start.

If you are on a CI environment, you don’t want to handle interaction with the plugin. Most CI tools define the CI environment variable, used by the Gatling plugin to disable interactions and run in headless mode.

It’s also possible to disable interactions by running Maven in batch mode.

Here are additional options for this command:

• -Dgatling.enterprise.waitForRunEnd=true: Enables the command to wait until the run finishes and fail if there are assertion failures.
• -Dgatling.enterprise.runTitle=<title>: Allows setting a title for your run reports.
• -Dgatling.enterprise.runDescription=<description>: Allows setting a description for your run reports summary.

Upload a package manually#

Packaging#

You can directly package your simulations for Gatling Enterprise Cloud using:

./mvnw gatling:enterprisePackage

mvnw.cmd gatling:enterprisePackage

This will generate the target/<artifactId>-<version>-shaded.jar package which you can then upload to the Cloud.

Upload#

You must already have configured a package. Copy the package ID from the Packages table, or copy the simulation ID linked to the package from the Simulations table.

Configure the package ID or simulation ID on the plugin:

<plugin>
    <groupId>io.gatling</groupId>
    <artifactId>gatling-maven-plugin</artifactId>
    <version>${gatling-maven-plugin.version}</version>
    <configuration>
        <packageId>YOUR_PACKAGE_ID</packageId>
        <!-- If packageId is missing, the task will use the package linked to the simulationId -->
        <simulationId>YOUR_SIMULATION_ID</simulationId>
    </configuration>
</plugin>

You can also configure either of those using Java System properties:

• packageId: gatling.enterprise.packageId
• simulationId: gatling.enterprise.simulationId

Then package and upload your simulation to Gatling Enterprise Cloud:

./mvnw gatling:enterpriseUpload

mvnw.cmd gatling:enterpriseUpload

Private packages#

Configure the Control Plane URL:

<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>${gatling-maven-plugin.version}</version>
  <configuration>
    <controlPlaneUrl>YOUR_CONTROL_PLANE_URL</controlPlaneUrl>
  </configuration>
</plugin>

Once configured, your private package can be created and uploaded using the deploy command.

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