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 5.0 to 8.2. 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']
}

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"?>
<configuration>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
      <immediateFlush>false</immediateFlush>
    </encoder>
  </appender>
  <root level="${logLevel}"> <!--1-->
    <appender-ref ref="CONSOLE"/>
  </root>
</configuration>

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"?>
<configuration>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
      <immediateFlush>false</immediateFlush>
    </encoder>
  </appender>
  <logger name="io.gatling.http.engine.response" level="${logHttp}"/> <!--1-->
  <root level="${logLevel}"> <!--2-->
    <appender-ref ref="CONSOLE"/>
  </root>
</configuration>

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

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.

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:
    // https://docs.gatling.io/reference/install/cloud/private-locations/private-packages/
    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.

Package#

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")) {
        url "REPLACE_WITH_YOUR_SNAPSHOTS_REPOSITORY_URL"
      } else {
        url "REPLACE_WITH_YOUR_RELEASES_REPOSITORY_URL"
      }
    }
  }
}

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

gradle publish

Sources#

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

Edit this page on GitHub