Running Gatling Tests from the CLI with Maven or Gradle

Did you know that running Gatling tests from the command line can significantly enhance your performance testing workflow? Mastering command-line execution and runtime parameters saves time and boosts CI/CD integration.

Introduction to Running Gatling Tests from the Command Line

Performance testing is a crucial aspect of modern software development, especially when deploying applications to production or test environments. While IDE-based execution is convenient for debugging and quick iterations, it can become a bottleneck in automated pipelines. By running Gatling tests from the command line, you unlock reproducibility, scalability, and seamless integration with build tools such as Maven and Gradle. In this guide, we’ll walk through the setup steps, share best practices, and show how to customize Gatling scripts with runtime parameters to make them flexible and CI-ready.

“when we come to run our performance test in production and test environments we want to trigger them from the command line” – Gatling course transcript

This approach ensures that your tests run the same way locally, on a build server, or in a containerized environment. You’ll also learn techniques for passing parameters to adjust user counts, ramp-up duration, and overall test time without modifying the code each time.

Running Tests from the Command Line Using Gradle

If you’re using the Gradle build system, the Gatling plugin simplifies CLI execution. First, make sure you have applied the plugin in your build.gradle file:

plugins {
    id 'io.gatling.gradle' version '3.9.5'
}

Once configured, navigate to your project root in a terminal and run:

./gradlew gatlingRun -Dgatling.simulationClass=simulations.RuntimeParametersSimulation

This command compiles your Scala scenario classes, packages them, and launches Gatling headlessly. Gradle will output progress details, simulate HTTP calls, and finally generate a detailed HTML report in build/reports/gatling. You can also chain additional parameters with -D flags, which we’ll cover in later sections. The key benefit is that the entire process can be scripted, version controlled, and invoked in any environment that has Java and Gradle installed.

Running Tests from the Command Line Using Maven

For teams standardized on Maven, the Gatling Maven plugin offers comparable capabilities. In your pom.xml, include:

<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>3.9.5</version>
  <executions>
    <execution>
      <goals>
        <goal>test</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Then execute:

mvn clean test -Dgatling.simulationClass=simulations.RuntimeParametersSimulation

Maven will compile your project, run the specified Gatling simulation class, and output results under target/gatling. You can pass parameters just like with Gradle:

mvn test \
  -Dusers=10 \
  -DrampDuration=15 \
  -Dduration=120 \
  -Dgatling.simulationClass=simulations.RuntimeParametersSimulation

This method leverages the same runtime-parameter techniques and ensures consistency across different build systems.

Adding Runtime Parameters to Gatling Scripts

Hard-coding values in your simulation can be limiting. Instead, add a small helper method at the top of your Scala script to read environment or system properties, falling back to defaults when none are provided:

private def getProperty(name: String, defaultVal: String): String =
  Option(System.getenv(name))
    .orElse(Option(System.getProperty(name)))
    .getOrElse(defaultVal)

Next, define strongly typed properties for common load test parameters:

def usersCount: Int = getProperty("users", "5").toInt
def rampDuration: Int = getProperty("rampDuration", "10").toInt
def testDuration: Int = getProperty("duration", "60").toInt

Optionally, add debug logging so that each test run clearly reports the chosen values:

println(s"Running with $usersCount users")
println(s"Ramping up over $rampDuration seconds")
println(s"Total duration: $testDuration seconds")

This setup empowers you to change your load profile on the fly, without editing and recompiling code.

Executing Your Gatling Tests with Parameters

With runtime parameters defined, you can execute your tests from the CLI and tailor them per environment:

Gradle example:

./gradlew gatlingRun \
  -Dusers=3 \
  -DrampDuration=5 \
  -Dduration=30 \
  -Dgatling.simulationClass=simulations.RuntimeParametersSimulation

Maven example:

mvn clean test \
  -Dusers=3 \
  -DrampDuration=5 \
  -Dduration=30 \
  -Dgatling.simulationClass=simulations.RuntimeParametersSimulation

If no parameters are provided, your script automatically falls back to the default values specified in code. This behavior prevents failures due to missing flags and makes your pipelines robust and predictable.

Integrating Gatling CLI into CI/CD Pipelines

Embedding Gatling into continuous integration systems like Jenkins, GitLab CI, or GitHub Actions ensures that performance regressions are caught early. Create a pipeline step that installs Java, checks out your code, and runs your tests with the desired parameters. For example, in a Jenkinsfile:

stage('Performance Test') {
  steps {
    sh './gradlew clean gatlingRun ' +
       '-Dusers=10 -DrampDuration=20 -Dduration=120 ' +
       '-Dgatling.simulationClass=simulations.RuntimeParametersSimulation'
    publishHTML(target: [
      allowMissing: false,
      alwaysLinkToLastBuild: true,
      keepAll: true,
      reportDir: 'build/reports/gatling',
      reportFiles: 'index.html',
      reportName: 'Gatling Performance Report'
    ])
  }
}

By automating report publication, you can trend key metrics over time, compare builds, and enforce performance budgets as part of your pull request validations.

Conclusion

You now have the knowledge to run Gatling tests from the command line with either Maven or Gradle, customize your load scenarios using runtime parameters, and integrate your performance tests into CI/CD pipelines. This approach streamlines the testing process, enhances reproducibility, and supports continuous delivery of reliable, high-performing applications.

• Actionable takeaway: Use -D parameters to dynamically adjust load without modifying your simulation code, ensuring flexibility and consistency across local and automated test runs.

What parameter will you configure first for your next Gatling performance test?