Skip to content

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 Session state management and multi-step request correlation.