SBT Plugin
The SBT plugin allows you to run Gatling tests from the command line, without the bundle, as well as to package your simulations for Gatling Enterprise
This SBT plugin integrates Gatling with SBT, allowing to use Gatling as a testing framework. It can also be used to package your Gatling project to run it on Gatling Enterprise.
Versions
Check out available versions on Maven Central.
Beware that milestones (M versions) are not documented for OSS users and are only released for Gatling Enterprise customers.
Setup
Cloning or downloading our demo project on GitHub is definitely the fastest way to get started:
If you prefer to manually configure your SBT project rather than clone our sample, you need to add the Gatling plugin dependency to your project/plugins.sbt
:
addSbtPlugin("io.gatling" % "gatling-sbt" % "MANUALLY_REPLACE_WITH_LATEST_VERSION")
And then add the Gatling library dependencies and enable the Gatling plugin in your build.sbt
:
enablePlugins(GatlingPlugin)
libraryDependencies += "io.gatling.highcharts" % "gatling-charts-highcharts" % "MANUALLY_REPLACE_WITH_LATEST_VERSION" % "test"
libraryDependencies += "io.gatling" % "gatling-test-framework" % "MANUALLY_REPLACE_WITH_LATEST_VERSION" % "test"
‘Test’ vs ‘Integration Tests’ configurations
This plugin offers two different custom SBT configurations, named Gatling
and GatlingIt
.
They are tied to different source directories (see next section for more details) and therefore allow to separate your simulations according to your needs, should you desire it.
Ideally:
- Your simulations with low injection profiles, which may serve as functional tests, should live in
src/test
(the default source directory for theGatling
configuration), and run along your unit tests, since they would complete quickly - Longer, more complex simulations with high injection profiles, should live in
src/it
(the default source directory for theGatlingIt
configuration) and be run on an as-needed basis.
Also, since they’re tied to separate SBT configurations, your SBT settings can then be customized per configuration. You can expect a relatively short simulation to run easily with the default JVM settings, but, for example, simulations with much higher load could require an increase of the max heap memory.
GatlingIt
configuration, you must use the GatlingIt/
prefix, e.g. Gatling/test
becomes GatlingIt/test
, etc…Default settings
For the Gatling
configuration :
- By default, Gatling simulations must be in
src/test/scala
, configurable using theGatling / scalaSource
setting. - By default, Gatling reports are written to
target/gatling
, configurable using theGatling / target
setting.
For the GatlingIt
configuration :
- By default, Gatling simulations must be in
src/it/scala
, configurable using theGatlingIt / scalaSource
setting. - By default, Gatling reports are written to
target/gatling-it
, configurable using theGatlingIt / target
setting.
If you override the default settings, you need to reset them on the project, eg:
Gatling / scalaSource := sourceDirectory.value / "gatling" / "scala"
lazy val root = (project in file(".")).settings(inConfig(Gatling)(Defaults.testSettings): _*)
Multi-project support
If you have a multi-project build, make sure to only configure the subprojects which contain Gatling Simulations with the Gatling plugin and dependencies as described above. Your Gatling subproject can, however, depend on other subprojects.
Usage
Running your simulations
As with any SBT testing framework, you’ll be able to run Gatling simulations using SBT standard test
, testOnly
,
testQuick
, etc… tasks. However, since the SBT Plugin introduces many customizations that we don’t want to interfere
with unit tests, those commands are integrated into custom configurations, meaning you’ll need to prefix them with
Gatling/
or GatlingIt/
.
For example, run all Gatling simulations from the test
configuration:
sbt Gatling/test
Or run a single simulation, by its FQN (fully qualified class name), from the it
configuration:
sbt 'GatlingIt/testOnly com.project.simu.MySimulation'
test
without prefixing started Gatling simulations.
However, this caused many interferences with other testing libraries and forcing the use of a prefix solves those issues.Working with Gatling Enterprise Cloud
it
configuration, simply replace Gatling/
with GatlingIt/
in the
configuration and commands.API tokens
You need to configure an an API token for most of the tasks regarding Gatling Enterprise Cloud. The API token needs the Configure
role.
Since you probably don’t want to include you secret token in your source code, you can configure it using either:
- the
GATLING_ENTERPRISE_API_TOKEN
environment variable - the
gatling.enterprise.apiToken
Java System property
If really needed, you can also configure it in your build.sbt:
Gatling / enterpriseApiToken := "YOUR_API_TOKEN"
Create or start a simulation
You can, using the Gatling/enterpriseStart
task:
- configure a new simulation on Gatling Enterprise Cloud, upload your packaged code, and immediately start the simulation
- or, for a simulation already configured on Gatling Enterprise Cloud, upload any updated code and immediately start the simulation
Configure
role.Quick usage:
- configure and start a new simulation with
sbt Gatling/enterpriseStart
, you will be prompted to choose all required options. This will also print the simulationId of the newly configured simulation. - run the simulation again with
sbt Gatling/enterpriseStart -Dgatling.enterprise.simulationId=<YOUR_SIMULATION_ID>
. - run the simulation and wait for the end of the run (will regularly print out progress information, and exit with an error code if the simulation fails) with
sbt Gatling/enterpriseStart -Dgatling.enterprise.simulationId=<YOUR_SIMULATION_ID> -Dgatling.enterprise.waitForRunEnd=true
.
List of configurations used by this task:
// You can also use the gatling.enterprise.simulationId system property
Gatling / enterpriseSimulationId := "YOUR_SIMULATION_ID"
// You can also use the gatling.enterprise.packageId system property
Gatling / enterprisePackageId := "YOUR_PACKAGE_ID"
// You can also use the gatling.enterprise.teamId system property
Gatling / enterpriseTeamId := "YOUR_TEAM_ID"
// default simulation fully qualified classname used when creating a new simulation, you can also use the gatling.enterprise.simulationClass system property
Gatling / enterpriseSimulationClass := "computerdatabase.BasicSimulation"
// custom system properties used when running the simulation on Gatling Enterprise
Gatling / enterpriseSimulationSystemProperties := Map.empty
// Additional environment variables used when running the simulation on Gatling Enterprise
Gatling / enterpriseSimulationEnvironmentVariables := Map.empty
// Wait for the result after starting the simulation on Gatling Enterprise; will complete with an error if the simulation ends with any error status
// False by default; you can also use the gatling.enterprise.waitForRunEnd system property
Gatling / waitForRunEnd := false
You can run it with the command:
sbt Gatling/enterpriseStart
If a simulationId
is set, the task will start the simulation on Gatling Enterprise.
If no simulationId is set, the task will ask you if you want to start or create a new simulation. If you choose create, you will be able to configure a new simulation (with the configured packageId
, teamId
, simulationClass
as default), then start it. If you choose start, you will be able to start an already existing simulation on Gatling Enterprise.
If you are on a CI environment, you don’t want to handle interaction with the plugin. You should then set the batchMode
option to true. In batch mode, no input will be asked from the user, the new simulation will be created using only the configuration.
Package
You can directly package your simulations for Gatling Enterprise Cloud:
sbt Gatling/enterprisePackage
This will generate the target/gatling/<artifactId>-gatling-enterprise-<version>.jar
package which you can then
upload to the Cloud.
To package simulations from the it
configuration, GatlingIt/enterprisePackage
will generate the
target/gatling-it/<artifactId>-gatling-enterprise-<version>.jar
package.
Package and upload
Configure
role.You must already have configured a package. Copy the package ID from the Packages table, or copy the simulation ID linked to the package from the Simulations table.
Configure the package ID or simulation ID on the plugin:
Gatling / enterprisePackageId := "YOUR_PACKAGE_ID"
// omit enterpriseApiToken when using environment variable or Java System property instead
Gatling / enterpriseApiToken := "YOUR_API_TOKEN"
Then package and upload your simulation to gatling Enterprise Cloud:
sbt Gatling/enterpriseUpload
To package and upload simulations from the it
configuration, simply replace Gatling/
with GatlingIt/
in the
configuration and command.
Working with Gatling Enterprise Self-Hosted
Build from sources
Once you have configured the SBT plugin on your project, Gatling Enterprise Self-Hosted can build it from sources without additional configuration. Add your source repository and configure your simulation to build from sources using SBT.
To make sure your setup is correct, you can run the packaging command and check that you get a jar containing all the
classes and extra dependencies of your project in target/gatling/<artifactId>-gatling-enterprise-<version>.jar
:
sbt Gatling/enterprisePackage
it
configuration, you will need to configure a custom build command in Gatling Enterprise, as the
default one is for the test
configuration:
sbt -J-Xss100M ;clean;GatlingIt/enterprisePackage -batch --error
Publish to a binary repository
Alternatively, you can package your simulations and publish them to a binary repository (JFrog Artifactory, Sonatype Nexus or AWS S3).
Enable publishing the Gatling test artifact, then define the repository:
Gatling / publishArtifact := true
publishTo := (
if (isSnapshot.value)
Some("private repo" at "REPLACE_WITH_YOUR_SNAPSHOTS_REPOSITORY_URL")
else
Some("private repo" at "REPLACE_WITH_YOUR_RELEASES_REPOSITORY_URL")
)
The packaged artifact will be automatically attached to your project and deployed with the tests
classifier when you publish it:
sbt publish
You can also set:
GatlingIt / publishArtifact := true
to publish Gatling simulations from theit
configuration, this artifact will be published with theit
qualifierCompile / publishArtifact := false
e.g. if your project only contains Gatling simulations and you don’t need to publish code fromsrc/main
.
Additional tasks
Gatling’s SBT plugin also offers four additional tasks:
Gatling/startRecorder
: starts the Recorder, configured to save recorded simulations to the location specified byGatling/scalaSource
(by default,src/test/scala
).Gatling/generateReport
: generates reports for a specified report folder.Gatling/lastReport
: opens by the last generated report in your web browser. A simulation name can be specified to open the last report for that simulation.Gatling/copyConfigFiles
: copies Gatling’s configuration files (gatling.conf & recorder.conf) from the bundle into your project resources if they’re missing.Gatling/copyLogbackXml
: copies Gatling’s default logback.xml.
Overriding JVM options
Gatling’s SBT plugin uses the same default JVM options as the bundle launchers or the Maven plugin, which should be sufficient for most simulations.
However, should you need to tweak them, you can use overrideDefaultJavaOptions
to only override those default options, without replacing them completely.
E.g., if you want to tweak Xms/Xmx to give more memory to Gatling
Gatling / javaOptions := overrideDefaultJavaOptions("-Xms1024m", "-Xmx2048m")
Sources
If you’re interested in contributing, you can find the gatling-sbt plugin sources on GitHub.