Gatling logo, used with permission.
Update 2020-04-07: This article has been updated for Gatling 3.3.1 as described here.
This is the first part in a series of posts in which I will present a written version of a workshop I recently held on load testing with Gatling. The target audience of the workshop was Java developers without any previous experience of Gatling and this series of articles is not different in this area.
Since I myself like concrete examples, the workshop was based a number of examples. A project containing all the examples is available on GitHub.
If you want to start from scratch, I recommend reading my previous article on how to create a Scala project that uses Maven in IntelliJ IDEA.
Let’s get started!
Example 1 – Sending One Request
In this first example we will learn the basic structure of a Gatling load simulation, we will see how to execute arbitrary Scala code before and after the load simulation. The load simulation will consists of one simulated user sending one single request to a URL. In addition we will take a look at a report created by Gatling.
The first Gatling load simulation example looks like this:
package se.ivankrizsan.gatling.simulations
import io.gatling.core.Predef._
import io.gatling.core.structure.ScenarioBuilder
import io.gatling.http.Predef._
import io.gatling.http.protocol.HttpProtocolBuilder
import io.gatling.http.request.builder.HttpRequestBuilder.toActionBuilder
/**
* Example Gatling load test that sends one HTTP GET requests to a URL.
* Note that the request is redirected and this causes the request count to become two.
* Run this simulation with:
* mvn -Dgatling.simulation.name=HttpSimulation1 gatling:test
*
* @author Ivan Krizsan
*/
class HttpSimulation1 extends Simulation {
/* Place for arbitrary Scala code that is to be executed before the simulation begins. */
before {
println("***** My simulation is about to begin! *****")
}
/* Place for arbitrary Scala code that is to be executed after the simulation has ended. */
after {
println("***** My simulation has ended! ******")
}
/*
* A HTTP protocol builder is used to specify common properties of request(s) to be sent,
* for instance the base URL, HTTP headers that are to be enclosed with all requests etc.
*/
val theHttpProtocolBuilder: HttpProtocolBuilder = http
.baseUrl("https://computer-database.gatling.io")
/*
* A scenario consists of one or more requests. For instance logging into a e-commerce
* website, placing an order and then logging out.
* One simulation can contain many scenarios.
*/
/* Scenario1 is a name that describes the scenario. */
val theScenarioBuilder: ScenarioBuilder = scenario("Scenario1")
.exec(
/* myRequest1 is a name that describes the request. */
http("myRequest1")
.get("/")
)
/*
* Define the load simulation.
* Here we can specify how many users we want to simulate, if the number of users is to increase
* gradually or if all the simulated users are to start sending requests at once etc.
* We also specify the HTTP protocol builder to be used by the load simulation.
*/
setUp(
theScenarioBuilder.inject(atOnceUsers(1))
).protocols(theHttpProtocolBuilder)
}
Note that:
- Gatling load simulations are written in Scala files, one load simulation being one Scala class.
This enables us, as we will see in a later example, to use inheritance to specify common properties of, for instance, a type of load simulations in a base class which is later used as a parent class for concrete load simulations. - The class HttpSimulation1 extends the class Simulation.
Simulation is the Gatling class which is parent-class to Gatling load simulations. - There is a before { … } block that contains one println-statement.
The before-block contains arbitrary Scala code that is to be executed before the load simulation is run. - Similar to the before { … } block, there is an after { … } block.
As the name indicates, the after-block contains arbitrary Scala code that is to be executed after the load simulation has finished running. - There is an immutable instance variable (val) named theHttpProtocolBuilder that is assigned something that takes an URL as parameter.
In Scala, val denotes a variable that can be assigned a value once and only once, similar to Java’s final. Since this variable appears outside of any methods, it is, as would also be the case in Java, an instance variable.
The http variable contains a reference to a Gatling HTTP protocol builder, which is used to specify properties of HTTP requests that are to be sent. Such properties may be the URL to which the request is to be sent, the HTTP headers to enclose with requests etc.
The different methods of the HTTP protocol builder each returns a HTTP protocol builder instance, which creates a fluent API for configuring the HTTP protocol builders. - In a similar fashion, there is an immutable instance variable named theScenarioBuilder that is assigned a new ScenarioBuilder instance with the name Scenario1.
A scenario is a number of HTTP requests that are the result of the actions of one (simulated) user. If we take a shopping website as example, a scenario can consist of logging in, selecting a number of items to order, proceeding to checkout, paying for the order and logging out.
In this example, the scenario Scenario1 consists of one single action; a HTTP request named myRequest1 that sends a GET request to “/” relative to the base URL of the HTTP protocol builder used in conjunction with the scenario. - Finally there is a call to the setUp method in which the following three entities are combined:
– A scenario.
– A number of users, one in this example.
– A protocol builder.
Thus this call specifies the actions that are to be performed, which protocol is to be used to perform the actions and how many simulated users that are to perform the actions.
To run the simulation, we execute this command in the terminal:
mvn -Dgatling.simulation.name=HttpSimulation1 clean gatling:test
Load Simulation Text Report
Having run the load simulation, there should be output similar to this in the terminal as the simulation is executed:
Simulation se.ivankrizsan.gatling.simulations.HttpSimulation1 started...
***** My simulation is about to begin! *****
================================================================================
2016-04-14 20:57:03 0s elapsed
---- Scenario1 -----------------------------------------------------------------
[ ] 0%
waiting: 1 / active: 0 / done:0
---- Requests ------------------------------------------------------------------
> Global (OK=0 KO=0 )
================================================================================
================================================================================
2016-04-14 20:57:04 0s elapsed
---- Scenario1 -----------------------------------------------------------------
[##########################################################################]100%
waiting: 0 / active: 0 / done:1
---- Requests ------------------------------------------------------------------
> Global (OK=2 KO=0 )
> myRequest1 (OK=1 KO=0 )
> myRequest1 Redirect 1 (OK=1 KO=0 )
================================================================================
Simulation finished
***** My simulation has ended! ******
Parsing log file(s)...
Parsing log file(s) done
Generating reports...
================================================================================
---- Global Information --------------------------------------------------------
> request count 2 (OK=2 KO=0 )
> min response time 143 (OK=143 KO=- )
> max response time 167 (OK=167 KO=- )
> mean response time 155 (OK=155 KO=- )
> std deviation 12 (OK=12 KO=- )
> response time 50th percentile 155 (OK=155 KO=- )
> response time 75th percentile 161 (OK=161 KO=- )
> mean requests/sec 5.65 (OK=5.65 KO=- )
---- Response Time Distribution ------------------------------------------------
> t < 800 ms 2 (100%)
> 800 ms < t < 1200 ms 0 ( 0%)
> t > 1200 ms 0 ( 0%)
> failed 0 ( 0%)
================================================================================
Reports generated in 0s.
Note that:
- First Gatling generates output saying that the simulation HttpSimulation1 has started.
- Next we see output from the println statement in the before { … } block in the simulation class.
- The next part of the text-version of the Gatling report consists of a number of reports showing the progress of the scenario of the simulation.
In this example there are only two such reports, since the simulation only consists of one request. - After having run the simulation, Gatling tells us that “Simulation finished”.
- Then there is the output from the println statement in the after { … } block in the simulation class.
- Finally there is a text-version of the global information part of the simulation report shown along with a section showing the distribution of the response times of the requests in the simulation.
The global information part tells us, among other things, how many requests succeeded (OK) and how many requests failed (KO). - Remember I said that the simulation only sent one single requests, but we can clearly see that the request count is two in the report.
If we look at the last progress report of the simulation run, we can see that it says “myRequest1 Redirect 1”.
The original request was redirected and Gatling followed the redirection and sent a second request.
Load Simulation Graphical Report
The report printed to the terminal is not bad, but where Gatling really shines, in my opinion, is the graphical reports it produces.
To view the graphical report for this first simulation, expand the target directory, then expand the gatling director, then the results directory and finally the directory which name starts with “httpsimulation1-“. The result should look like this:
Locate Gatling simulation graphical report.
In IntelliJ IDEA you can right-click the index.html file and select Open in Browser. Otherwise you may have to navigate to the index.html file from your browser.
The first page, the Global tab, of the report looks like this (click on the picture to enlarge):
On this page there are seven or eight different sections:
- Indicators
Shows response time distribution and the number of failed and the number of succeeded requests. - Statistics
Statistics for all requests, global statistics, and statistics per request. - Errors
If there were errors during the simulation, there will be an Errors section describing the errors. - Active Users Along the Simulation
Graph showing the number of simulated users during the course of the simulation. In this report there will be just one single dot, since there is just one single simulated user sending two requests. - Response Time Distribution
Chart showing the different response times of the requests in the simulation. - Response Time Percentiles Over Time (OK)
Chart showing response time percentiles for successful requests over the course of the simulation. - Number of Requests Per Second
- Number of Responses Per Second
The second page, the Details tab, of the report looks like this (click on the picture to enlarge):
This page contains the following information per request of the simulation:
- Indicators
- Statistics
- Response Time Distribution
- Response Time Percentiles Over Time (OK)
- Latency Percentiles Over Time (OK)
Chart showing latency time percentiles for successful requests over the course of the simulation. - Number of Requests Per Second
- Number of Responses Per Second
- Response Time against Global RPS
Chart showing distribution of the response times of the specific request plotted on a chart that also shows the total (global) number of requests per second at the time where the response time was obtained. - Latency against Global RPS
Chart showing distribution of the latency times of the specific request plotted on a chart that also shows the total (global) number of requests per second at the time where the response time was obtained.
Not only does the report present the data of a load simulation in a very appealing manner, but the report is also interactive in a way – allowing you to focus on a smaller timeframe of the simulation in the charts, learn the exact value of a data-point by placing the mouse over it etc.
For further details on Gatling reports, please consult the reports section in the Gatling documentation.
This concludes the first part of the introduction to load testing with Gatling. The second part can be found here.
Happy coding!