Checks & Assertions¶
Gatling separates validation into two distinct layers:
1. Checks inspect every individual response in real time—marking bad responses as KO and extracting dynamic values into the virtual user's Session.
2. Assertions evaluate aggregate statistics across the entire simulation at the end of the run—determining whether the Maven build passes or fails against your SLOs.
flowchart LR
Resp["Individual HTTP Response"] --> Check["Checks (Per-Request)<br/>• status().is(200)<br/>• jsonPath('$.id').saveAs('id')<br/>• responseTimeInMillis().lt(1000)"]
Check -->|"Pass -> OK / Fail -> KO"| Stats["Aggregated Run Histograms"]
Stats --> Assert["Assertions (End-of-Run Gate)<br/>• global().responseTime().percentile(95.0).lt(300)<br/>• global().successfulRequests().percent().gte(99.9)"]
Assert -->|"All True"| BuildPass["Maven Exit 0 (CI Green)"]
Assert -->|"Any False"| BuildFail["Maven Exit 1 (CI Red)"]
1. Response Checks (check)¶
By default, Gatling implicitly checks that HTTP responses return a 2xx or 304 status code. Explicit .check(...) rules verify status codes, headers, payload structure, and per-request latency—and extract data for correlation.
Essential Check Reference¶
exec(http("Create Order")
.post("/api/orders")
.body(ElFileBody("bodies/create_order.json"))
.check(
// 1. HTTP Status Validation
status().is(201), // Exact match (or .in(200, 201))
// 2. Header Extraction
header("Location").exists(),
header("X-Request-Id").saveAs("traceId"),
// 3. JSON Payload Validation & Extraction (JSONPath / JMESPath)
jsonPath("$.status").is("CONFIRMED"),
jsonPath("$.items[*].sku").findAll().saveAs("allSkus"), // Saves List<String>
jsonPath("$.orderId").saveAs("orderId"), // Saves String for next step
// 4. Substring / Regex / Response Time
bodyString().not(contains("Internal Error")),
responseTimeInMillis().lte(1500) // Mark KO if > 1.5s!
));
Transforming & Defaulting Extracted Data¶
You can transform extracted values on the fly before saving them into Session, or guard optional fields with .optional():
.check(
jsonPath("$.totalCents")
.ofInt()
.transform(cents -> cents / 100.0)
.saveAs("totalDollars"),
jsonPath("$.discountCode")
.optional() // Won't mark request KO if field is absent!
.saveAs("discountCode")
)
2. SLO Assertions (assertions)¶
Assertions attach to setUp(...) and compose three parts: Scope $\rightarrow$ Statistic / Metric $\rightarrow$ Condition.
Assertion Scopes¶
| Scope | Meaning | Example |
|---|---|---|
global() |
Aggregated across all requests in the entire simulation | global().successfulRequests().percent().gte(99.5) |
forAll() |
Evaluated individually against every request name—fails if any single endpoint violates the threshold! | forAll().responseTime().percentile(99.0).lt(1000) |
details("Group", "Req") |
Targets one specific named request or group | details("Browse Phase", "Search Catalog").responseTime().percentile(95.0).lt(150) |
Complete Production Assertion Suite¶
setUp(
checkoutScenario.injectOpen(constantUsersPerSec(100).during(Duration.ofMinutes(10)))
)
.protocols(httpProtocol)
.assertions(
// Availability / Error Budget
global().successfulRequests().percent().gte(99.9),
global().failedRequests().count().lt(50L),
// Global Latency Percentiles (Note: Java DSL uses .percentile(double), not .p95()!)
global().responseTime().percentile(50.0).lt(100),
global().responseTime().percentile(95.0).lt(300),
global().responseTime().percentile(99.0).lt(800),
// Endpoint-Specific Critical Path Gate
details("Create Order").responseTime().percentile(95.0).lt(450),
details("Create Order").successfulRequests().percent().gte(99.95),
// Guardrail: No individual endpoint may breach 1.5s at P99
forAll().responseTime().percentile(99.0).lt(1500)
);
Gatling Java DSL Syntax Note
In Gatling 3.8+ Java DSL, percentiles are written .percentile(95.0) or .percentile3() (defaulting to P95 in gatling.conf), not .p95(). Using .percentile(95.0) and .percentile(99.0) is explicit, self-documenting, and independent of config overrides!
Knowledge Check¶
What is the difference between global().responseTime().percentile(95.0).lt(300) and forAll().responseTime().percentile(95.0).lt(300)?
Next Steps¶
- Read next: Session & Correlation — Master immutable
Sessionstate management and multi-step request correlation.