Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

The Gatling sbt plugin integrates Gatling into your sbt build for projects written in Scala, enabling you to run simulations using standard sbt test tasks, and to package or deploy them to Gatling Enterprise Edition. It provides two configurations — Gatling and GatlingIt — so you can separate fast functional tests from longer integration-style load tests.
This plugin supports Scala simulations only. For Java or Kotlin simulations, use the Maven plugin or the Gradle plugin instead.
This plugin requires sbt 1 (sbt 0.13 is not supported). All examples on this page use the unified slash syntax introduced in sbt 1.1.
Clone the official demo project to get started quickly: gatling-sbt-plugin-demo

​
Versions

Check available versions on Maven Central. Milestone (M) versions are for Gatling Enterprise Edition customers only.

​
Setup

​
Step 1 — Add the Plugin

Add the Gatling sbt plugin to project/plugins.sbt: 
addSbtPlugin("io.gatling" % "gatling-sbt" % "MANUALLY_REPLACE_WITH_LATEST_VERSION")

​
Step 2 — Enable in build.sbt

Enable the GatlingPlugin and add the required library dependencies in 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"

​
Configurations: Gatling vs. GatlingIt

The plugin provides two sbt configurations that map to different source directories:
ConfigurationSource DirectoryReport OutputTypical Use
Gatlingsrc/test/scalatarget/gatlingFast tests run alongside unit tests
GatlingItsrc/it/scalatarget/gatling-itLong-running integration load tests
When using GatlingIt, prefix all commands with GatlingIt/. For example, Gatling/test becomes GatlingIt/test.
Override default source and target directories when needed: 
Gatling / scalaSource := sourceDirectory.value / "gatling" / "scala"
lazy val root = (project in file(".")).settings(inConfig(Gatling)(Defaults.testSettings): _*)

​
Running Simulations

Run all simulations in the Gatling configuration: 
sbt Gatling/test
Run a single simulation by its fully qualified class name from the GatlingIt configuration: 
sbt 'GatlingIt/testOnly com.example.MySimulation'

​
Overriding JVM Options

The plugin uses sensible JVM defaults. To adjust heap settings without replacing the defaults entirely, use overrideDefaultJavaOptions: 
Gatling / javaOptions := overrideDefaultJavaOptions("-Xms1024m", "-Xmx2048m")

​
Additional Tasks

The plugin also exposes the following utility tasks:

Gatling/startRecorder

Starts the Gatling Recorder, saving results to the path set by Gatling/scalaSource.

Gatling/generateReport

Generates an HTML report for a specified results folder.

Gatling/lastReport

Opens the most recently generated report in your web browser.

Gatling/copyConfigFiles

Copies gatling.conf and recorder.conf from the bundle into your project resources if absent.

​
Running Simulations on Gatling Enterprise Edition

​
Prerequisites

You need a Gatling Enterprise Edition API token with the Configure role on the expected teams. Store it using one of:
  • The GATLING_ENTERPRISE_API_TOKEN environment variable
  • The gatling.enterprise.apiToken Java system property
If absolutely required, it can also be set in build.sbt: 
Gatling / enterpriseApiToken := "YOUR_API_TOKEN"

​
Deploying to Gatling Enterprise Edition

Create or update packages and simulations automatically: 
sbt Gatling/enterpriseDeploy
To target a different package descriptor file: 
sbt 'Gatling/enterpriseDeploy --package-descriptor-filename "mypackage.conf"'

​
Starting Simulations on Gatling Enterprise Edition

Deploy and start a simulation in a single command: 
sbt Gatling/enterpriseStart
To bypass the interactive prompt by specifying the simulation name directly: 
sbt 'Gatling/enterpriseStart "My Simulation Name"'
To wait for the run to complete and fail the build on assertion failures, set this in build.sbt: 
Gatling / waitForRunEnd := true
Additional command options:
  • --run-title <title> — Sets a title for the run report.
  • --run-description <description> — Sets a description for the run summary.

​
Packaging for Manual Upload

Generate a deployable JAR for manual upload: 
sbt Gatling/enterprisePackage
This produces target/gatling/<artifactId>-gatling-enterprise-<version>.jar. For the GatlingIt configuration: 
sbt GatlingIt/enterprisePackage
Produces target/gatling-it/<artifactId>-gatling-enterprise-<version>.jar.

​
Private Packages

Configure the Control Plane URL for private location deployments in build.sbt: 
Gatling / enterpriseControlPlaneUrl := Some(URI.create("YOUR_CONTROL_PLANE_URL").toURL)

​
Sources

Plugin source code is available on GitHub: gatling/gatling-sbt.

Build docs developers (and LLMs) love

Get started for freeTalk to us