In this section we will use Gatling to load test a simple cloud hosted web server and will introduce you to the basic elements of the DSL.

Getting the bundle

You can get Gatling bundles as a .zip file here.


Just unzip the downloaded bundle to a folder of your choice.


Windows users : we recommend that you do not place Gatling in the Programs folder as there may be permission issues.

In order to run Gatling, you need to have a JDK installed. Gatling requires JDK8, yet we recommend that you use an up-to-date version.

For all details regarding the installation and the tuning of the operating system (OS), please refer to the Operations section.


Gatling launch scripts and Gatling maven plugin honor JAVA_HOME env var if it’s set. OS, like OSX, have their own tricky way of discovering which version of Java to run, so you might end up running a different version than the one java -version tells you. If you get strange errors such as Unsupported major.minor version 51.0 and you were expecting to run a JDK8, you might want to explicitly set JAVA_HOME.

A Word on Encoding

Gatling’s default encoding is UTF-8. If you want to use a different one, you have to:

  • select the proper encoding while using the Recorder

  • configure the proper encoding in the gatling.conf file.

    It will be used for compiling your simulations, building your requests and your responses.

  • make sure your text editor encoding is properly configured to match.

A Word on Scala

Gatling simulation scripts are written in Scala, but don’t panic! You can use all the basic functions of Gatling without knowing much about Scala. In most situations the DSL will cover most of your needs and you’ll be able to build your scenarios.

If you are interested in knowing more about Scala, then we recommend that you have a look at Twitter’s Scala School.


Feel also free to join our Google Group and ask for help once you’ve read this documentation.

Test Case

This page will guide you through most of Gatling HTTP features. You’ll learn about simulations, scenarios, feeders, recorder, loops, etc.

Application under Test

In this tutorial, we will use an application named Computer-Database deployed at the URL: http://computer-database.gatling.io.

This application is a simple CRUD application for managing computer models, and was a sample for the Play Framework before version 2.3.

You can also run it on your local machine: download Play! 2.2.x’s bundle and check out the app.


To test the performance of this application, we will create scenarios representative of what really happens when users navigate it.

Here is what we think a real user would do with the application:
  1. A user arrives at the application.
  2. The user searches for ‘macbook’.
  3. The user opens one of the related models.
  4. The user goes back to home page.
  5. The user iterates through pages.
  6. The user creates a new model.


Using the Recorder

To ease the creation of the scenario, we will use the Recorder, a tool provided with Gatling that allows you to record your actions on a web application and export them as a Gatling scenario.

This tool is launched with a script located in the bin directory:

  • On Linux/Unix:

  • On Windows:


Once launched, the following GUI lets you configure how requests and responses will be recorded.

Set it up with the following options:
  • computerdatabase package
  • BasicSimulation name
  • Follow Redirects? checked
  • Automatic Referers? checked
  • Black list first filter strategy selected
  • .*\.css, .*\.js and .*\.ico in the black list filters

After configuring the recorder, all you have to do is to start it and configure your browser to use Gatling Recorder’s proxy.


For more information regarding Recorder and browser configuration, please check out Recorder reference page.

Recording the scenario

Now simply browse the application:
  1. Enter ‘Search’ tag.
  2. Go to the website: http://computer-database.gatling.io
  3. Search for models with ‘macbook’ in their name.
  4. Select ‘Macbook pro’.
  5. Enter ‘Browse’ tag.
  6. Go back to home page.
  7. Iterates several times through the model pages by clicking on Next button.
  8. Enter ‘Edit’ tag.
  9. Click on Add new computer.
  10. Fill the form.
  11. Click on Create this computer.

Try to act as a real user would, don’t immediately jump from one page to another without taking the time to read. This will make your scenario closer to real users’ behavior.

When you have finished playing the scenario, click on Stop in the Recorder interface.

The Simulation will be generated in the folder user-files/simulations/computerdatabase of your Gatling installation under the name BasicSimulation.scala.

Gatling scenario explained

Here is the produced output:

package computerdatabase // 1

import io.gatling.core.Predef._ // 2
import io.gatling.http.Predef._
import scala.concurrent.duration._

class BasicSimulation extends Simulation { // 3

  val httpConf = http // 4
    .baseURL("http://computer-database.gatling.io") // 5
    .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8") // 6
    .acceptEncodingHeader("gzip, deflate")
    .userAgentHeader("Mozilla/5.0 (Windows NT 5.1; rv:31.0) Gecko/20100101 Firefox/31.0")

  val scn = scenario("BasicSimulation") // 7
    .exec(http("request_1")  // 8
    .get("/")) // 9
    .pause(5) // 10

  setUp( // 11
    scn.inject(atOnceUsers(1)) // 12
  ).protocols(httpConf) // 13

What does it mean?

  1. The optional package.
  2. The required imports.
  3. The class declaration. Note that it extends Simulation.
  4. The common configuration to all HTTP requests.


val is the keyword for defining a constant value. Types are not defined and are inferred by the Scala compiler.

  1. The baseURL that will be prepended to all relative urls.
  2. Common HTTP headers that will be sent with all the requests.
  3. The scenario definition.
  4. A HTTP request, named request_1. This name will be displayed in the final reports.
  5. The url this request targets with the GET method.
  6. Some pause/think time.


Duration units default to seconds, e.g. pause(5) is equivalent to pause(5 seconds).

  1. Where one sets up the scenarios that will be launched in this Simulation.
  2. Declaring to inject into scenario named scn one single user.
  3. Attaching the HTTP configuration declared above.


For more details regarding Simulation structure, please check out Simulation reference page.

Running Gatling

Launch the second script located in the bin directory:

  • On Linux/Unix:

  • On Windows:


You should see a menu with the simulation examples:

Choose a simulation number:
   [0] computerdatabase.BasicSimulation

When the simulation is done, the console will display a link to the HTML reports.


If Gatling doesn’t work as expected, see our FAQ or ask on our Google Group.

Going Further

When you’re ready to go further, please check out the Advanced Tutorial.