Package Generation

Generate a package from your Gatling bundle or with a Maven, SBT, or Gradle project.

Generating Packages for Gatling Enterprise

Gatling Enterprise deploys packages containing your compiled Simulations and resources. Those packages have to be generated upstream, using one of the methods below, before you can run them with Gatling Enterprise.

Gatling Enterprise is compatible with Gatling 3.3, 3.4, 3.5 and 3.6.

Gatling zip bundle

Once you have created a simulation you want to upload, run the script artifact.sh (on Linux or macOS) or artifact.bat (on Windows), found in the bin directory of your unzipped Gatling bundle. This will generate a target/artifact.jar file. You can then upload this file in the Packages section.

Maven Project

In your pom.xml file, you must add:

  • the Gatling dependencies
  • the Scala Maven plugin (scala-maven-plugin), which compiles your code
  • the Gatling Enterprise Maven plugin (frontline-maven-plugin), which packages your code

The pom.xml file should contain this:

<dependencies>
  <dependency>
    <groupId>io.gatling.highcharts</groupId>
    <artifactId>gatling-charts-highcharts</artifactId>
    <version>3.6.1</version>
    <scope>test</scope>
  </dependency>
</dependencies>

<build>
  <!-- so maven compiles src/test/scala and not only src/test/java -->
  <testSourceDirectory>src/test/scala</testSourceDirectory>
  <plugins>
    <plugin>
      <artifactId>maven-jar-plugin</artifactId>
      <version>3.2.0</version>
    </plugin>
    <!-- so maven can compile your scala code -->
    <plugin>
      <groupId>net.alchim31.maven</groupId>
      <artifactId>scala-maven-plugin</artifactId>
      <version>4.4.1</version>
      <executions>
        <execution>
          <goals>
            <goal>testCompile</goal>
          </goals>
          <configuration>
            <recompileMode>all</recompileMode>
            <jvmArgs>
              <jvmArg>-Xss100M</jvmArg>
            </jvmArgs>
            <args>
              <arg>-target:jvm-1.8</arg>
              <arg>-deprecation</arg>
              <arg>-feature</arg>
              <arg>-unchecked</arg>
              <arg>-language:implicitConversions</arg>
              <arg>-language:postfixOps</arg>
            </args>
          </configuration>
        </execution>
      </executions>
    </plugin>

    <!-- so maven can build a package for FrontLine -->
    <plugin>
      <groupId>io.gatling.frontline</groupId>
      <artifactId>frontline-maven-plugin</artifactId>
      <version>1.2.3</version>
      <executions>
        <execution>
          <goals>
            <goal>package</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Run the mvn clean package -DskipTests command. This will generate the target/<artifactId>-<version>-shaded.jar file. You can then upload this file in the Packages section.

SBT Project

In your SBT project configuration, you must add:

  • the Gatling dependencies
  • the Gatling Enterprise SBT plugin ("io.gatling.frontline" % "sbt-frontline"), which packages your code

The build.sbt file should contain this:

enablePlugins(GatlingPlugin, FrontLinePlugin)

// If you want to package simulations from the 'it' scope instead. You will need the gatling-sbt plugin, see further below.
// inConfig(IntegrationTest)(_root_.io.gatling.frontline.sbt.FrontLinePlugin.frontlineSettings(IntegrationTest))

scalaVersion := "2.13.6"
scalacOptions := Seq(
  "-encoding", "UTF-8", "-target:jvm-1.8", "-deprecation",
  "-feature", "-unchecked", "-language:implicitConversions", "-language:postfixOps")

val gatlingVersion = "3.6.1"

libraryDependencies += "io.gatling.highcharts" % "gatling-charts-highcharts" % gatlingVersion % "test"
// only required if you intend to use the gatling-sbt plugin:
libraryDependencies += "io.gatling"            % "gatling-test-framework"    % gatlingVersion % "test"

You will also need the following lines in the project/plugins.sbt file:

// only if you intend to use the gatling-sbt plugin for running Gatling locally:
addSbtPlugin("io.gatling" % "gatling-sbt" % "3.2.2")
// so that sbt can build a package for Gatling Enterprise:
addSbtPlugin("io.gatling.frontline" % "sbt-frontline" % "1.3.4")

To package your code, please run one of the following commands in your terminal.

In general (typically, your Gatling simulations are written inside the src/test/scala directory):

sbt test:assembly

If you are using the integration test (it) configuration provided by the gatling-sbt plugin (typically, your Gatling simulations are written inside the src/it/scala directory):

sbt it:assembly

Either command will generate the target/<artifactId>-<version>.jar file, which you can then upload in the Artifacts section.

Gradle Project

In your build.gradle file, you must add:

  • the Gatling dependencies
  • the Gatling Enterprise Gradle plugin (io.gatling.frontline.gradle), which packages your code

The build.gradle file should contain this:

plugins {
  // The following line allows to load io.gatling.gradle plugin and directly apply it
  id 'io.gatling.frontline.gradle' version '1.4.3'
}

// This is needed to let io.gatling.gradle plugin to loads gatling as a dependency
repositories {
  jcenter()
  mavenCentral()
}

gatling {
  toolVersion = '3.6.1'
}

Run the gradle frontLineJar command. It will generate the build/libs/artifactId.jar file. You can then upload this file in the Packages section.

Multi-Module Support

If you have a multi-module project, make sure to only configure the modules which contain Gatling Simulations with the Gatling related plugins described above. Your Gatling modules can, however, depend on other modules.

Note on Feeders

A typical mistake with Gatling and Gatling Enterprise is to rely on having an exploded Maven/Gradle/SBT project structure, and to try to load files from the project filesystem.

This filesystem structure will not be accessible once your project has been packaged and deployed to Gatling Enterprise.

If your feeder files are packaged with your test sources, you must resolve them from the classpath. This will work both when you run simulations locally and when you deploy them to Gatling Enterprise.

// incorrect
val feeder = csv("src/test/resources/foo.csv")

// correct
val feeder = csv("foo.csv")

Load Sharding

Injection rates and throttling rates are automatically distributed amongst nodes.

However, Feeders data is not automatically sharded, as it might not be the desired behavior.

If you want data to be unique cluster-wide, you have to explicitly tell Gatling to shard the data, e.g.:

val feeder = csv("foo.csv").shard

Assuming the CSV file contains 1000 entries, and you run your simulation on 3 Gatling nodes, the entries will be distributed as follows:

  • First node will access the first 333 entries
  • Second node will access the next 333 entries
  • Third node will access the last 334 entries

Resolving Injector Location in Simulation

When running a distributed test from multiple locations, you could be interested in knowing where a given injector is deployed in order to trigger specific behaviors depending on the location.

For example, you might want to hit https://example.fr if the injector is deployed in the Europe - Paris AWS region, and https://example.com otherwise.

In your simulation code, you can resolve the name of the pool in which the injector running the code is deployed:

val poolName = System.getProperty("gatling.frontline.poolName")
val baseUrl = if (poolName == "Europe - Paris") "https://example.fr" else "https://example.com"

Edit this page on GitHub

← Profile
Package Configuration →