Thresholds in k6 - The Guardrails of Performance Testing

When you test a SaaS dashboard—or any web service—you’re not just measuring numbers. You’re defining boundaries. These boundaries are called thresholds, and they describe what “good enough” means for your system under load. In k6, these boundaries are called thresholds, and they act like automatic pass/fail checks for your test script.

Thresholds answer questions like:

• How slow can requests get before users notice?
• How many requests are allowed to fail before it becomes unacceptable?
• How much throughput should the system handle reliably?

Before setting thresholds, you need to understand the fundamentals: what latency means, what percentiles represent, and why units matter.

In this post, we’ll walk through thresholds step by step using your JWT SaaS dashboard API from earlier posts.

Table of contents

What Latency Actually Measures

Latency is the time it takes for a request to travel through your system and return a response. In k6, it includes:

• Connecting to the server
• TLS handshake (if HTTPS)
• Sending the request
• Waiting for the response
• Receiving the full response

In k6 you’ll see numbers like:

http_req_duration: 0.233

That means 0.233 seconds, which is 233 ms.

Percentiles: Why They Matter

Some requests will always be slower due to network hiccups, server load, or cache misses.Actual response to Real-world users will always be in flux.

Percentiles show how your system behaves for most users:

• p90: 90% of requests are this fast or faster
• p95: 95% are this fast or faster
• p99: Only the slowest 1% exceed this value

Example:

If p99 = 900 ms, then 99% of your requests completed under 900 ms. That upper tail is meaningful because even small tail latencies can break user flows in dashboards:

Error Rate and Its Thresholds

Error thresholds define what failure level is acceptable.

Typical categories:

• HTTP 4xx: client errors (invalid token, bad input)
• HTTP 5xx: server errors (bugs, overload)
• Connection errors: timeouts or broken pipelines

Example threshold:

http_req_failed: ["rate<0.01"]

Meaning: < 1% of all requests may fail during the entire test.

Throughput and Why It Gets a Threshold Too

Throughput measures how many requests per second your service can sustain. In SaaS dashboards, throughput tends to spike:

• Right after login
• During refresh cycles
• When widgets auto-update
• When teams export data at the same time

A throughput threshold might look like:

checks: ["rate>100"]

Meaning: The service should handle more than 100 successful operations per second.

Throughput thresholds prevent silent regressions where latency looks fine but capacity quietly drops.

Three Categories of Thresholds (Conceptually)

k6 divides thresholds into conceptual types:

1. Thresholds That Must Be Fast

These directly impact UX.

Common metrics:

• http_req_duration
• http_req_waiting
• http_req_connecting

These are strict. If the 95th percentile goes above your defined limit, the test fails.

2. Thresholds That Can Be Slower

These are more flexible and used to observe trends, not enforce strict rules.

Examples:

• vus (virtual users)
• iteration_duration
• http_req_sending

They’re still important, but they rarely make the test fail.

3. Thresholds That Must Never Fail

These represent hard requirements.

Examples:

• Error rate must stay below 1%
• Authentication failures must stay below 0.1%
• DNS failures must be zero

These act as non-negotiable “gates.”

Putting It All Together

export const options = {
  thresholds: {
    // Latency
    http_req_duration: ["p(95)<500", "p(99)<900"],

    // Error rate
    http_req_failed: ["rate<0.01"],

    // Throughput
    checks: ["rate>100"],
  },
};

What this means,

• http_req_duration: [“p(95)<500”, “p(99)<900”]:
  • 95% of all requests must finish faster than 500 ms.
  • 99% of all requests must finish faster than 900 ms.
• http_req_failed: [“rate<0.01”]:
  • The threshold uses a ratio (0 to 1) so, 0.01 means 1%.
  • Fewer than 1% of all requests may fail, If even 1.1% fail, the test fails.
• checks: [“rate>100”]:
  • The system must maintain at least 100 successful operations per second.

Exercises (Try It Yourself)

• Modify your JWT SaaS dashboard script to add a p90 latency threshold for the login endpoint.
• Add a check that verifies the response JSON contains access token and add a throughput threshold.
• Simulate a failed request (wrong password) and observe how the http_req_failed threshold responds.