Skip to content

Lesson 11 ยท Checks and Thresholds

Checks in k6

Use k6 check() to validate status codes, bodies and timings, understand why failed checks do not stop a test, read the checks metric, and combine checks with thresholds.

Sending requests is only half of a useful test. A server under load often answers quickly with an error page, and a fast error looks great in the timing numbers. You must verify that the responses are correct. In k6 that is the job of check(). A check asserts something about a value, records the result as a metric, and then lets the test carry on. This is the important difference from a unit-test assertion: a failed check does not stop the test and does not make k6 exit with an error. It only lowers the checks pass rate. To turn the rate into a verdict you add a threshold.

The basic form

JavaScript
import http from 'k6/http';
import { check } from 'k6';

export default function () {
  const res = http.get('http://localhost:3000/api/products');

  check(res, {
    'status is 200': (r) => r.status === 200,
    'has products': (r) => r.json().length > 0,
    'fast enough': (r) => r.timings.duration < 500,
  });
}

check(value, checks) takes the thing to inspect (usually a response) and an object. Each key is a name shown in the summary, and each value is a function that receives the value and returns a boolean (true means pass). check() itself returns true only if all checks passed, which you can use to branch:

JavaScript
const ok = check(res, { 'status is 200': (r) => r.status === 200 });
if (!ok) {
  return; // skip the rest of this iteration
}

Without that guard, a failed login would be followed by requests using a missing token and you would measure garbage. Skipping the dependent steps is the usual pattern.

What the summary shows

TEXT
     โœ“ status is 200
     โœ— has products
      โ†ณ  85% โ€” โœ“ 170 / โœ— 30
     โœ“ fast enough

     checks.........................: 95.00% โœ“ 570  โœ— 30

Each check is listed with its pass percentage and counts. The overall checks line is a rate metric: passes divided by total evaluations. A single failing check out of three still contributes passes from the other two, so 95% overall can hide one check that is failing 15% of the time. Look at the per-check lines, not just the total.

Writing good checks

  • Name checks for what the user needs, not for the implementation. "order has an id" is clearer than "json path 1".
  • Check status first. If the status is 500, parsing the body as JSON will throw. A check function that throws marks the check as failed in recent k6 versions, but cleaner is to guard:
JavaScript
check(res, {
  'status is 201': (r) => r.status === 201,
  'body has id': (r) => r.status === 201 && typeof r.json('id') === 'number',
});
  • Keep checks cheap. Parsing a large JSON body in every check of every iteration costs CPU on the load generator and can distort results. Parse once: const body = res.json(); then check against body.
  • Do not repeat the same name for different things; checks are aggregated by name.
  • You can check any value, not just responses: check(items, { 'at least 3 items': (a) => a.length >= 3 }).

Checks versus thresholds

Check Threshold
Applies to One value at one moment A whole metric over the whole test
Failure effect Records a failed check, test continues Marks the test failed, non-zero exit code
Written in The default function options.thresholds
Example status is 200 checks: ['rate>0.99']

The two are meant to work together. Checks produce the data; the threshold checks: ['rate>0.99'] decides how many failed checks are acceptable.

JavaScript
export const options = {
  thresholds: { checks: ['rate>0.99'] },
};

A stand-in that mimics check()

The program below is not k6. It defines a check() function with the same behaviour: it evaluates named predicates, records pass/fail counters per name, returns whether all passed, and never throws. It runs against a flaky local server that fails every fourth request so you can see failing checks and the guard pattern.

Node.js Stand-in: check() records results and carries on

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Two of eight responses were 500s, so each check failed twice and the rate is 75%. Notice that the loop carried on after every failure, exactly like a real k6 test.

Checks on non-HTTP values and groups

Checks work inside group() and appear with the group's name in the summary, which keeps big scripts readable. They also accept a third argument, tags, when you need a sub-metric: check(res, { ok: (r) => r.status === 200 }, { endpoint: 'login' }) makes checks{endpoint:login} available to thresholds (Groups and Tags).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to the test when a check fails?

    Checks do not halt a test. They record pass/fail counts; use a threshold to fail the run.
  2. 2. What does check() return?

    The boolean lets you skip dependent steps when something failed.
  3. 3. Which threshold turns failed checks into a failed test?

    The checks metric is a rate; a threshold on its rate fails the run when the pass rate is too low.
  4. 4. Why look at per-check lines and not only the total checks percentage?

    The total averages all checks together, so a single failing check can be masked by many passing ones.

Summary

  • check(value, { name: fn }) records named pass/fail results and returns whether all passed.
  • Failed checks do not stop the test; combine them with a checks threshold to get a verdict.
  • Guard dependent steps with the return value; parse bodies once; check status before body.
  • Read each check's own pass rate in the summary, not just the total.

Next: Thresholds