k6chaijs on Grafana Labs

config

Mon, 21 Sep 2026 15:16:28 +0000

config

Chai exposes a few options to change the library configuration.

Config option	Default	Description
truncateMsgThreshold	300	Check message length is truncated to this value.
truncateVariableThreshold	100	Variables interpolated into check message are truncated to this length. It prevents mistakes when the check name is very large, especially when `aggregateChecks` is `false`.
aggregateChecks	true	The actual values are not interpolated into the check message. Disable for tests with 1 iteration.
logFailures	false	When the check fails, debug messages are printed.

import http from 'k6/http';
import chai, { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';

// individual variables should be up to 20 chars after rendering.
chai.config.truncateVariableThreshold = 20;

// whole check() message must be below 300 chars.
chai.config.truncateMsgThreshold = 300;

// the variable values (resp.status) are inserted into the check message - useful for debugging or tests with 1 iteration
chai.config.aggregateChecks = false;

// when the check fails, WARN messages with variables are printed. Useful for debugging.
chai.config.logFailures = true;

export default function testSuite() {
  describe('Testing bad assertion.', () => {
    const response = http.get('https://quickpizza.grafana.com');

    expect(response.body).to.have.lengthOf.at.least(100);
  });
}

Resulting in:

█ Testing bad assertion.
  ✓ expected '<!DOCTYPE html>\n<html lang="en">\n<hea...' to have property 'length'
  ✓ expected '<!DOCTYPE html>\n<html lang="en">\n<hea...' to have a length at least 100 got 2611

describe( name, function )

Mon, 21 Sep 2026 15:16:28 +0000

describe( name, function )

describe is a wrapper of group that adds the ability to:

Catch exceptions to allow continuing the execution outside of the describe function.
Returns a boolean to indicate the success of all its k6chaijs assertions.

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';

export default function testSuite() {
  const success1 = describe('Basic test', () => {
    expect(1, 'number one').to.equal(1);
  });
  console.log(success1); // true

  const success2 = describe('Another test', () => {
    throw 'Something entirely unexpected happened';
  });
  console.log(success2); // false

  const success3 = describe('Yet another test', () => {
    expect(false, 'my vaule').to.be.true();
  });
  console.log(success3); // false
}

default ✓ [======================================] 1 VUs  00m00.0s/10m0s  1/1 iters, 1 per VU

     █ Basic test
       ✓ expected number one to equal 1

     █ Another test
       ✗ Exception raised "Something entirely unexpected happened"
        ↳  0% — ✓ 0 / ✗ 1

     █ Yet another test
       ✗ expected my vaule to be true
        ↳  0% — ✓ 0 / ✗ 1

API

Parameter	Type	Description
name	string	Test case name. The test case name should be unique. Otherwise, the test case will be grouped.
function	function	The test case function to be executed

Returns

Type	Description
bool	Returns true when all `expect` conditions within the `describe()` body were successful, and no unhandled exceptions were raised, otherwise false.

Chaining describe() blocks

If you want to skip the execution of the following describe blocks, consider chaining them using && as shown below.

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';

export default function testSuite() {
  describe('Basic test', () => {
    expect(1, 'number one').to.equal(1);
  }) &&
    describe('Another test', () => {
      throw 'Something entirely unexpected happened';
    }) &&
    describe('Yet another test', () => {
      // the will not be executed because the prior block returned `false`
      expect(false, 'my vaule').to.be.true();
    });
}

expect()

Mon, 21 Sep 2026 15:16:28 +0000

expect()

expect is a wrapper of check to provide BDD style of assertions in k6. It implements the Chai Expect API:

import http from 'k6/http';
import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';

export default function () {
  describe('Basic test', () => {
    expect({ a: 1 }).to.not.have.property('b');
    expect(2).to.equal(2);
    expect({ a: 1 }).to.deep.equal({ a: 1 });
    expect({ a: { b: ['x', 'y'] } }).to.have.nested.property('a.b[1]');
    expect({ a: 1 }).to.have.own.property('a');
    expect([1, 2]).to.have.ordered.members([1, 2]).but.not.have.ordered.members([2, 1]);
    expect({ a: 1, b: 2 }).to.not.have.any.keys('c', 'd');
    expect({ a: 1, b: 2 }).to.have.all.keys('a', 'b');
    expect('foo').to.be.a('string');
    expect([1, 2, 3]).to.be.an('array').that.includes(2);
    expect('foobar').to.include('foo');
    expect(1).to.equal(1);
    expect(true).to.be.true;
    expect(false).to.be.false;
    expect(null).to.be.null;
    expect(undefined).to.be.undefined;
    expect(NaN).to.be.NaN;
    expect(1).to.equal(1);
    expect([]).to.be.empty;
    expect({}).not.to.be.arguments;
    expect(1).to.equal(1);
    expect({ a: 1 }).to.eql({ a: 1 }).but.not.equal({ a: 1 });
    expect('foo').to.have.lengthOf(3);
    expect(2).to.equal(2);
    expect(1).to.equal(1);
    expect(2).to.be.at.most(3);
    expect(2).to.equal(2);
    expect({ a: 1 }).to.not.be.an.instanceof(Array);
    expect({ a: 1 }).to.have.property('a');
    expect([1, 2, 3]).to.have.lengthOf(3);
    expect('foobar').to.match(/^foo/);
    expect('foobar').to.have.string('bar');
    expect({ a: 1, b: 2 }).to.have.all.keys('a', 'b');
    const badFn = function () {
      throw new TypeError('Illegal salmon!');
    };
    expect(badFn).to.throw();
    expect(1).to.satisfy(function (num) {
      return num > 0;
    });
    expect(1.5).to.equal(1.5);
    expect([1, 2, 3]).to.have.members([2, 1, 3]);
    expect('Today is sunny').to.contain.oneOf(['sunny', 'cloudy']);
    expect({ a: 1 }).to.be.extensible;
    expect(1).to.be.finite;
  });
}

When you run this test with k6 run script.js, the output at the end of the test shows:

default ✓ [======================================] 1 VUs  00m00.0s/10m0s  1/1 iters, 1 per VU

     █ Basic test

       ✓ expected ${this} to not have property 'b'
       ✓ expected ${this} to equal 2
       ✓ expected ${this} to deeply equal { a: 1 }
       ✓ expected ${this} to have nested property 'a.b[1]'
       ✓ expected ${this} to have own property 'a'
       ✓ expected ${this} to be an array
       ✓ expected ${this} to have the same ordered members as [ 1, 2 ]
       ✓ expected ${this} to not have the same ordered members as [ 2, 1 ]
       ✓ expected ${this} to not have keys 'c', or 'd'
       ✓ expected ${this} to have keys 'a', and 'b'
       ✓ expected ${this} to be a string
       ✓ expected ${this} to include 2
       ✓ expected ${this} to include 'foo'
       ✓ expected ${this} to equal 1
       ✓ expected ${this} to be true
       ✓ expected ${this} to be false
       ✓ expected ${this} to be null
       ✓ expected ${this} to be undefined
       ✓ expected ${this} to be NaN
       ✓ expected ${this} to be empty
       ✓ expected ${this} to not be arguments
       ✓ expected ${this} to not equal { a: 1 }
       ✓ expected ${this} to have property 'length'
       ✓ expected ${this} to have a length of 3 got ${actual}
       ✓ expected ${this} to be at most 3
       ✓ expected ${this} to not be an instance of Array
       ✓ expected ${this} to have property 'a'
       ✓ expected ${this} to match /^foo/
       ✓ expected ${this} to contain 'bar'
       ✓ expected ${this} to be a function
       ✓ expected ${this} to throw an error
       ✓ expected ${this} to satisfy [Function]
       ✓ expected ${this} to equal 1.5
       ✓ expected ${this} to have the same members as [ 2, 1, 3 ]
       ✓ expected ${this} to contain one of [ 'sunny', 'cloudy' ]
       ✓ expected ${this} to be extensible
       ✓ expected ${this} to be a finite number

Error handling

Mon, 21 Sep 2026 15:16:28 +0000

Error handling

When you execute a load test, your System Under Test (SUT) may often become over saturated and start responding with errors. In this case, you need to consider what the iteration execution should do:

to embrace the system error and continue the execution of the scenario
or to exit

It’s not uncommon for performance testers to forget about these cases. We often write fragile test code that assumes our system’s response will always succeed and contain the expected data.

import { check, group } from 'k6';
import http from 'k6/http';

export default function () {
  group('Fetch a list of pizza names', () => {
    const res = http.get('https://quickpizza.grafana.com/api/names');
    check(res, {
      'is status 200': (r) => r.status === 200,
      'got more than 5 crocs': (r) => r.json().length > 5,
    });
    // ... continue test within the group...
  });

  group('other group', () => {
    //...
  });
}

This code will work fine when the SUT returns correct responses. But, when the SUT starts to fail, r.json().length will throw an exception:

ERRO[0001] cannot parse json due to an error at line 1, character 2 , error: invalid character '<' looking for beginning of value
running at reflect.methodValueCall (native)

In this case, k6 throws a JavaScript exception and exits the execution of the current iteration but continues starting new iterations.

This might not be ideal because:

system errors are propagated as exceptions that are not reported on the test results
you might want to embrace these errors - as normal - and continue the execution

It’s possible to rewrite this test to be less fragile, but it can make our test code longer and less readable.

Handling exceptions

Sometimes it’s hard to predict how a SUT might fail. For those cases, describe catches any internal exceptions and:

records them as failed assertions
continues the execution (outside of its describe() function)

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';

export default function testSuite() {
  describe('Test case against a Shaky SUT', (t) => {
    throw 'Something entirely unexpected happened';
  });

  // this test case will be executed because
  // the previous `describe` catched the exception
  describe('Another test case', (t) => {
    expect(2).to.equal(2);
  });
}

█ Test case against a Shaky SUT

  ✗ Exception raised "Something entirely unexpected happened"
  ↳  0% — ✓ 0 / ✗ 1

█ Another test case

  ✓ expected ${this} to equal 2