Integrate Gatling into Gradle Builds with the Gradle Plugin (2026)

The Gradle Gatling plugin lets you run your Gatling load tests directly from your build process, treating them like any other unit or integration test.

Let’s see it in action. Imagine you have a simple Gatling simulation written in Scala:

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

class BasicSimulation extends Simulation {

  val httpProtocol = http
    .baseUrl("http://localhost:8080")
    .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
    .doNotTrackHeader("DNT", "1")
    .disableCaching

  val scn = scenario("My Scenario")
    .exec(http("Home Page")
      .get("/")
      .check(status.is(200)))
    .pause(5)

  setUp(scn.inject(rampUsers(10) during (10 seconds))).protocols(httpProtocol)
}

To integrate this into your Gradle build, you’ll first apply the Gatling plugin in your build.gradle file:

plugins {
  id 'java'
  id "io.gatling.gradle" version "3.9.0" // Use the latest version
}

repositories {
  mavenCentral()
}

dependencies {
  // Gatling core dependency
  gatling "io.gatling:gatling-core:3.9.0"
  gatling "io.gatling.highcharts:gatling-charts-highcharts:3.9.0" // For HTML reports

  // Your simulation code (if not in main/test sources)
  // If your simulation is in src/gatling/scala, you don't need this.
  // Otherwise, ensure it's on the classpath for the Gatling task.
  // implementation 'com.example:my-load-tests:1.0.0'
}

// Optional: Configure Gatling task
gatling {
  // Where your simulations are located. Defaults to src/gatling/scala.
  // sources {
  //   scala.srcDirs = ['src/load-tests/scala']
  // }

  // Where the results will be stored. Defaults to build/gatling.
  // resultsDir = 'build/gatling-results'

  // Whether to include the Gatling console (interactive mode). Defaults to true.
  // console = true

  // Arguments to pass to the Gatling JVM.
  // jvmArgs = ['-Xmx2g']

  // Arguments to pass to the Gatling runner.
  // args = ['-s', 'com.example.MySimulation'] // Run a specific simulation
}

With this setup, Gradle automatically creates a gatling task. You can run your load tests by simply executing:

./gradlew gatling

This command will compile your Scala simulations (if they are in the src/gatling/scala directory or a configured source set), package them, and then execute them using the Gatling engine. Gatling will run the defined scenarios against your target application, collect metrics, and generate a detailed HTML report in the build/gatling directory (or your configured resultsDir).

The gatling plugin manages the entire lifecycle: compiling your simulation code, setting up the Gatling runtime, executing the tests, and processing the results. It leverages Gradle’s task dependency system, so if you run check or build, and the Gatling task is configured to run as part of that lifecycle (e.g., by making check.dependsOn gatling), your load tests will execute automatically.

The core problem this solves is treating performance testing as a first-class citizen in your CI/CD pipeline. Instead of manually triggering load tests or relying on separate tooling, you integrate them directly into your build, ensuring performance is checked with every build or at defined stages. The plugin handles the complexities of Gatling’s execution environment, such as classpath management for simulations and dependencies, and ensures consistent reporting.

The gatling configuration block in build.gradle is your primary lever. You can define where Gatling looks for simulation files using sources.scala.srcDirs. By default, it’s src/gatling/scala, which is a common convention. If you place your simulations elsewhere, you must configure this. You can also specify the output directory for reports with resultsDir. The console flag controls whether Gatling runs in interactive mode, which is useful for debugging but often disabled in automated CI environments. Finally, jvmArgs and args allow fine-grained control over the Gatling JVM process and the Gatling runner itself, respectively, enabling you to pass specific Gatling configurations or system properties.

A common pitfall is misconfiguring the sources.scala.srcDirs. If your simulations aren’t found, it’s almost always because this path doesn’t correctly point to the directory containing your .scala files. Ensure the path is relative to your project root and accurately reflects your project structure. If you’re using a custom source set, you’ll need to define it properly in your build.gradle and then reference it within the gatling block.

The most surprising thing about integrating Gatling with Gradle is how seamlessly it handles dependencies. You don’t typically need to manually add Gatling core or chart dependencies to your implementation or testImplementation configurations. By declaring them with the gatling configuration (e.g., gatling "io.gatling:gatling-core:3.9.0"), you signal to the plugin that these are specifically for the Gatling runtime, and it will correctly place them on the classpath for the Gatling task without polluting your application’s runtime classpath.

Once your Gatling tests are running as part of the build, the next logical step is to integrate Gatling Enterprise for more advanced features like distributed load generation and centralized reporting.