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
Cloning or downloading one of our demo projects on GitHub is definitely the fastest way to get started:
They also come pre-configured with the Gradle Wrapper, so you don’t need to install Gradle yourself. You can simply run ./gradlew
(Mac/Linux) or gradlew.bat
(Windows) from the project directory instead of the gradle
command.
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>
}
}
- append
folder1
as an extra simulations’ folder. - use
folder1
as a single source of simulations. - append
folder2
as an extraGatling
resources folder. - use
folder2
as a single source ofGatling
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 | ['java.net.preferIPv6Addresses': 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>
}
}
- all Scala files from plugin simulation dir subfolder
package1
ending withSimu
. - all Scala files from plugin simulation dir subfolder
package2
ending withSimulation
.
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>
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>
logHttp
is configured via plugin extension,TRACE
forALL
value andDEBUG
forFAILURES
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>
}
- adding gson library, available both in compile and runtime classpath.
- adding commons-lang3 to compile classpath for simulations.
- 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:
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 simulationSimulationFQN 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
Configure
role.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://gatling.io/docs/enterprise/cloud/reference/admin/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
.
Configure
role.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.