Gatling glossary

Learn more about virtual users, scenarios, simulations, sessions, feeders, checks, assertions, reports

Domain-Specific Language (DSL)

Gatling provides a kind of language to define your load test, called a DSL.

The components of this DSL are mere definitions of the desired effect. They don’t generate the desired effect where you invoke them in your own code. Only when chained with other components so they are ultimately passed to the setUp, can the Gatling engine interpret them and produce the desired effect.

The example below doesn’t execute 5 HTTP requests. It creates 5 dangling HTTP requests definitions that don’t have any effect.

for (int i = 0; i < 5; i++) {
  http("Access Github").get("https://github.com");
}

for (let i = 0; i < 5; i++) {
  http("Access Github").get("https://github.com");
}

for (i in 1..5) {
  http("Access Github").get("https://github.com")
}

for (i <- 1 to 5) {
  http("Access Github").get("https://github.com")
}

Immutability

Most Gatling APIs such as DSL components and Session, are immutable. This means you can’t update existing instances but only generate new instances with the desired changes.

HttpRequestActionBuilder request1 = http("Access Github").get("https://github.com");
// request1 is left unchanged
HttpRequestActionBuilder request2 = request1.header("accept-encoding", "gzip");

const request1 = http("Access Github").get("https://github.com");
// request1 is left unchanged
const request2 = request1.header("accept-encoding", "gzip");

val request1 = http("Access Github").get("https://github.com")
// request1 is left unchanged
val request2 = request1.header("accept-encoding", "gzip")

val request1 = http("Access Github").get("https://github.com")
// request1 is left unchanged
val request2 = request1.header("accept-encoding", "gzip")

Virtual User

Some load testing tools, such as ab or wrk are very efficient at url bashing, but can’t deal with logic between requests.

Advanced load testing tools such as Gatling can deal with virtual users, each one having its own data and maybe taking a distinct browsing path.

Some other tools implement those virtual users as threads. Gatling implements them as messages, which scales much better and can deal easily with thousands of concurrent users.

Scenario

To represent users’ behaviors, testers will have to define scenarios which will be written as scripts given to Gatling.

These scenarios can be the result of measurements on the running application with analytic tools, or expected users’ behavior of a new application. In any case, the creation of these scenarios is the key to meaningful results of the load test.

A scenario represents a typical user behavior. It’s a workflow that virtual users will follow.

For example, a standard e-commerce application scenario could be:

Access home page
Select a browse category
Make a search in this category
Open a product description
Go back
Open another product description
Buy product
Log in
Checkout
Payment
Log out

Scenarios are represented as scripts in conjunction with a DSL (Domain Specific Language). This allows fast writing of scenarios and easy maintenance of existing scenarios.

Here is a simple example of a scenario:

scenario("Standard User")
  .exec(
    http("Access Github").get("https://github.com"),
    pause(2, 3),
    http("Search for 'gatling'").get("https://github.com/search?q=gatling"),
    pause(2)
  );

scenario("Standard User")
  .exec(
    http("Access Github").get("https://github.com"),
    pause(2, 3),
    http("Search for 'gatling'").get("https://github.com/search?q=gatling"),
    pause(2)
  );

scenario("Standard User")
  .exec(
    http("Access Github").get("https://github.com"),
    pause(2, 3),
    http("Search for 'gatling'").get("https://github.com/search?q=gatling"),
    pause(2)
  )

scenario("Standard User")
  .exec(
    http("Access Github").get("https://github.com"),
    pause(2, 3),
    http("Search for 'gatling'").get("https://github.com/search?q=gatling"),
    pause(2)
  )

As we can easily guess, this scenario:

is named “Standard User”
contains 2 HTTP Requests
contains 2 pauses

Pauses are used to simulate user think time. When a real user clicks on a link, the page has to be loaded in their browser and they will, most likely, read it and then decide what to do next.

HTTP requests are actually sent to the application under test when a user clicks on a button or a link. Each HTTP Request is easy to grasp (excluding page resources):

Access GitHub is a GET request pointing at https://github.com
Search for ‘gatling’ is a GET request pointing at https://github.com/search?q=gatling

For more information, check the Scenario reference section.

Injection Profile

An injection profile is the way Virtual Users are started. It’s typically either a rate of users started per second over time (open workload) or a current number of users over time (closed workload).

For more information, check the Injection reference section.

Load Generator

A load generator, in the context of load testing, is a component that simulates Virtual Users who generate traffic in a system or application. The purpose of load generators is to replicate the conditions of a real-world scenario by imposing a specific level of load on the target system. This allows performance testers to evaluate how the system reacts under various conditions, such as different numbers of concurrent users or varying transaction volumes.

Load generators generate virtual users by simulating their interactions with the system, sending requests and receiving responses. These responses are collected, stored, arranged, and pushed into load test reports. Load testing involves using multiple load generators to create a substantial and realistic load on the system.

Load generators are sometimes known as Injectors, Load agents, or Runners.

Simulation

A simulation is a description of the load test. It describes how, possibly several, user populations will run: which scenario they will execute and how new virtual users will be injected.

Here is an example of simulation definition:

ScenarioBuilder stdUser = scenario("Standard User"); // etc..
ScenarioBuilder admUser = scenario("Admin User"); // etc..
ScenarioBuilder advUser = scenario("Advanced User"); // etc..

setUp(
  stdUser.injectOpen(atOnceUsers(2000)),
  admUser.injectOpen(nothingFor(60), rampUsers(5).during(400)),
  advUser.injectOpen(rampUsers(500).during(200))
);

const stdUser = scenario("Standard User"); // etc..
const admUser = scenario("Admin User"); // etc..
const advUser = scenario("Advanced User"); // etc..

setUp(
  stdUser.injectOpen(atOnceUsers(2000)),
  admUser.injectOpen(nothingFor(60), rampUsers(5).during(400)),
  advUser.injectOpen(rampUsers(500).during(200))
);

val stdUser = scenario("Standard User") // etc..
val admUser = scenario("Admin User") // etc..
val advUser = scenario("Advanced User") // etc..

setUp(
  stdUser.injectOpen(atOnceUsers(2000)),
  admUser.injectOpen(nothingFor(60), rampUsers(5).during(400)),
  advUser.injectOpen(rampUsers(500).during(200))
)

val stdUser = scenario("Standard User") // etc..
val admUser = scenario("Admin User") // etc..
val advUser = scenario("Advanced User") // etc..

setUp(
  stdUser.inject(atOnceUsers(2000)),
  admUser.inject(nothingFor(60), rampUsers(5).during(400)),
  advUser.inject(rampUsers(500).during(200))
)

For more information, check the Simulation Setup reference section.

Session

Each virtual user is backed by a Session. Those Sessions are the actual messages that go down the scenario workflow. A Session is basically a state placeholder, where testers can inject or capture and store data.

For more information, check the Session reference section.

Feeders

When the tested application offers the possibility to authenticate, tests should take this into consideration and use data to test log in, log out, actions allowed only for certain users, and so on.

Gatling doesn’t provide tools to generate this test data.

Feeders are a convenient API for testers to inject data from an external source into the virtual users’ sessions.

For more information, check the Feeders reference section.

Checks

Each time a request is sent to the server, a response is normally sent, by the server, back to Gatling.

Gatling is able to analyze this response with Checks.

A check is a response processor that captures some part of it and verifies that it meets some given condition(s). For example, when sending an HTTP request, you could expect a HTTP redirect; with a check, you can verify that the status of the response is actually a 30x code.

Checks can also be used to capture some elements and store them into the Session so that they can be reused later, for example to build the next request.

For more information, check the Checks reference section.

Assertions

Assertions are used to define acceptance criteria on Gatling statistics (e.g. 99th percentile response time) that would make Gatling fail and return an error status code for the test as a whole.

For more information, check the Assertions reference section.

Reports

By default, reports are automatically generated at the end of a simulation. They consist of HTML files. Therefore, they are portable and can be viewed on any device with a web browser.

For more information, check the Reports reference section.

Durations

In Gatling, the default unit for duration parameters is seconds.

Edit this page on GitHub

Gatling glossary

Domain-Specific Language (DSL)#

Immutability#

Virtual User#

Scenario#

Injection Profile#

Load Generator#

Simulation#

Session#

Feeders#

Checks#

Assertions#

Reports#

Durations#