gatling.sh: Run a Simulation with Assertions
Gatling runs a coded Simulation and, when that simulation declares assertions (e.g. global p99 under 500ms), exits non-zero if they fail, which fails the CI job.
Gatling defines load as code and its killer CI feature is assertions: put SLOs in the simulation and the process exit code enforces them. You run it via the bundle script, Maven, or Gradle.
What it does
Gatling executes a Simulation class describing scenarios, injection profiles, and assertions. It records every request, writes an HTML report, and evaluates the setUp(...).assertions(...) block. If any assertion (percentile latency, error rate, request count) fails, Gatling exits with a nonzero code.
Common usage
# bundle: pick a simulation non-interactively and set the results dir
./gatling.sh -s com.example.BasicSimulation -rf ./results
# Maven plugin
mvn gatling:test -Dgatling.simulationClass=com.example.BasicSimulationAssertion example
setUp(scn.injectOpen(rampUsers(100).during(30)))
.protocols(httpProtocol)
.assertions(
global.responseTime.percentile(99).lt(500),
global.failedRequests.percent.lt(1.0)
)Options
| Flag | What it does |
|---|---|
| -s, --simulation <class> | Fully qualified simulation class to run |
| -rf, --results-folder <dir> | Where to write the report |
| -rd, --run-description <text> | Label for the report |
| mvn gatling:test | Run via the Maven plugin |
| -Dgatling.simulationClass | Select the simulation for Maven/Gradle |
In CI
Put your SLOs in .assertions(...) and let Gatling own the exit code, so no output parsing is needed. Pass -s (or the Maven property) so it does not prompt to choose a simulation and hang the job. Upload the results folder as an artifact for triage.
Common errors in CI
Assertion(s) failed in the log with a nonzero exit is the intended threshold breach. There are no simulation scripts to run means the sources were not compiled or the class name is wrong. A job that hangs is usually Gatling waiting at the interactive simulation picker; always pass -s. Please define a JAVA_HOME or Unsupported class file major version means the runner JDK does not match Gatling requirements.