Running Gatling through Gradle – Complete Beginner’s Guide

I have been using the stress testing tool Gatling alot recently. It is becoming one of my favourite performance testing tools. There is decent getting started documentation on the Gatling website. But this involves downloading a zip file, then running a BAT or SH script to launch Gatling. You then select the test you want to run from the list.
 
It would be much nicer to do all the above through Gradle. Not to mention more convenient. Particularly if you want to run Gatling tests as part of Continuous Integration. One of the big advantages of doing that, is that you can have Gatling fail your CI build if a certain performance threshold is breached (such as too many errors, or average response time being too great etc.)
 
Fortunately there are some good Gatling through Gradle plugins out there. Not so fortunate, the documentation around getting any of these working is lacking. Especially if you are new to Gradle, Gatling or any of this stuff in general.
 
Not to worry! This Complete Beginners Guide to Running Gatling through Gradle will have you setup and ready to go in no time.
 
To make this guide even more beginner friendly, we will configure it through an IDE (Intellij). Once the setup is done and working, you can switch to running solely through the command line if you wish.
 
Let me mention from the outset that I won’t be going into detail on Gatling in this post. I will publish a followup post with a comprehensive introduction to Gatling. This post’s focus is on getting you up and running with Gatling through Gradle in no time.

Prerequisites

 

Before we begin, you should check off the list of 5 prerequisites below. Most likely you will have some if not all of them already. But I have listed them all here for completeness. Along with guides for installing each.
 
1. Java 8 JDK
 You probably have this already. But if not, I have a guide on my site here. There is also an in depth guide on installing the JDK, for all OS types, here.
 
2. Gradle 3.1 +
 Suggest that you grab the latest version. See these guides:
 
4. Scala SDK
Download the Scala SDK binaries from here and unpack the archive. Note that I am not installing the SBT (Scala Build Tool). If you have no idea what I’m talking about, just don’t worry!
As the guide says, you should add scala and scalac to your path. This is the same method as when you setup the Java JDK. See the 2 guides above if you need a reminder. As per the Scala instructions, the default folders are as follows:
Check that Scala is installed by launching a command prompt or terminal and typing scala.
 
5. Intellij Scala Plugin
That’s all the prerequisites done. Now let’s get on to actually running Gatling through Gradle!
 
There are quite a few different Gatling plugins out there for Gradle. The one that I have had the most success with is from lkishalmi . See the Github page for the Gatling Gradle Plugin for more information. We will be downloading the plugin through Gradle as part of the guide.
 

The 10 Step Guide To Running Gatling through Gradle

 
1. Open up Intellij and go to the landing page. Select “Create New Project“. Select Gradle, and deselect all libraries for the time being. Click next.
 
 
2. Enter a GroupID and ArtifactID. Click next. Tick ‘Auto Import‘ and ‘Create directories for empty content roots automatically‘. Click next. Enter a project name and location, then click finish.
 
 
3. When the project loads, open up the ‘build.gradle‘ file from the directory structure. Copy in the following code:
 
plugins {
    id "com.github.lkishalmi.gatling" version "0.4.1"
}

repositories {
    mavenCentral()
}

apply plugin: 'scala'

dependencies {
    compile 'org.scala-lang:scala-library:2.11.8'
}

 

Note: you might see a popup in Intellij as in the image below. Click on “Ok, apply suggestion!
 
 
4. Once you enter this code in the build.gradle file, Intellij should automatically build the project for you. If it doesn’t, simply right-click on the build.gradle file and select ‘Build Module‘.
 
 
5. Once the project has finished building, you should see that directory structure is created as in the screenshot.
 
 
6. Go into the folder src > gatling > scala . Right click and create a new package called ‘techietester‘.
 
 
7. Inside that new package, right click again and choose New Scala Class. Give the class a name of ‘BasicSimulation‘.
 
 
 
 
8. Copy in the following code to the BasicSimulation.scala class. This code is your Gatling script
 
package techietester

import io.gatling.http.Predef._
import io.gatling.core.Predef._

class BasicSimulation extends Simulation {

  val httpConf = http.baseURL("https://api.football-data.org/")

  val scn = scenario("Basic Simulation")
    .exec(http("request_1")
    .get("v1/teams/73"))
    .pause(5)

  setUp(
    scn.inject(atOnceUsers(1))
  ).protocols(httpConf)

}
9. Open up a command prompt / terminal. and browse to your root project folder. You can also do this in Intellij by pressing ALT + F12. Type gradlew gatlingRun . Your Gatling load test will execute!
 
 
10. The load test report generated by Gatling will be created in a folder like: C:\Work\gatling-gradle\build\reports\gatling\basicsimulation-1491462217892\index.html . It should look look something like this:
 
 

ADDITIONAL NOTES

  • Once you start developing additional scripts (i.e. tests), you can specify the name of the script that you want to run through Gradle. To do that, use the following command instead, specifying the full package name: gradlew gatlingRun-com.concur.BasicSimulation
  • It is important to stick with the directory structure that the plugin creates in order to successfully run Gatling scripts. At the moment the folder structure is not configurable, although this feature may be added at a later date. See this post for more information.
  • To successfully turn on logging, I had to add the following file in src > gatling > resources > conf > logback.xml . I wasn’t able to get logging to work as I wanted through the plugin, but adding this logback.xml file here worked instead. With this, you can change the logging level to whatever you like (trace, debug, warn etc.) . You can also turn logging on only for failing requests, which can be useful when running in production:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>

   <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
         <pattern>%d{HH:mm:ss.SSS} [%-5level] %logger{15} - %msg%n%rEx</pattern>
         <immediateFlush>false</immediateFlush>
      </encoder>
   </appender>

   <!-- Uncomment for logging ALL HTTP request and responses -->
   <logger name="io.gatling.http.ahc" level="TRACE" />
   <logger name="io.gatling.http.response" level="TRACE" />
   <!-- Uncomment for logging ONLY FAILED HTTP request and responses -->
   <!--   <logger name="io.gatling.http.ahc" level="DEBUG" /> -->
   <!--    <logger name="io.gatling.http.response" level="DEBUG" /> -->

   <root level="WARN">
      <appender-ref ref="CONSOLE" />
   </root>

</configuration>

 

  • I ran into issues getting Scala setup through Intellij, as in this post on Stack Overflow . I found that adding the following 4 lines to my build.gradle file fixed the issue:
ScalaCompileOptions.metaClass.daemonServer = true
ScalaCompileOptions.metaClass.fork = true
ScalaCompileOptions.metaClass.useAnt = false
ScalaCompileOptions.metaClass.useCompileDaemon = false
 
Incidentally, I was able to delete these 4 lines after the Gradle project built, and I didn’t need to reenter them again. Most likely it’s a configuration issue on my machine, but I thought it was worth mentioning in case anyone else has an issue.
 
You should now be up and running with Gatling through Gradle! I will be creating a followup post that gives a comprehensive introduction to Gatling.
 
I hope you found this post useful. Please let me know if there is anything else you think should be included, and I will try to add it.
  • daybirth zapata

    Hi James, can you tell me what program did you use to make the videos? Tanks!!

    • James Willett

      Hey, I’m using a combination of Snagit and Camtasia, both from Techsmith. You can get them both in a bundle.

  • Pingback: Testing Bits – 4/9/17 – 4/15/17 | Testing Curator Blog()

  • Pingback: Gatling Introduction - High Level Overview of the Stress Test Tool()

  • Vishal Patidar

    https://uploads.disquscdn.com/images/b14bc083868adc3a6e504ab9d02a29080d79b4e6121f7aafadfbbe008a186e2f.png Hi James,

    I came to this blog via your REST Assured course that I joined recently.

    I am running into a problem at Step 4 (after adding the code) the build isn’t created (neither automatically nor manually).
    Please see the screen shot.

    Could you please suggest where I am doing things incorrectly.

    Thank you,
    Vishal

  • Nikhil Nana

    Hi James. Great into. You mentioned in the intro its possible to fail the build for CI.
    How do you fail the build based on threshold values?
    Thanks.

  • chandan hks

    Hi James. Very nice blog and very informative. I am new to Gatling and Gradle, please help me out as I am facing an issue. I am not able to get the “src” folder and its other folder structure when i gave build module after copying the code into “build.gradle” file. Please let me know what can i do. I followed every step mentioned here.
    Thanks

  • Yunesh Shalika Senarathna

    Hi James,
    I got this, “only buildscript {} and other plugins {} script blocks are allowed before plugins {} blocks, no other statements are allowed” while building the build.gralde, I did paste exact same code you that have provided in the blog above. Non of the R&D helped. Could you please advice on this? https://uploads.disquscdn.com/images/eab262b8d0857d6450b9223541fe637227fd6abfd2a74ff4e2c533d1a479335f.png

    • https://james-willett.com James Willett

      Looking at the error, you just need to move “group” and “version” lower in the file (or you can delete them altogether and I don’t think it would matter here).

      It looks like you are using Gradle version 4.4, I believe when I wrote this post I used Gradle version 3, so thats probably why you are getting this error

      • Yunesh Shalika Senarathna

        Hi James,
        Thanks for the response, yes I am in gradle 4.2.1 and it worked your way for me, by removing the “Group” and “Version”. But I had to create src file structure manually as it did not auto create here.
        Thanks

  • Rakesh Sharma

    Hi James,

    While executing the script I an getting following :
    :compileJava NO-SOURCE
    :compileScala NO-SOURCE
    :processResources NO-SOURCE

    https://uploads.disquscdn.com/images/a2cd505b3207cac97315b8645401ff9a244c5c9df19c54b9b02f32b483f009a2.png
    Please advice what is wrong, I have followed all the above described steps

    • https://james-willett.com James Willett

      Hi Rakesh,

      Looking at the error it seems that your Gatling classes aren’t getting picked up by the plugin – is the directory structure definitely the same as in the post? Do you see any other errors in Intellij when creating the project ?

      James

      • Rakesh Sharma

        Thanks James, yes directory structure same as in post. There are no other errors in Intellij https://uploads.disquscdn.com/images/7e8f06b26314a10e11fed2769910d8a920a58f1dea5dd67a22ad447dede5c63c.png

        • Rakesh Sharma

          Interestingly when I hit the following command it executed successfully
          ./gradlew gatlingRun-com.softcell.headless.BasicSimulation

          • https://james-willett.com James Willett

            That makes sense – when using this command you are specifying exactly which script to run…. with just “./gradlew gatlingRun” it will only execute if there is no other script that it can find.