Gatling

Introduction for
Java Users

Section A - Accompanying Documentation

 Table of contents

A1 - Section Overview 3

A2 - Gatling Introduction 4

A3 - Gatling Prerequisites 7
Java JDK 7
IntelliJ IDE 8

A4 - Install Gatling in Standalone Mode 9

A5 - Install Gatling via Maven 13

A6 - Install Gatling via Gradle 16

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 2
A1 - Section Overview
Section A of this module is titled Gatling Overview and Installation, this is what we are
going to cover:

● Overview of the Gatling tool, having a brief look at how it works and what makes it
such a powerful tool for stress and performance testing.
● Prerequisites required for proper Gatling script development
● Gatling installation:
○ Through standalone download
○ Through a build tool - Maven or Gradle

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 3
A2 - Gatling Introduction
Gatling is an open-source load and performance testing framework that's been around since
2012. The tagline on the official Gatling site is "Load test as code" and "The best developer
tool to load test your web applications"

Gatling.io website

At a high-level, we can say Gatling is an open-source load testing tool. It's written purely in
Scala and makes use of the AKKA and Netty frameworks.

This tech stack is extremely powerful for stress and performance testing because it
overcomes the JVM limitation of being able to handle single virtual users on threads.
Traditional JVM based load testing tools such as JMeter can only handle a single virtual user
per thread, as shown in the diagram below:

Single virtual user per thread in a traditional JVM tool

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 4
This severely limits the number of users that can be supported per load injector

Gatling is different because it supports a message-driven architecture. It can handle many

more virtual users, or messages, per thread. This is shown in the diagram below:

Gatling allows for many users per thread

Load test scripts in Gatling can be written in either Scala, Kotlin or Java. In fact, the
expressive DSL that it ships with means that users need only know little code in order to
write Gatling load tests.

The extensive Gatling documentation explains exactly what each DSL method in the Gatling
library does, for all of the supported languages. The documentation can be found online
here: https://gatling.io/docs/gatling/

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 5
Gatling also comes with a handy recorder application, to assist with script creation. This
recorder has two different modes: works in two different modes:

● HTTP Proxy Mode - runs as a proxy and captures all traffic, converting that traffic
into a Gatling script
● HAR Converter Mode - Save a HAR file from a user journey in your browser, and
convert that file into a Gatling script

We'll be seeing both of these modes in the course.

Gatling Recorder

Another great feature of Gatling is that because it represents a load test as code, it makes it
very easy to have this code stored in your version control system. In your Github repository,
for example, you can have your stress tests living side-by-side with your application code.

This makes it easy to run performance tests through your continuous integration solution.

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 6
A3 - Gatling Prerequisites
Before we go over the prerequisites that you should have installed in order to use Gatling
effectively, we should mention that because Gatling is simply code, you could just write
everything in a simple text editor.

But if you are doing any serious script development in Gatling, then it’s best to have the
following installed on your development machine:

● Java JDK - versions 8, 11 and 17 are recommended for Gatling as they have been
tested the most, but any version after 8 should work
● An IDE such as IntelliJ

Java JDK

You most likely already have Java installed on your machine. To check if you do, open a
terminal or command prompt and type:

$ java -version
openjdk version "11.0.2" 2019-01-15
OpenJDK Runtime Environment 18.9 (build 11.0.2+9)
OpenJDK 64-Bit Server VM 18.9 (build 11.0.2+9, mixed mode)

If Java is installed, you should see a message printed out telling you which version you have
installed.

In the event that you don't have Java installed, simply browse to
https://www.oracle.com/java/technologies/downloads/ , and download the appropriate
version for your operating system

If you require further installation instructions, refer to the JDK installation guide here -
https://docs.oracle.com/en/java/javase/18/install/overview-jdk-installation.html

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 7
IntelliJ IDE

The other thing required is an IDE. For this course, we will be using IntelliJ IDEA. IntelliJ can
be downloaded from here: https://www.jetbrains.com/idea/download

Simply download the Community edition, and follow the onscreen instructions to install.

IntelliJ Download Page

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 8
A4 - Install Gatling in Standalone Mode
If you want to get up and running with Gatling as quickly as possible, then the standalone
version is a great place to start.

Head over to https://gatling.io/open-source/ , and click Download Now!

Gatling Download Page

This will download a ZIP file, that you should save and extract somewhere on your machine.

Open up the directory that you just extracted, and change into the /bin folder.

To start Gatling from here, run either:

● gatling.bat - If you are using Windows

● gatling.sh - If you are using a Mac or Unix operating system

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 9
Once you run Gatling for the first time, you will be asked to choose a simulation number.
These are a few sample simulation scripts that Gatling ships with, that you can execute right
away:

$ ./gatling.sh
GATLING_HOME is set to
/Users/username/Desktop/gatling-charts-highcharts-bundle-3.3.1
Choose a simulation number:
[0] computerdatabase.BasicSimulation
[1] computerdatabase.RecordedSimulation
[2] computerdatabase.advanced.AdvancedSimulationStep01
[3] computerdatabase.advanced.AdvancedSimulationStep02
[4] computerdatabase.advanced.AdvancedSimulationStep03
[5] computerdatabase.advanced.AdvancedSimulationStep04
[6] computerdatabase.advanced.AdvancedSimulationStep05

Press 0 to execute the Basic Simulation.

Enter test for the run description and press enter. A Gatling stress test will execute against
the Computer Database Application and should last for 30 seconds or so. We will be seeing
more of this application later on, as it's the target application we will be creating our own
Gatling scripts against.

As the script is executing, every 5 seconds Gatling will print an update to the console with
the progress of the test:

========================================================================
2020-09-16 08:20:25 5s elapsed
---- Requests
------------------------------------------------------------------
> Global (OK=2
KO=0 )
> request_1 (OK=1
KO=0 )
> request_1 Redirect 1 (OK=1
KO=0 )

---- Scenario Name

-------------------------------------------------------------
[-----------------------------------------------------------------------
---] 0%
waiting: 0 / active: 1 / done: 0
========================================================================

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 10
At the end of the test, some high-level results are additionally shown in the console:

========================================================================
---- Global Information
--------------------------------------------------------
> request count 13 (OK=13
KO=0 )
> min response time 18 (OK=18
KO=- )
> max response time 41 (OK=41
KO=- )
> mean response time 23 (OK=23
KO=- )
> std deviation 6 (OK=6
KO=- )
> response time 50th percentile 21 (OK=21
KO=- )
> response time 75th percentile 22 (OK=22
KO=- )
> response time 95th percentile 32 (OK=32
KO=- )
> response time 99th percentile 39 (OK=39
KO=- )
> mean requests/sec 0.565 (OK=0.565
KO=- )
---- Response Time Distribution
------------------------------------------------
> t < 800 ms 13 (100%)
> 800 ms < t < 1200 ms 0 ( 0%)
> t > 1200 ms 0 ( 0%)
> failed 0 ( 0%)
========================================================================

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 11
As well as the results in the console, Gatling will also print out a link to the full test report that
is automatically created at the end of each test execution:

Please open the following file:

/Users/user/Desktop/gatling-charts-highcharts-bundle-3.3.1/results/basic
simulation-20200916072019032/index.html

We can open this index.html file to view the test report:

Gatling Results Report

The Gatling results report will be covered in greater detail later on in the course, but feel free to
explore the report yourself now in the meanwhile.

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 12
A5 - Install Gatling via Maven
The simplest way to get up and running with Gatling through Maven is to clone the example
project from the Gatling repository on GitHub -
https://github.com/gatling/gatling-maven-plugin-demo-java

If you aren’t familiar with how Git works, you can simply click on Code and Download ZIP:

Download the Gatling Maven Plugin Demo project

If you are comfortable with Git, then simply clone this repository onto your computer in the
normal way:

$ git clone
https://github.com/gatling/gatling-maven-plugin-demo-java.git
Cloning into 'gatling-maven-plugin-demo-java'...
remote: Enumerating objects: 49, done.
remote: Counting objects: 100% (49/49), done.
remote: Compressing objects: 100% (36/36), done.
remote: Total 436 (delta 20), reused 35 (delta 10), pack-reused 387
Receiving objects: 100% (436/436), 58.05 KiB | 667.00 KiB/s, done.
Resolving deltas: 100% (184/184), done.

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 13
We next need to import the project into our IDE, in this tutorial we will use IntelliJ.

From the IntelliJ landing page choose Open or Import, then browse to the folder that you
just cloned and locate the pom.xml file, and choose Open as Project when prompted.

IntelliJ will now import the project and the IDE will open up. Once the project loads, open the
folder structure on the left-hand side and double click on the BasicSimulation file:

Project folder structure in IntelliJ

This is the example Gatling simulation that we ran in the previous section.

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 14
To run Gatling scripts directly through IntelliJ, simply right-click on the Engine class in the
project and choose Run. This will launch Gatling as we saw previously, and run the example
script within our project directly through the IDE.

As before, we can see the logs and results being printed to the console in IntelliJ.

Once the test completes, we can view the test results report that gets created by opening the
target folder and locating the index.html file. Right-click and choose Open in Browser to
view the report:

View Gatling Results Report in IntelliJ

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 15
A6 - Install Gatling via Gradle
The official plugin for Gradle is available on the Gatling Github repository here:
https://github.com/gatling/gatling-gradle-plugin

As with Maven previously, the easiest way to get started is by cloning an example project
and adapting that for your requirements. You can find the an example project here:
https://github.com/gatling/gatling-gradle-plugin-demo-java

Gatling Gradle Plugin Demo Java Project on Github

You can browse to that repository and click Code > Download Zip, or you can clone the
project directly onto your machine through Git:

$ git clone
https://github.com/gatling/gatling-gradle-plugin-demo-java.git
Cloning into 'gatling-gradle-plugin-demo-java'...
remote: Enumerating objects: 58, done.
remote: Counting objects: 100% (58/58), done.
remote: Compressing objects: 100% (40/40), done.
remote: Total 58 (delta 15), reused 42 (delta 8), pack-reused 0
Unpacking objects: 100% (58/58), done.

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 16
Once the project has been cloned, we need to import it into IntelliJ. From the IntelliJ landing
page, choose Open or Import. Browse to the folder that you just cloned or downloaded, and
double-click on the build.gradle file. Choose Open as Project when prompted.

Select the build.gradle file

Gradle will import the project and all the required dependencies for Gatling into IntelliJ.

Once everything has been imported, we can run the sample script that ships with the project
by executing the following:
$ ./gradlew gatlingRun-computerdatabase.BasicSimulation

We could also run every script that exists within our project by simply executing:
$ ./gradlew gatlingRun

For full instructions on using the Gatling Gradle plugin, check out the official documentation
here: https://gatling.io/docs/current/extensions/gradle_plugin/

Gatling Academy - Gatling Introduction for Java Users - Section A

Page 17