Gradle Plugin

The Gradle plugin allows you to run Gatling test from the command line, without the bundle

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.

Setup#

In build.gradle, add:

 plugins {
   id 'io.gatling.gradle' version "MANUALLY_REPLACE_WITH_LATEST_VERSION"
 }

Demo sample#

You can find a sample project demoing the io.gatling.gradle plugin in Gatling’s Github organization.

Compatibility#

Gradle version

• Minimal supported Gradle version is 4.0.
• Maximum version is 6.6.1

Scala version

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

Installation#

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 configurations. Following directories are configured by default.

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:

[
  ‘-server’,
  ‘-Xmx1G’,
  ‘-XX:+HeapDumpOnOutOfMemoryError’,
  ‘-XX:+UseG1GC’,
  ‘-XX:+ParallelRefProcEnabled’,
  ‘-XX:MaxInlineLevel=20’,
  ‘-XX:MaxTrivialSize=12’,
  ‘-XX:-UseBiasedLocking’
]

How to override Gatling version, JVM arguments and system properties

gatling {
  toolVersion = '3.4.0'
  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"?>
<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:

<?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, 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 by plugin’s users to any of 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#

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.

Default tasks#

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#

Original issue

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 does not use Spring.

There are 2 ways of solving the problem, depending on the actual usage of Netty in the project.

• When production code does not rely on Netty:

build.gradle:

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:

build.gradle:

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'
      }
    }
  }
}

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

Sources#

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

Edit this page on GitHub