Introduction to Load Testing with Gatling – Part 1

By | April 16, 2016
gatling-logo

Gatling logo, used with permission.

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:

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:

Load Simulation Text Report

Having run the load simulation, there should be output similar to this in the terminal as the simulation is executed:

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.

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):

Gatling HttpSimulation1 graphical report, page 1.

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):

Gatling HttpSimulation1 graphical report, page 2.

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!

Leave a Reply

Your email address will not be published. Required fields are marked *