Gatling tests

This topic describes how to use Gatling load testing scripts in Controller scenarios.

Gatling tests overview

Gatling is an open source load and performance testing tool that uses the Scala programming language to create test scripts. Gatling is used for analyzing and measuring the performance of web servers and web applications.

LoadRunner Professional scenarios support Gatling scripts with the .scala and .jar extensions. You can run one or more Gatling scripts together with other LoadRunner Professional protocol scripts in a scenario.

Gatling scripts have two significant features:

  • Every Gatling script file contains all the necessary run settings within the script code.
  • Gatling scripts contain a series of HTTP requests and pauses. Each request and request group is reported as a transaction.

LoadRunner Professional allows you to manipulate the number of running Vusers and the ramp-up configuration via the Controller, ignoring their configuration in the Gatling scripts. You configure Gatling Vusers the same way as you would configure Vusers of other protocol types.

Measurements can be viewed online and offline (via Controller and Analysis), using the data points from the Gatling tests.

Back to top

Prerequisite setup for Gatling tests

Note the following before creating a scenario with a Gatling script:

  • Gatling scripts can be run on a load generator on a Windows or Linux operating system. The Docker installations of Windows and Linux also support Gatling scripts.
  • LoadRunner Professional installation includes an embedded version of Gatling. No other installation or configuration is necessary. (For supported versions, see Support Matrix.)

  • You must have 32-bit or 64-bit JDK 8, 11, or 17 installed on the load generator machine.
  • For Linux load generators, make sure that unzip is installed on the machine in order to execute Gatling .jar files.

Tip: We recommend that you use dedicated load generator machines for running Gatling test scripts. If you run tests on the Controller's localhost load generator, they may become unstable.

Data files

Gatling scripts can reference data files, such as those that contain parameter values. These files can be in several formats, such as .csv, .ssv, .tsv, .json, and .xml.

If the Gatling script references a data file, make sure that:

  • it is in the same folder as the .scala or .jar file, (and not a subfolder).
  • the Gatling script correctly references the file.

The Controller will find these files, and send them to the load generator for execution.

Back to top

Gatling scripts in Controller scenarios

A Gatling script is triggered as a separate process on the load generator machine.

Note: Network Virtualization is not supported for Gatling tests.

To define a Gatling scenario:

  1. Make sure the load generator machines are set up to run Gatling tests, as described above.
  2. On the main Controller toolbar, click the New Scenario button .
  3. In the New Scenario dialog box, click Add Scripts. From the Script Type dropdown, select Gatling Scripts.
  4. Click Browse and select the Gatling script (.scala file) or Gatling archive (.jar file).
  5. Click OK in the New Scenario dialog box. The scenario containing the Gatling script opens in the Design tab.
  6. Set the number of Vusers to run in the script.
  7. Configure runtime settings for the script, as required:

    • Specify a custom JRE path.

    • Customize the behavior of the JVM.

    • Specify a simulation class, if you are using a .jar script or if the scenario contains multiple simulations.

    • Set the iteration pacing.

    Open the Runtime Settings UI and configure the relevant settings:

    1. In the Gatling settings section, specify the details such as the custom JRE path or a string in the Additional parameters section. For example, -Xms512m.

    2. If you are using a script with a .jar extension, or if the scenario contains multiple simulations, you must specify a simulation class.

      In the Class name field, specify the full name of the class to execute. If you leave this blank, the script run will fail. If there are multiple Gatling scenarios in a simulation, the Controller runs the first scenario.

    3. In the Pacing section, specify the pacing details. For details, see the documentation on iterations and run logic in the Virtual User Generator Help Center (select the relevant version).

  8. Specify the schedule as you would for any other LoadRunner protocol. For details, see Define a schedule for the scenario. Any schedule-related definitions in the Gatling script's simulation setup, such as inject and maxDuration, are ignored.

  9. In the Run tab, click the Start Scenario button to begin running the scenario.
  10. To add Vusers during the scenario run, click Run/Stop Vusers and modify the number.

Back to top

Sample Gatling script

The following example illustrates a scenario with two requests that generate two transactions:

Note: All schedule-related definitions in the script's simulation setup, such as inject and maxDuration, are ignored. Instead, use the Controller scheduling as described in Define a schedule for the scenario.

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

class LRDemoSimulation extends Simulation {

  val httpProtocol = http
    .baseURL("") // Here is the root for all relative URLs
    .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8") // Here are the common headers
    .acceptEncodingHeader("gzip, deflate")
    .userAgentHeader("Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:16.0) Gecko/20100101 Firefox/16.0")

  val scn = scenario("Scenario Name") // A scenario is a chain of requests and pauses
  setUp(scn.inject(rampUsers(5) over (30 seconds)).protocols(httpProtocol)).maxDuration(2 minutes)

Back to top

View Gatling test results

In your Gatling script, you can group a series of HTTP requests to be marked as a single transaction, and you can define the transaction name. If you do not group the requests, then each HTTP request is reported as a transaction.

Gatling scripts produce results that are displayed in the following standard Controller graphs:

Graph For details, see...
Running Vusers Runtime graphs overview
Transaction Response Time Transaction monitor graphs overview
Total Transaction per second (Passed)
Transactions per second (Passed)
HTTP Responses per second Web Resource monitoring
Hits per Second
Throughput - Whole Load Test

Back to top

Known issues for Gatling tests

The following are known issues for Gatling tests:

  • SLA transaction names are not listed.
  • Gatling 3 syntax is not supported—only version 2.17 scripts are supported. To adapt scripts created in other versions, you may need to adjust several parameters such as keywords. For more information, see the Gatling documentation Migration Guides.
  • When running scripts with a .scala extension, the compilation time (approximately 20-30 seconds) is included in the run duration. As a result, the actual time that Vusers run is shorter than the specified duration.
  • If you run a Gatling script for a specific duration, the scenario may stop before the last iteration is finished.

  • Gatling may not be binary-compatible with previous versions of Gatling. Gatling .jar scripts compiled with a previous version need to be recompiled.

Back to top

See also: