Skip to content
Go to file


Failed to load latest commit information.
Latest commit message
Commit time


Gatling Plugin for Gradle


Plugin versioning scheme

Since version 3.0.0 the plugin strictly follows Gatling versioning, where the major and minor versions of the plugin are always identical to Gatling 's major and minor version.

Gradle version

Minimal supported Gradle version is 4.0.

Scala version

Gatling uses Scala version 2.12 since version 3.0.0, so the plugin does.

Source code layout

Since Gatling 3.0.0 and corresponding plugin version 3.x.x there were breaking changes for source code layout. Check corresponding section of this README for details and original Gatling issue explaining the scope of changes.



For those who are familiar with Gradle and Gatling, and probably having few already developed simulations - the recommended way is to jump right to Installation section and follow configuration guide to create build.gradle, organize source code and run performance tests.

The plugin provides bootstrap script that creates sample project with:

  • minimal build.gradle leveraging Gradle wrapper

  • latest version of this plugin applied

  • proper source file layout

  • sample Simulation class, demonstrating sufficient Gatling functionality

For this quickstart - git and curl must be instlled and available in $PATH.

Generate sample Gradle project and run Gatling simulation
curl -sL | bash -s ~/sample-gradle-gatling
Navigate to new project folder and run all simulations
cd ~/sample-gradle-gatling
./gradlew gatlingRun


  1. Install Gradle

  2. Create a new project directory, and a file name build.gradle within it

  3. Follow Gradle Plugin Portal instructions.

Source files layout

Plugin creates dedicated Gradle sourceSet named gatling. This source set is used for storing simulations and Gatling configs. Following directories are configured by default.

Directory Purpose


Simulation sources (Scala code)


Resources (feeders, configuration, bodies, etc)

Using 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




Gatling version




The default Gatling console log level if no logback.xml present in the configutation folder




Include main source set output to gatlingImplementation




Include test source set output to gatlingImplementation




scala version that fits your Gatling tool version



['-server', '-Xmx1G',
'-XX:+UseG1GC', '-XX:MaxGCPauseMillis=30',

Additional arguments passed to JVM when executing Gatling simulations


Map<String, Object>

['': true,
'': false]

Additional systems properties passed to JVM together with caller JVM system properties



{ include "**/*Simulation*.scala" }

Simulations filter. See Gradle docs for details.

How to override Gatling version, JVM arguments and system properties
gatling {
  toolVersion = '3.3.1'
  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 default parameters of Gatling just put own version of gatling.conf into src/gatling/resources.

Logging management

Gatling uses Logback to customize its output. To change logging behaviour, put your logback.xml into resources folder, src/gatling/resources.

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

Default logback.xml created by the plugin
<?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.

Dependency management

This plugin defines three Gradle configurations gatling, gatlingImplementation and gatlingRuntimeOnly. By default 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 don’t 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 by plugin’s users to any of 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.


Plugin provides GatlingRunTask that is responsible for executing Gatling simulations. Users may create own instances of this task to run particular simulations.

Following configuration options are available. Those options are similar to global gatling configurations. Options are used in a fallback manner, i.e. if option is not set the value from gatling global config is taken.

Property name Type Default value Description




Additional arguments passed to JVM when executing Gatling simulations


Map<String, Object>


Additional systems properties passed to JVM together with caller JVM system properties




Simulations filter. See Gradle docs for details.

Default tasks

Task name Type Description



Compiles Gatling simulation and copies resources



Executes all Gatling simulations configured by extension



Executes single Gatling simulation,
SimulationFQN should be replaced by fully qualified simulation class name.

Run all simulations
$ gradle gatlingRun
Run single simulation implemented in com.project.simu.MySimulation class
$ gradle gatlingRun-com.project.simu.MySimulation

Troubleshooting and known issues

Spring Boot and Netty version

Caused by io.spring.dependency-management plugin and Spring platform BOM files. The dependency management plugin ensures that all declared dependencies have exactly the same versions as declared in BOM. Since Spring Boot declares own Netty version (e.g. 4.1.22.Final) - this version is applied globally for all the configurations of the Gradle project, even if configuration doesn’t use Spring.

There’s 2 ways of solving the problem, depending on the actual usage of Netty in the project

  • When production code doesn’t rely on Netty

    ext['netty.version'] = '4.0.51.Final'

    This declares Netty version globally for all transitive dependencies in your project, including Spring.

  • When production code uses Netty

    dependencyManagement {
        gatling {
            dependencies {
                dependencySet(group: 'io.netty', version: '4.0.51.Final') {
                   entry 'netty-codec-http'
                   entry 'netty-codec'
                   entry 'netty-handler'
                   entry 'netty-buffer'
                   entry 'netty-transport'
                   entry 'netty-common'
                   entry 'netty-transport-native-epoll'

    This options ensures that 4.0.51.Final will be used only for gatling configurations, leaving other dependencies unchanged.

Release a new version

  1. NodeJS and Npm must be installed.

  2. Create GitHub access token. Only repo scope is required.

  3. Install release-it

    $ npm install -g release-it @release-it/conventional-changelog
  4. Run

    $ env GITHUB_TOKEN=${....} release-it --ci patch (1) (2)
    1. paste token value from step 2

    2. can be patch, minor, major

  5. Release script will create and push tag to GitHub, create a release with a changelog in GitHub and publish plugin to Gradle plugin portal.

You can’t perform that action at this time.