Gatling

Introduction

Section A - Accompanying Documentation

 Table of contents

A1 - Section Overview 3

A2 - Gatling Introduction 4

A3 - Gatling Prerequisites 7
Java JDK 7
Scala Binaries 8
IntelliJ IDE & Scala Plugin 9

A4 - Install Gatling in Standalone Mode 10

A5 - Install Gatling via Maven 14

A6 - Install Gatling via SBT 17

A7 - Install Gatling via Gradle 20

Gatling Academy - Gatling Introduction - 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, Gradle or SBT

Gatling Academy - Gatling Introduction - 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. I​ t'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:

Gatling Academy - Gatling Introduction - Section A

Page 4
 Single virtual user per thread in a traditional JVM tool

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

Although Gatling is Scala code, the expressive DSL that it ships with means that users don't
need to know any Scala in order to write Gatling tests. Gatling comes with a really helpful
cheat sheet that you can refer to guide you in the creation of your test scenarios. The
documentation in the cheat sheet explains exactly what each DSL method in the Gatling
library does.

Gatling Academy - Gatling Introduction - 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 - 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 Scala 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 or 11 are recommended for Gatling as they have been tested
the most, but any version after 8 should work
● Scala 2.12
● 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:

$ javac -version
javac 1.8.0_192

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://www3.ntu.edu.sg/home/ehchua/programming/howto/JDK_Howto.html

This will take you to a guide that shows how to install the JDK on all different operating
systems.

Gatling Academy - Gatling Introduction - Section A

Page 7
Scala Binaries

The next thing we need to do is download the Scala binaries, it's important that you use
version ​2.12 of Scala ​with Gatling. Version 2.13 has some compatibility issues with Gatling
and won’t be supported until the next major release of Gatling.

Scala 2.12 can be downloaded from here: ​https://www.scala-lang.org/download/2.12.12.html

Download Scala Binaries

Save the Scala binaries somewhere on your computer, and you can import them into your
IDE once loading it for the first time.

Gatling Academy - Gatling Introduction - Section A

Page 8
IntelliJ IDE & Scala Plugin

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

Simply download it and follow the onscreen instructions to install.

When you run it for the first time, the IntelliJ landing page should load, and from here you
can install the Scala plugin. Click on "configure" and then "plugins". Make sure you're on the
marketplace and then type in "Scala"

And then next to the Scala plugin hit "install":

IntelliJ Scala Plugin

Gatling Academy - Gatling Introduction - Section A

Page 9
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 - Section A

Page 10
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 its 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 - Section A

Page 11
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 - Section A

Page 12
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 - Section A

Page 13
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

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.git

Cloning into ​'gatling-maven-plugin-demo'​...
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 - Section A

Page 14
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.

Note: If you see a message ​No Scala SDK in Module​ at the top of the IDE, then you may
need to configure Scala in IntelliJ. Follow the steps in ​this guide​ to get that setup.

Gatling Academy - Gatling Introduction - Section A

Page 15
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 - Section A

Page 16
A6 - Install Gatling via SBT
The easiest way to get started using Gatling with the Scala Build Tool (SBT) is to clone the
example project at:​ ​https://github.com/gatling/gatling-sbt-plugin-demo

It is required to have SBT 1 installed, which is available from the link above.

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-sbt-plugin-demo.git

Cloning into ​'gatling-sbt-plugin-demo'​...
remote: Enumerating objects: 5, ​done​.
remote: Counting objects: 100% (5/5), ​done​.
remote: Compressing objects: 100% (5/5), ​done​.
remote: Total 329 (delta 0), reused 3 (delta 0), pack-reused 324
Receiving objects: 100% (329/329), 43.58 KiB | 330.00 KiB/s, ​done​.
Resolving deltas: 100% (122/122), ​done​.

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.sbt​ file. Choose ​Open as Project​ when prompted.

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

There are two sample scripts in this project that we can view:

Gatling Academy - Gatling Introduction - Section A

Page 17
 Sample Gatling scripts in the SBT project in IntelliJ

Gatling Academy - Gatling Introduction - Section A

Page 18
To execute Gatling scripts through SBT inside IntelliJ, we first need to open a terminal within
the IDE, or in a standalone regular terminal. Type ​sbt ​to launch the Scala Build Tool.

With SBT running, we can run all the example scripts in our project (two in our case) with:

$sbt:> gatling:​test

Or to run a single test script, we can type:

$sbt> gatling:testOnly computerDatabase.BasicSimulation

Here we are providing the full path of the script, i.e. it lives in the ​computerDatabase
package and is called ​BasicSimulation

Once the test has finished, we can again up the ​index.html​ file within the ​target​ folder to
view the test report directly in the IDE. We simply need to right-click on the file and choose
Open in Browser

Gatling Academy - Gatling Introduction - Section A

Page 19
A7 - Install Gatling via Gradle
Please refer to ​https://github.com/gatling/gatling-gradle-plugin​ for detailed instructions on
how to run Gatling through Gradle.

Gatling Academy - Gatling Introduction - Section A

Page 20