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.

Versions#

Check out available versions on Gradle Plugins Portal.

Compatibility#

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.

Setup#

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.

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:

[
 ‘-server’,
 ‘-Xmx1G’,
 ‘-XX:+HeapDumpOnOutOfMemoryError’,
 ‘-XX:+UseG1GC’,
 ‘-XX:+ParallelRefProcEnabled’,
 ‘-XX:MaxInlineLevel=20’,
 ‘-XX:MaxTrivialSize=12’
]

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 'com.google.code.gson:gson:2.8.0' // <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.

Tasks#

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.

Running the Gatling Recorder#

You can launch the Gatling Recorder:

./gradlew gatlingRecorder

gradlew.bat gatlingRecorder

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 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:

• 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:

./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#

Packaging#

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.

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:

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.

Sources#

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

Edit this page on GitHub