Gatling Installation and Configuration – The Ultimate Tutorial

Gatling Installation

As Gatling is written in Scala, it can be run on any OS (operating system) and the only requirement is to have the Java installed on the machine. Moreover, in order to use Gatling and run the load tests, you need to have the JDK (Java Development Kit) installed. The latest version of Gatling requires JDK 1.8 at least so you need to be sure you don’t use the older version. You can check your current JDK version by executing this command in your terminal (command line):

> java -version

If JDK is installed on your system, you should see a similar output to this one:

If you see a similar output and the JDK version is at least 1.8 then you can skip the Java installation steps. Otherwise, check this link to download the latest JDK version based on your local system. As soon as the JDK installation file is downloaded, you can just run it and proceed with a very straightforward installation process where you basically only need to accept a couple of agreements. it is always recommended to set the JAVA_HOME system variable. This variable should point to the correct version of Java, because this is the main way Gatling uses to locate Java on your machine when launching. These official instructionsmight be useful and will tell you how to set the JAVA_HOME variable based on your OS.

After all Java magic is complete, you can proceed with the Gatling distribution downloading from the official source, where you can always find the latest version (2.3.0 on the date of writing the article). As soon the distribution has been downloaded, unzip it to any preferred location. However, you need to keep in mind that it is better to unzip the distribution into your user’s home location or in some other folder you have full user permission to.

As the next step you just need to unzip the downloaded distribution into the preferable location using any application that can open zip archives. If you don’t have a desktop application for this, you can use the terminal and unzip the Gatling distribution using these commands:

> tar xvf (UNIX)

> unzip (Windows)

In the screenshot below you can find a short explanation for the Gatling framework folders:

gatling installation instructions

Gatling is code based performance testing framework and it doesn’t have a GUI desktop application to run the tests. That’s why, to verify that Gatling can be run successfully on your local machine, you need to execute a Gatling performance test scenario using a Gatling tests runner. Fortunately, Gatling has a few scripts that you can use right after installation just for that, instead of creating your own.

To execute one of these test scripts, you need to run the Gatling tests runner, which is located in the Gatling ‘bin’ folder. The Gatling distribution has default simulation scripts that can be run to check if everything has been installed correctly and that Gatling works as expected. In the terminal, go to the downloaded Gatling distribution and after that execute the runner scripts according to your local system environment:

./ (UNIX)
./gatling.bat (Windows)

If you see a similar execution flow on your machine, everything is working fine and you are ready to write your tests. After the end of the test you should see a link that you can open to verify that the Gatling metrics reports are being built successfully:

In addition to that, you can verify that Gatling is working properly by running the Gatling recorder, which is located in the same folder as the tests runner, and can be run using this command:

./ (UNIX)
./recorder.bat (Windows)

Gatling Configuration

You can configure the Gatling tests runner in three different ways:

  • Using configuration files, located in the conf directory of the Gatling home directory
  • Via the command line options
  • Via the $JAVA_OPTS environment variable

It is worth mentioning that Gatling has very well documented configuration files. Usually, if you try to open internal configuration files belonging to performance tools, it takes a long time to get the meaning of each. Gatling is an exception. If you try to open the main configuration file located under ‘.conf/gatling.conf’, you will see such a property file:

start out with gatling

Just keep in mind that almost all the necessary Gatling configurations can be found inside the ‘.conf/gatling.conf’ configuration file, so you can edit them yourself by using your favorite text editor.

Command line options do not have such a wide choice of parameters for configuration, but they provide the most important configuration parts for changing the configuration during tests execution without having to spend time on editing the separate configuration file.

Categories: Gatling

Leave a Reply