Simulation structure

A Simulation is a real Scala class containing 4 different parts:

  • The HTTP protocol configuration
  • The headers definition
  • The scenario definition
  • The simulation definition

To illustrate this point we will take one of our sample simulations: computerdatabase.BasicSimulation


We recommend your Simulation’s name doesn’t start with Test.

Some tools such as maven surefire aggressively consider classes with such naming pattern are for them to handle and will try to launch them.

DSL imports

The Gatling DSL requires some imports:

import io.gatling.core.Predef._     // required for Gatling core structure DSL
import io.gatling.jdbc.Predef._     // can be omitted if you don't use jdbcFeeder
import io.gatling.http.Predef._     // required for Gatling HTTP DSL

import scala.concurrent.duration._  // used for specifying duration unit, eg "5 second"


Do not try to “optimize imports” with your IDE, you’d break everything.

Just copy paste those imports wherever you want to use Gatling DSL.


Beware that the sole API in Gatling (hence stable documented components) is the DSL.

If you chose to use Gatling internal types, beware those might change any time.

HTTP protocol configuration

The first element is the configuration of the HTTP protocol. In this example, this configuration is very basic and just defines:

  • the baseUrl, which will be prepended to all the relative paths in the scenario definition. Here, the base URL is
  • common headers, which will be added on each request.

The HTTP Configuration is stored as a Scala value so that we can set it later in the simulation definition.

Headers definition

As you’ll see later, when we define the scenario for Gatling, we can provide the headers used for each request sent to the server. As the file was generated by the recorder, all headers are declared in the beginning of the file and used in the scenario definition.


Adding common headers can seem useless, but don’t forget that they add load on your server and have a real impact on the server behavior (like Accept-Encoding or If-Last-Modified).

Headers are declared as Scala Maps:

val someExtraHeaders = Map("Origin" -> "")


Scenario definition

After the headers definition comes the scenario definition. This definition has a name because you can define several scenarios in the same simulation. A scenario is usually stored in a Scala value:

val scn = scenario("ScenarioName") // etc...

The scenario structure basically consists of chaining two methods: exec and pause. The first one is used to describe an action, usually a request sent to the tested application; the second one is used to simulate the think time of the user between consecutive requests.

HTTP requests are defined as follows in a scenario:

// Here's an example of a POST request
  .formParam("name", "Beautiful Computer")
  .formParam("introduced", "2012-05-30")
  .formParam("discontinued", "")
  .formParam("company", "37")

The above example produces a POST HTTP request that creates a new computer model:

HTTP request:
  Accept: [text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8]
  Content-Type: [application/x-www-form-urlencoded]
  DNT: [1]
  Accept-Language: [en-US,en;q=0.5]
  Accept-Encoding: [gzip, deflate]
  User-Agent: [Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:16.0) Gecko/20100101 Firefox/16.0]
  Referer: []
  company: [37]
  discontinued: []
  name: [Beautiful Computer]
  introduced: [2012-05-30]

Simulation definitions

The last part of the file contains the simulation definition, this is where you define the load you want to inject to your server, e.g.:

  scn.inject(atOnceUsers(1)) // (1)
    .protocols(httpProtocol) // (2)

which correspond to:

  1. We inject one single user into the scn scenario
  2. We configure httpProtocol on the setUp so that we pass the base URL and the common headers.


Gatling provides two hooks:

  • before for executing some arbitrary code before the simulation actually runs
  • after for executing some arbitrary code after the simulation actually runs

The lifecycle is as below:

  1. Gatling starts
  2. Simulation constructor is called and all the code in the class body not delayed in before and after hooks is executed
  3. before hook is executed
  4. Simulation runs
  5. Simulation terminates
  6. after hook is executed
  7. HTML reports are generated if enabled
  8. Gatling shuts down
before {
  println("Simulation is about to start!")

after {
  println("Simulation is finished!")


You won’t be able to use Gatling DSL in there, as it’s only intended for load test. You can only use your own code. If you’re looking for executing Gatling DSL, you might consider using sequential scenarios.