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 5.0 to 8.2. 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
logLevel String 'WARN' The default Gatling console log level if no logback.xml present in the configuration folder
logHttp String 'NONE' Verbosity of logging HTTP requests performed by Gatling, must be one of:
* 'NONE' - do not log,
* 'ALL' - log all requests,
* 'FAILURES' - only failed requests
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
simulations Closure include("**/*Simulation*.java", "**/*Simulation*.kt", "**/*Simulation*.scala") Simulations filter. See Gradle docs for details.

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

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

How to filter simulations:

gatling {
  simulations = {
    include "**/package1/*Simu.scala" // <1>
    include "**/package2/*Simulation.scala" // <2>
  1. all Scala files from plugin simulation dir subfolder package1 ending with Simu.
  2. all Scala files from plugin simulation dir subfolder package2 ending with Simulation.

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.

If no custom logback.xml file is provided, by default the plugin will implicitly use the following configuration:

<?xml version="1.0" encoding="UTF-8"?>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
  <root level="${logLevel}"> <!--1-->
    <appender-ref ref="CONSOLE"/>
  1. logLevel is configured via plugin extension, WARN by default.

In case logHttp is configured (except for 'NONE'), the generated logback.xml will look like this:

<?xml version="1.0" encoding="UTF-8"?>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
  <logger name="io.gatling.http.engine.response" level="${logHttp}"/> <!--1-->
  <root level="${logLevel}"> <!--2-->
    <appender-ref ref="CONSOLE"/>
  1. logHttp is configured via plugin extension, TRACE for ALL value and DEBUG for FAILURES
  2. logLevel is configured via plugin extension, WARN by default.

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

Task name Type Description
gatlingClasses Compiles Gatling simulation and copies resources
gatlingRun GatlingRunTask Executes all Gatling simulations configured by extension
gatlingRun-SimulationFQN GatlingRunTask Executes single Gatling simulation
SimulationFQN should be replaced by fully qualified simulation class name.

For example, run all simulations:

gradle gatlingRun

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

gradle gatlingRun-com.project.simu.MySimulation

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
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
environmentVariables Map<String, Object> null Additional environment variables passed to the simulation
simulations Closure null See Gradle docs for details.

Working with Gatling Enterprise Cloud

API tokens

You need to configure an an API token for most of the tasks regarding Gatling Enterprise Cloud. The API token needs the Configure role.

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"

Create or start a simulation

You can, using the GatlingEnterpriseStart task:

  • configure a new simulation on Gatling Enterprise Cloud, upload your packaged code, and immediately start the simulation
  • or, for a simulation already configured on Gatling Enterprise Cloud, upload any updated code and immediately start the simulation

Quick usage:

  • configure and start a new simulation with gradle gatlingEnterpriseStart, you will be prompted to choose all required options. This will also print the simulationId of the newly configured simulation.
  • run the simulation again with gradle gatlingEnterpriseStart -Dgatling.enterprise.simulationId=<YOUR_SIMULATION_ID>.
  • run the simulation and wait for the end of the run (will regularly print out progress information, and exit with an error code if the simulation fails) with gradle gatlingEnterpriseStart -Dgatling.enterprise.simulationId=<YOUR_SIMULATION_ID> -Dgatling.enterprise.waitForRunEnd=true.

List of configurations used by this task:

gatling {
  enterprise {
    // Simulation that needs to be started, you will be able to create a new simulation if empty, you can also use the gatling.enterprise.simulationId system property
    simulationId "YOUR_SIMULATION_ID"
    // Default package when creating a new simulation, you can also use the gatling.enterprise.packageId system property
    packageId "YOUR_PACKAGE_ID"
    // Default team when creating a new simulation, you can also use the gatling.enterprise.teamId system property
    teamId "YOUR_TEAM_ID"
    // Default simulation fully qualified classname used when creating a new simulation, you can also use the gatling.enterprise.simulationClass system property
    simulationClass "computerdatabase.BasicSimulation"
    // Custom system properties used when running the simulation on Gatling Enterprise
    systemProps(["KEY_1": "VALUE_1", "KEY_2": "VALUE_2"])
    // Additional environment variables used when running the simulation on Gatling Enterprise
    environmentVariables(["KEY_1": "VALUE_1", "KEY_2": "VALUE_2"])
    // Wait for the result after starting the simulation on Gatling Enterprise; will complete with an error if the simulation ends with any error status
    // False by default; you can also use the gatling.enterprise.waitForRunEnd system property
    waitForRunEnd false
    // Set to true if you don't want any user input, eg in a CI environment
    // False by default; you can also use the gatling.enterprise.batchMode system property
    batchMode false
    // If this URL is configured, newly created packages and uploaded ones are considered as private.
    // Private packages are uploaded and managed through this control plane.
    // Null by default; you can also use the gatling.enterprise.controlPlaneUrl system property
    // See Private Packages on Gatling Cloud documentation for details:
    controlPlaneUrl "YOUR_CONTROL_PLANE_URL"

You can run it with the command:

gradle gatlingEnterpriseStart

If a simulationId is set, the task will start the simulation on Gatling Enterprise.

If no simulationId is set, the task will ask you if you want to start or create a new simulation. If you choose create, you will be able to configure a new simulation (with the configured packageId, teamId, simulationClass as default), then start it. If you choose start, you will be able to start an already existing simulation on Gatling Enterprise.

If you are on a CI environment, you don’t want to handle interaction with the plugin. You should then set the batchMode option to true. In batch mode, no input will be asked from the user, the new simulation will be created using only the configuration.


Use the task GatlingEnterprisePackageTask to package your simulation for Gatling Enterprise Cloud:

gradle gatlingEnterprisePackage

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

Package and upload

You can also create and upload the package in a single command, using the GatlingEnterpriseUploadTask.

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:

gradle gatlingEnterpriseUpload

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

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

gradle publish


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

Edit this page on GitHub