Documentation Index
Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt
Use this file to discover all available pages before exploring further.
The Gatling Gradle plugin integrates Gatling into your Gradle build, providing a dedicated gatling source set, task configuration, and first-class support for deploying and launching simulations on Gatling Enterprise Edition. Originally contributed by the community, the plugin is now officially maintained by the Gatling team.
Clone one of the official demo projects to get started immediately — they come pre-configured with the Gradle Wrapper: Versions
Available versions are listed on the Gradle Plugin Portal.
Compatibility
This plugin requires Gradle 7.6 or later. It is tested against Gradle versions 7.1 through 8.6; versions outside that range are not guaranteed to work.
Inconsistent JVM-target compatibility detected, force the Java bytecode version in your build.gradle.kts:
tasks.withType(JavaCompile::class) {
options.release.set(21)
}
kotlin {
compilerOptions {
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
}
}
Setup
plugins {
id 'io.gatling.gradle' version "MANUALLY_REPLACE_WITH_LATEST_VERSION"
}
plugins {
id("io.gatling.gradle") version "MANUALLY_REPLACE_WITH_LATEST_VERSION"
}
Multi-Project Builds
Only configure subprojects that contain Gatling simulations with the Gatling plugin. Your Gatling subproject can still depend on other subprojects.
Source File Layout
The plugin creates a dedicated gatling Gradle source set with the following default directories:
| Directory | Purpose |
|---|
src/gatling/java | Simulation sources (Java) |
src/gatling/kotlin | Simulation sources (Kotlin) |
src/gatling/scala | Simulation sources (Scala) |
src/gatling/resources | Resources (feeders, config, bodies) |
sourceSets {
gatling {
scala.srcDir "custom/simulations"
resources.srcDirs = ["custom/resources"]
}
}
Plugin Configuration
Configure the gatling extension block to override defaults:
gatling {
gatlingVersion = '3.13.5'
jvmArgs = ['-server', '-Xms512M', '-Xmx512M']
systemProperties = ['file.encoding': 'UTF-8']
}
| Property | Type | Default | Description |
|---|
gatlingVersion | String | First 3 digits of plugin version | Gatling core version to use |
includeMainOutput | Boolean | true | Include src/main output on classpath |
includeTestOutput | Boolean | true | Include src/test output on classpath |
scalaVersion | String | 2.13.18 | Scala version for Scala simulations |
jvmArgs | List | Server JVM defaults | JVM arguments passed when running simulations |
systemProperties | Map | [] | Extra system properties for the JVM |
simulation | String | — | Fully qualified simulation class name |
apiToken | String | null | Gatling Enterprise Edition API token |
Dependency Management
The plugin defines three Gradle configurations: gatling, gatlingImplementation, and gatlingRuntimeOnly. Add external libraries as follows:
dependencies {
gatling 'com.google.code.gson:gson:2.8.0' // compile + runtime
gatlingImplementation 'org.apache.commons:commons-lang3:3.4' // compile only
gatlingRuntimeOnly 'cglib:cglib-nodep:3.2.0' // runtime only
}
Running Simulations
Use the gatlingRun task to execute simulations:
Run a single simulation by its fully qualified class name:
./gradlew gatlingRun --simulation com.example.MySimulation
gradlew.bat gatlingRun --simulation com.example.MySimulation
./gradlew gatlingRun --all
gatlingRun task runs interactively unless the CI environment variable is set to true or --non-interactive is passed, in which case it fails if more than one simulation is found.
| Task option | Type | Description |
|---|
--simulation | String | Simulation class FQN to run |
--jvmArgs | List | Extra JVM arguments |
--systemProperties | Map | Extra system properties |
--environment | Map | Extra environment variables |
--run-description | String | Description inserted in HTML reports |
--all | boolean | Run all simulations sequentially |
--same-process | boolean | Run Gatling in the Gradle process (for debugging) |
Running the Recorder
./gradlew gatlingRecorder
Running Simulations on Gatling Enterprise Edition
Prerequisites
You need a Gatling Enterprise Edition API token with the Configure role on the target teams. Store it securely using one of:
- The
GATLING_ENTERPRISE_API_TOKEN environment variable
- The
gatling.enterprise.apiToken Java system property
If needed, the token can also be configured in build.gradle:
gatling {
enterprise {
apiToken "YOUR_API_TOKEN"
}
}
Deploying to Gatling Enterprise Edition
Deploy your package and update simulations automatically:
./gradlew gatlingEnterpriseDeploy
./gradlew gatlingEnterpriseDeploy -Dgatling.enterprise.packageDescriptorFilename="mypackage.conf"
Starting Simulations on Gatling Enterprise Edition
./gradlew gatlingEnterpriseStart
gradlew.bat gatlingEnterpriseStart
./gradlew gatlingEnterpriseStart -Dgatling.enterprise.simulationName="My Simulation"
-Dgatling.enterprise.waitForRunEnd=true — Wait for the run to complete; fail if assertions fail.-Dgatling.enterprise.runTitle=<title> — Set a title for the run report.-Dgatling.enterprise.runDescription=<description> — Set a description for the run summary.-Dgatling.enterprise.batchMode=true — Disable interactive prompts for CI environments.
Packaging for Manual Upload
./gradlew gatlingEnterprisePackage
gradlew.bat gatlingEnterprisePackage
build/libs/<artifactId>-<version>-tests.jar for manual upload to Gatling Enterprise Edition.
Private Packages
Configure the Control Plane URL for private location deployments:
gatling {
enterprise {
controlPlaneUrl "YOUR_CONTROL_PLANE_URL"
}
}
Sources
Plugin source code is available on GitHub: gatling/gatling-gradle-plugin.