Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท 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