Configuring Gatling HTTP Checks and Assertions for Reliable CI/CD Gatekeeping

Goal: Fail CI build when API SLA breached

In a CI pipeline you want the build to stop automatically if response times exceed a threshold, error rates rise, or required fields are missing. Gatling lets you embed checks directly on HTTP calls and define global assertions that evaluate after the simulation runs.

Prerequisites

The simulation must extend Simulation and use Gatling 3.8+ (Scala 2.13 or 3.3). You need an HTTP protocol configuration with a baseUrl, a scenario that calls the target endpoint, and an assertions block inside setUp(...).assertions(...). Ensure the CI agent has at least 2 GB heap (-Xmx2G) and enough file descriptors.

Step‑by‑step procedure

1. Add response‑level checks to critical requests.

   exec(http("Login")
     .get("/api/login")
     .check(status.is(200), jsonPath("$.token").saveAs("authToken")))

2. Define global SLA assertions that apply to the whole run.

   setUp(
     scenario("Login scenario")
       .exec(http("Login").get("/api/login"))
   ).assertions(
     global.responseTime.max.lt(500),
     global.successfulRequests.percent.gt(95),
     forAll.failedRequests.count.is(0)
   )

3. Run the simulation from the command line or via Maven/Gradle.

   gatling.sh -sf simulations -rf results -rd "Login SLA test"

4. Check the exit code. A zero exit means all assertions passed; any non‑zero code indicates a breach. In CI you can capture it with echo $? or parse the JUnit XML.
5. Inspect the HTML report at target/gatling/<simulation>/index.html. The Assertions tab lists each rule, its threshold, actual value, and a green/red indicator.
6. If the build fails, re‑run only the failing simulations with -ro after adjusting thresholds or code, then re‑evaluate.

Verification

To confirm that assertions truly affect the exit code, create a minimal simulation that intentionally violates a rule:

• Set global.responseTime.max.lt(1) – this is impossible for any realistic request.
• Run the simulation and observe a non‑zero exit status.
• Open the HTML report; the Assertions table will show a red row for the latency rule.
• Generate JUnit XML with Maven: mvn gatling:test -Dgatling.junit=true and verify a <failure> element inside <testcase> for the latency assertion.

Recovery & troubleshooting

When an assertion fails, the virtual user continues unless you add .exitHereIfFailed to the scenario chain. To debug check evaluation, enable debug logging in conf/logback.xml or raise the log level in gatling.conf. If the CI agent runs out of memory, increase the heap or reduce the number of concurrent users. As a fallback, download the HTML report and review the Assertions tab manually.

Limitations

Assertions are evaluated after the full simulation, so they cannot abort a running scenario early. Body‑level checks such as JSONPath add CPU load; use them sparingly in high‑throughput smoke tests. Older Gatling versions (pre‑3.7) used a different DSL where only global assertions were available; migrating to 3.8+ requires updating the assertions syntax.