Gatling Gradle Plugin

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

This Gradle plugin was initially contributed by Ievgenii Shepeliuk and Laszlo Kishalmi.

This Gradle plugin integrates Gatling with Gradle, allowing to use Gatling as a testing framework.


Check out available versions on Gradle Plugins Portal.


Gradle version

The latest version of this plugin is tested against Gradle versions ranging from 7.1 to 8.6. Any version outside this range is not guaranteed to work.


If you prefer to manually configure your Gradle project rather than clone one of our samples, you need to add the following to your build.gradle:

 plugins {
   id 'io.gatling.gradle' version "MANUALLY_REPLACE_WITH_LATEST_VERSION"

Multi-project support

If you have a multi-project build, make sure to only configure the subprojects which contain Gatling Simulations with the Gatling plugin as described above. Your Gatling subproject can, however, depend on other subprojects.

Source files layout

The plugin creates a dedicated Gradle sourceSet named gatling. This source set is used for storing simulations and Gatling configurations. The following directories are configured by default.

Directory Purpose
src/gatling/java Simulation sources (Java code)
src/gatling/kotlin Simulation sources (Kotlin code)
src/gatling/scala Simulation sources (Scala code)
src/gatling/resources Resources (feeders, configuration, bodies, etc)

Using the Gradle API, file locations can be customized.

sourceSets {
  gatling {
    scala.srcDir "folder1" <1>
    // or
    scala.srcDirs = ["folder1"] <2>

    resources.srcDir "folder2" <3>
    // or
    resources.srcDirs = ["folder2"] <4>
  1. append folder1 as an extra simulations’ folder.
  2. use folder1 as a single source of simulations.
  3. append folder2 as an extra Gatling resources folder.
  4. use folder2 as a single source of Gatling resources.

Plugin configuration

The plugin defines the following extension properties in the gatling closure:

Property name Type Default value Description
gatlingVersion String The first 3 digits of this plugin’s version Gatling version
includeMainOutput Boolean true true
includeTestOutput Boolean true Include test source set output to gatlingImplementation
scalaVersion String '2.13.8' Scala version that fits your Gatling version
jvmArgs List
Additional arguments passed to JVM when executing Gatling simulations
systemProperties Map ['': true] Additional systems properties passed to JVM together with caller JVM system properties
simulation String A fully qualified class name that extends a Gatling Simulation The simulation to run
apiToken String null, optional Your Gatling Enterprise api token

How to override Gatling version, JVM arguments and system properties:

gatling {
  gatlingVersion = '3.8.3'
  jvmArgs = ['-server', '-Xms512M', '-Xmx512M']
  systemProperties = ['file.encoding': 'UTF-8']

Gatling configuration

Override gatling.conf settings

To override Gatling’s default parameters, put your own version of gatling.conf into src/gatling/resources.

Logging management

Gatling uses Logback. To change the logging behaviour, put your custom logback.xml configuration file in the resources folder, src/gatling/resources.

Dependency management

This plugin defines three Gradle configurations: gatling, gatlingImplementation and gatlingRuntimeOnly.

By default, the plugin adds Gatling libraries to gatling configuration. Configurations gatlingImplementation and gatlingRuntimeOnly extend gatling, i.e. all dependencies declared in gatling will be inherited. Dependencies added to configurations other than these ‘gatling’ configurations will not be available within Gatling simulations.

Also, project classes (src/main) and tests classes (src/test) are added to gatlingImplementation and gatlingRuntimeOnly classpath, so you can reuse existing production and test code in your simulations.

If you do not need such behaviour, you can use flags. Manage test and main output:

gatling {
  // do not include classes and resources from src/main
  includeMainOutput = false
  // do not include classes and resources from src/test
  includeTestOutput = false

Additional dependencies can be added to any of the configurations mentioned above. Add external libraries for Gatling simulations:

dependencies {
  gatling '' // <1>
  gatlingImplementation 'org.apache.commons:commons-lang3:3.4' // <2>
  gatlingRuntimeOnly 'cglib:cglib-nodep:3.2.0' // <3>
  1. adding gson library, available both in compile and runtime classpath.
  2. adding commons-lang3 to compile classpath for simulations.
  3. adding cglib to runtime classpath for simulations.


Running your simulations

Use the task GatlingRunTask to execute Gatling simulations. You can create your own instances of this task to run particular simulations, or use the default gatlingRun task.

By default, the gatlingRun task 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 --simulation=<FullyQualifiedClassName> option,
  • or the non-interactive mode is forced with the --non-interactive option, in which case the task will fail if there is more than 1 simulation available,
  • or the CI environment variable is set to true, in which case the task will fail if there is more than 1 simulation available.

For example, to run a simulation:

./gradlew gatlingRun
gradlew.bat gatlingRun

Run a single simulation by its FQN (fully qualified class name):

./gradlew gatlingRun --simulation com.project.simu.MySimulation
gradlew.bat gatlingRun --simulation com.project.simu.MySimulation

You can run all simulations with the --all option:

./gradlew gatlingRun --all
gradlew.bat gatlingRun --all

The following configuration options are available. Those options are similar to global gatling configurations. Options are used in a fallback manner, i.e. if an option is not set the value from the gatling global config is taken.

Property name Type Default value Description
simulation String The only class that extends a Gatling Simulation The simulation to run
jvmArgs List null Additional arguments passed to JVM when executing Gatling simulations
systemProperties Map<String, Object> null Additional systems properties passed to JVM together with caller JVM system properties
environment Map<String, Object> null Additional environment variables passed to the simulation

Running the Gatling Recorder

You can launch the Gatling Recorder:

./gradlew gatlingRecorder
gradlew.bat gatlingRecorder

Running your simulations on Gatling Enterprise Cloud


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 build.gradle:

gatling {
  enterprise {
    apiToken "YOUR_API_TOKEN"

Deploying on Gatling Enterprise Cloud

With gatlingEnterpriseDeploy 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, GatlingEnterpriseDeploy searches for the package descriptor in .gatling/package.conf. However, you can target a different filename in .gatling by using the following command:

gradle GatlingEnterpriseDeploy -Dgatling.enterprise.packageDescriptorFilename="<file name>"

Start your simulations on Gatling Enterprise Cloud

You can, using the gatlingEnterpriseStart command:

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:

./gradlew gatlingEnterpriseStart -Dgatling.enterprise.simulationName="<simulation name>"
gradlew.bat gatlingEnterpriseStart -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 setting -Dgatling.enterprise.batchMode=true.

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


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

./gradlew gatlingEnterprisePackage
gradlew.bat gatlingEnterprisePackage

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


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:

gatling {
  enterprise {
    packageId "YOUR_PACKAGE_ID"
    simulationId "YOUR_SIMULATION_ID" // If packageId is missing, the task will use the package linked to the simulationId

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:

./gradlew gatlingEnterpriseUpload
gradlew.bat gatlingEnterpriseUpload

Private packages

Configure the Control Plane URL:

gatling {
  enterprise {
    controlPlaneUrl "YOUR_CONTROL_PLANE_URL"

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 Gradle 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 Gradle or Gradle Wrapper.

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 build/libs/<artifactId>-<version>-tests.jar:

./gradlew gatlingEnterprisePackage
gradlew.bat gatlingEnterprisePackage

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 maven-publish plugin to use the task named gatlingEnterprisePackage, then define the repository to publish to:

plugins {
  id "maven-publish"

publishing {
  publications {
    mavenJava(MavenPublication) {
      artifact gatlingEnterprisePackage
  repositories {
    maven {
      if (project.version.endsWith("-SNAPSHOT")) {
      } else {

The packaged artifact will be deployed with the tests classifier when you publish it:

./gradlew publish
gradlew.bat publish


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

Edit this page on GitHub