Assertions

Turn your load tests into Pass/Fail gates by asserting performance thresholds.

Overview

Assertions evaluate the final aggregate metrics of a test run against conditions you define. If any condition is violated, the overall test verdict is marked as FAIL and the CLI exits with code 1. This makes it effortless to integrate Overload into CI/CD pipelines.

Expression Syntax

An assertion expression follows this simple format: <metric><operator><value>

Example: p95_latency_ms<500

Available Metrics

Metric	Description
`p50_latency_ms`	Median latency in milliseconds. 50% of requests are faster than this.
`p95_latency_ms`	95th percentile latency. 95% of requests are faster than this.
`p99_latency_ms`	99th percentile latency. Excellent for tracking tail latency.
`max_latency_ms`	The absolute highest latency observed during the run.
`mean_latency_ms`	The average latency across all requests.
`error_rate_pct`	Percentage (0-100) of requests that returned 4xx, 5xx, or network errors.
`success_rate_pct`	Percentage (0-100) of requests that returned 2xx or 3xx status codes.
`avg_rps`	The actual average Requests Per Second achieved over the test.
`total_requests`	The absolute number of requests dispatched.
`rate_limited_count`	The absolute number of requests that returned a 429 status code.

Operators

Overload supports standard comparison operators:

< (Less than)
<= (Less than or equal to)
> (Greater than)
>= (Greater than or equal to)
== (Equal to)

Using Assertions

Via CLI

Pass assertions using the repeatable --assert flag:

overload run --collection api.json \
  --assert "p95_latency_ms<500" \
  --assert "error_rate_pct==0" \
  --assert "success_rate_pct>=99.9"

Via YAML Config

Store assertions in your overload.config.yaml under the thresholds list:

thresholds:
  - metric: p95_latency_ms
    operator: "<"
    value: 500
  - metric: error_rate_pct
    operator: "=="
    value: 0