Documentation Index
Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt
Use this file to discover all available pages before exploring further.
Assertions let you define quantitative pass/fail thresholds for a Gatling simulation. Rather than manually inspecting charts after every run, you express your performance requirements as assertions — for example, “the 99th-percentile response time must be below 500 ms” or “less than 1% of requests may fail” — and Gatling evaluates them automatically when the simulation ends. If any assertion fails, the simulation exits with a non-zero code, integrating cleanly into CI/CD pipelines.
Assertions are registered via .assertions() on setUp and accept a chain of calls that define: the scope (which requests), the statistic (what to measure), the metric (which aspect of that statistic), and the condition (the threshold).
Registering Assertions
Java
JavaScript / TypeScript
setUp(scn.injectOpen(injectionProfile))
.assertions(
global().responseTime().max().lt(50),
global().successfulRequests().percent().gt(95.0)
);
setUp(scn.injectOpen(injectionProfile))
.assertions(
global().responseTime().max().lt(50),
global().successfulRequests().percent().gt(95.0)
);
Scope
The scope determines which requests contribute to the statistic being asserted.
| Scope | Description |
|---|
global() | Statistics calculated from all requests in the simulation. |
forAll() | Statistics calculated per individual request; every request must satisfy the condition. |
details(path...) | Statistics for a specific named request or group. Path segments work like a Unix filesystem path. |
Java
JavaScript / TypeScript
// assert on a single named request
details("MyRequest");
// assert on a request nested inside a group
details("MyGroup", "MyRequest");
details("MyRequest");
details("MyGroup", "MyRequest");
For WebSocket checks, use the check name (as passed to ws.checkTextMessage("name")) rather than the request name.
When details targets a group, assertions are matched against the group’s cumulated response time (the sum of all request times within the group), not the group’s total wall-clock duration.
Statistics
Choose what to measure after selecting the scope:
| Statistic | Description |
|---|
responseTime() | Response time in milliseconds. |
allRequests() | Total number of requests. |
failedRequests() | Number of failed requests. |
successfulRequests() | Number of successful requests. |
requestsPerSec() | Throughput rate (requests per second). |
Metrics
Applicable to responseTime()
| Metric | Description |
|---|
min() | Minimum observed response time. |
max() | Maximum observed response time. |
mean() | Arithmetic mean of all response times. |
stdDev() | Standard deviation of response times. |
percentile1() | Configured 1st percentile (default: p50). |
percentile2() | Configured 2nd percentile (default: p75). |
percentile3() | Configured 3rd percentile (default: p95). |
percentile4() | Configured 4th percentile (default: p99). |
percentile(value) | Arbitrary percentile as a double between 0 and 100. |
Applicable to Request Counts
| Metric | Description |
|---|
percent() | Value as a percentage (0–100). |
count() | Raw count of requests. |
Conditions
Conditions can be chained to apply multiple thresholds to the same metric.
| Condition | Description |
|---|
lt(threshold) | Less than. |
lte(threshold) | Less than or equal to. |
gt(threshold) | Greater than. |
gte(threshold) | Greater than or equal to. |
between(min, max) | Inclusive bounds by default. |
between(min, max, inclusive=false) | Exclusive bounds. |
around(value, plusOrMinus) | Within a fixed margin around a target. |
around(value, plusOrMinus, inclusive=false) | Exclusive version. |
deviatesAround(target, percentDeviation) | Within a relative (percentage) margin. |
deviatesAround(target, percentDeviation, inclusive=false) | Exclusive version. |
is(value) | Exact equality. |
in(sequence) | Value must be one of the provided values. |
In Kotlin, is and in are reserved keywords. Use backticks (`is`, `in`) or the aliases shouldBe and within instead.
Examples
Java
JavaScript / TypeScript
// max response time of all requests < 100 ms
setUp(scn.injectOpen(injectionProfile))
.assertions(global().responseTime().max().lt(100));
// every individual request has ≤ 5% failure rate
setUp(scn.injectOpen(injectionProfile))
.assertions(forAll().failedRequests().percent().lte(5.0));
// "MyRequest" in "MyGroup" has exactly 0% failures
setUp(scn.injectOpen(injectionProfile))
.assertions(details("MyGroup", "MyRequest").failedRequests().percent().is(0.0));
// "MyGroup" throughput is between 100 and 1000 req/sec
setUp(scn.injectOpen(injectionProfile))
.assertions(details("MyGroup").requestsPerSec().between(100.0, 1000.0));
// max response time of all requests < 100 ms
setUp(scn.injectOpen(injectionProfile))
.assertions(global().responseTime().max().lt(100));
// every individual request has ≤ 5% failure rate
setUp(scn.injectOpen(injectionProfile))
.assertions(forAll().failedRequests().percent().lte(5.0));
// "MyRequest" in "MyGroup" has exactly 0% failures
setUp(scn.injectOpen(injectionProfile))
.assertions(details("MyGroup", "MyRequest").failedRequests().percent().is(0.0));
// "MyGroup" throughput is between 100 and 1000 req/sec
setUp(scn.injectOpen(injectionProfile))
.assertions(details("MyGroup").requestsPerSec().between(100.0, 1000.0));
Gatling Enterprise Edition adds time window options that let you exclude warm-up and ramp-down periods from assertion calculations. Additionally, when Service Level Objectives (SLOs) are configured on a test in Enterprise Edition, they take precedence over simulation-level assertions — assertions defined in code will not be evaluated when SLOs are active.
