Gatling: Reports, Assertions & CI Integration

Why Percentiles, Not Averages

• An average can look fine even when a meaningful fraction of users have a much worse experience -- p95/p99 reveal that tail latency directly.

• Gatling's HTML report breaks down response time distributions, throughput over time, and per-request/per-group statistics.

• As concurrency approaches a system's capacity limit, throughput plateaus while response times climb -- a queuing signature the report's graphs are designed to surface.

• A request can return a correct 200 status while taking 8 seconds under load -- functionally correct, but a real performance problem a pass/fail check alone wouldn't flag.

Assertions: Making Performance a CI Gate

setUp(scn.inject(rampUsers(1000).during(60.seconds)))
  .protocols(httpProtocol)
  .assertions(
    global.responseTime.percentile(95).lt(500),   // whole-simulation p95 < 500ms
    global.successfulRequests.percent.gt(99),
    details("Get Homepage").responseTime.percentile(95).lt(300), // per-request
  )

// A violated assertion fails the Gatling run -- and therefore the CI
// build -- the same way a broken unit test would, catching a
// performance regression (like a new N+1 query) before it ships.

CI Integration

# Run headlessly in CI -- generates the HTML report as a build artifact
./mvnw gatling:test
# or
./gradlew gatlingRun

# Assertions failing exits non-zero, gating the pipeline the same way
# a failed functional test suite would.

Testing Environment Considerations

• Run the load generator on a machine with sufficient CPU/network headroom -- if the generator itself is the bottleneck, results reflect its limits, not the system under test's.

• Prefer a staging environment closely matching production over load testing production directly -- avoids risking a self-inflicted outage for real users.

• Staging may not perfectly replicate production's data volume or cache warmth -- a known limitation to account for when interpreting results.

• Beyond HTTP, Gatling also supports WebSocket, JMS, gRPC, and MQTT via its extensible DSL for non-REST systems.