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 ( Gatling is used for analyzing and measuring the performance of web servers and web applications. Gatling uses the Scala programming language to create test scripts.

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 guidelines 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.
  • The LoadRunner Professional installation, through version 2021, includes an embedded version of Gatling. No other installation or configuration is necessary.
  • From version 2021 R1, Gatling is no longer automatically installed with LoadRunner Professional. You must instead manually install the Gatling version included with LoadRunner Professional.

    To install, copy the Gatling files to %LG_PATH%\bin on the load generator machine. File locations:

    • LoadRunner Professional and VuGen: The files are located in the DVD\lrunner\Common\gatling folder.

    • OneLG load generators: The files are located in the prerequisites\gatling subfolder of the extracted installation package (by default C:\Temp\Micro Focus LoadRunner OneLG <version>\prerequisites\gatling).

  • Make sure you have 32-bit or 64-bit JDK 8 installed on the load generator machine (JDK 11 is not supported).
  • 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 if you need to:

    • 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 (supported from version 2021 R1).

    To open the runtime settings, right-click the script name, and select Runtime Settings or click the Runtime Settings toolbar button .

    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 Iterations and run logic.

  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, and so forth, 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:

  • Running Vusers
  • Transaction Response Time
  • Total Transaction per second (Passed)
  • Transactions per second (Passed)
  • HTTP Responses per second
  • Hits per Second
  • Throughput - Whole Load Test

For graph details, see the Online monitor graphs reference.

Back to top

Known issues for Gatling scripts

The following are known issues for Gatling scripts:

  • 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 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 will be 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.

Back to top

See also: