Scenario Components

Reference of the different components available to write scenarios with Gatling.

scenario #

This method is the first one of a scenario. It declares a new scenario with a name as parameter.

scenario("My Scenario")

You can use any character in the name of the scenario except tabulations: \t.

Note that the method chain used in loops and conditional statements can be seen as an anonymous scenario

insertChain #

This method allows you to define a chain in the script and use it at different places in the scenario:

val myChain = chain.exec( http("...") ... ).pause(4).exec( http("...") ...) ...

scenario("My Scenario")
    .insertChain(myChain)
    .exec( http("...") ... )
    .insertChain(myChain)

As the previous example shows, the same chain can be inserted at several places in the scenario. You can use this chain directly in methods expecting chains as parameters.

Note: If you want to repeat the use of a chain, prefer using a loop

exec #

This method is used to execute an action. Actions are usually requests (HTTP, LDAP, POP, IMAP, etc) that will be sent during the simulation. For example, using Gatling HTTP one would write the following line:

scenario("My Scenario")
    .exec( http("Get Homepage").get("http://github.com/excilys/gatling") )

Any action that will be executed will be called with exec.

Session manipulation

Apart from actions, exec can take a function (Session => Session) as argument. Using this function, you can set a value in the session between two actions, eg: exec( (s: Session) => s.setAttribute("myKey", "myValue") )

Be advised that Sessions are immutable in Gatling. That's why the signature of the function is Session => Session. Don't forget to return the session if needed.

pause #

When a user sees a page he/she often reads what is shown and then chooses to click on another link. To reproduce this behavior, the pause method is used. There are several ways of using it:

With fixed duration

pause(4)           // will pause for 4 seconds
pause(4, SECONDS)  // if you want to specify the unit

With random duration

pause(4, 5)          // will pause between 4 and 5 seconds
pause(4, 5, SECONDS) // you can also specify the unit if you need to

Available units are: NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS

doIf #

Gatling's DSL has conditional execution support. If you want to execute a specific chain of actions only when some condition is satisfied, you can do so using the doIf method. It will check if a value in the session equals the one you specified:

doIf("${myKey}", "myValue",
    chain.exec( http("...") ... ) // executed if the session value stored in "myKey" equals "myValue"
)

doIf("${myKey}", "myValue",
    chain.exec( http("if true") ... ), // executed if the session value stored in "myKey" is equal to "myValue"
    chain.exec( http("if false") ... ) // executed if the session value stored in "myKey" is not equal to "myValue"
)

As you can see, the executed actions if the condition is false are optional.

If you want to test other conditions than equality, you'll have to use a scala function to write it:

doIf( (s: Session) => s.getTypedAttribute[String]("myKey").startsWith("admin"),
    chain.exec( http("if true") ... ) // executed if the session value stored in "myKey" starts with "admin"
)
   
doIf( (s: Session) => s.getTypedAttribute[String]("myKey").startsWith("admin"),
    chain.exec( http("if true") ... ), // executed if the session value stored in "myKey" starts with "admin",
    chain.exec( http("if false") ... ) // executed if the session value stored in "myKey" does not start with "admin"
)

Scala functions may seem complex, but they are really useful. Their usage is covered in Advanced usage of Gatling.

loop #

Often, you'll want to have your simulated users repeat several tasks. To help you with these iterative actions, Gatling provides 3 loop structures based on: a fixed number of iterations, a duration or a stop condition.

usage

Usage of loops is almost the same for each type. It starts with the method loop:

loop(
    chain.exec( http("...") ... )
)

This keyword indicated that the chain in the loop will eventually be executed several times. To specify the type of loop, you can add:

.times(20)                       // this will execute the chain 20 times
OR
.during(20)                      // will execute the chain until 20 seconds passed at least
.during(20, SECONDS)             // you can specify the time unit if you want
OR
.asLongAs("${myKey}", "myValue") // will execute the chain while the session value in "myKey" equals "myValue"

Regarding the during method, keep in mind that the duration time is checked each time the chain has been executed. Therefore, it could last more than the time you specified.

Finally, the asLongAs method takes a condition and executes the chain as long as the condition is true. Thus, the chain can also not be executed at all if the condition is false when the scenario reaches the loop.

loop counter

If you're a developer, you are familiar with loops and recognized that times is a for loop and the others are while loops. As in any programming language, these loops have internal counters that you can use in your actions. Here's how you can use them:

loop(
    chain.exec( (s: Session) => println( getCounter(s, "myLoop") ) ) // This function prints the value of the counter on the console
).counterName("myLoop").times(10)

First you have to specify the name of the counter, here it is named "myLoop". Then, when writing the actions that will be executed, you can access the counter value thanks to the getCounter method. This example would print the value from 0 to 9 in the console.

Don't forget that the counter starts at 0!