k6-testing on Grafana Labs

expect()

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

expect()

The expect() function is the main entry point for creating assertions in the k6 testing library. It provides an intuitive API for both retrying and non-retrying assertions.

Syntax

expect(actual);
expect(actual, message);

Parameters

Parameter	Type	Description
actual	any	The value to test against
message	string	Optional custom error message

Returns

Type	Description
Expectation	An expectation object with assertion methods

Description

The expect() function wraps a value and returns an expectation object that provides assertion methods. The expectation object supports both retrying (that are asynchronous, and automatically retry until they pass or timeout) and non-retrying assertions (that are synchronous and evaluate immediately).

Non-retrying assertions

Standard assertions evaluate immediately and do not retry:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

expect(42).toBe(42);
expect([1, 2, 3]).toContain(2);

Retrying Assertions

Retrying assertions automatically retry until they pass or timeout. These are particularly useful for browser testing where elements may not be immediately available:

import { browser } from 'k6/experimental/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = browser.newPage();
  await page.goto('https://test.k6.io');

  // Auto-retrying assertions
  await expect(page.locator('h1')).toBeVisible();
  await expect(page.locator('h1')).toHaveText('Welcome to the k6 test site');
}

Negation

All assertions can be negated using the .not property:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

expect(42).not.toBe(43);
expect('hello').not.toContain('world');

Soft Assertions

By default, failed assertions will terminate the test execution. Soft assertions, on the other hand, don’t terminate the test execution when they fail, but mark the test as failed, leading k6 to eventually exit with code 110.

import exec from 'k6/execution';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  vus: 2,
  iterations: 10,
};

export default function () {
  // Iteration 3 will mark the test as failed, but the test execution
  // will keep going until its end condition, and eventually exit with
  // code 110.
  if (exec.scenario.iterationInInstance === 3) {
    expect.soft(false).toBeTruthy();
  }
}

Note that soft assertions can be configured to throw an exception (and effectively failing the iteration where it happens) instead.

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Configure soft mode globally
expect.configure({ softMode: 'continue' });

export default function () {
  // These assertions will not stop test execution on failure
  expect.soft(response.status).toBe(200);
  expect.soft(response.json()).toHaveProperty('data');
}

Examples

API Testing

import http from 'k6/http';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export default function () {
  const response = http.get('https://test-api.k6.io/public/crocodiles/1/');
  const data = response.json();

  // Basic assertions
  expect(response.status).toBe(200);
  expect(response.headers['Content-Type']).toContain('application/json');

  // Object assertions
  expect(data).toHaveProperty('id');
  expect(data.name).toBeDefined();
  expect(data.age).toBeGreaterThan(0);

  // With custom error message
  expect(data.status, 'Crocodile should be alive').toBe('alive');
}

Browser Testing

import { browser } from 'k6/experimental/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export default async function () {
  const page = browser.newPage();

  await page.goto('https://test.k6.io/my_messages.php');

  // Form interaction with assertions
  await expect(page.locator('#username')).toBeVisible();
  await page.locator('#username').fill('admin');
  await expect(page.locator('#username')).toHaveValue('admin');

  await page.locator('#password').fill('123');
  await page.locator('input[type="submit"]').click();

  // Verify navigation
  await expect(page.locator('h2')).toContainText('Welcome, admin!');
}

Assertion methods

Non-Retrying Assertions

Method	Description
toBe(expected)	Exact equality using Object.is()
toBeCloseTo(expected, precision?)	Floating point comparison
toBeDefined()	Value is not undefined
toBeFalsy()	Value is falsy
toBeGreaterThan(expected)	Greater than comparison
toBeGreaterThanOrEqual(expected)	Greater than or equal comparison
toBeInstanceOf(expected)	Value is an instance of a class
toBeLessThan(expected)	Less than comparison
toBeLessThanOrEqual(expected)	Less than or equal comparison
toBeNaN()	Value is NaN
toBeNull()	Value is null
toBeTruthy()	Value is truthy
toBeUndefined()	Value is undefined
toContain(expected)	Array/string contains value
toContainEqual(expected)	Array or Set contains a similar element
toEqual(expected)	Deep equality comparison
toHaveLength(expected)	Value has a expected length
toHaveProperty(path, expected?)	Property at provided path exists in the object and optionally checks that it is equal to expected

Retrying Assertions

Method	Description
toBeChecked(options?)	Checkbox is checked
toBeDisabled(options?)	Element is disabled
toBeEditable(options?)	Element is editable
toBeEnabled(options?)	Element is enabled
toBeHidden(options?)	Element is hidden
toBeVisible(options?)	Element is visible
toContainText(text, options?)	Element contains text
toHaveAttribute(attribute, value?)	Element attribute value
toHaveText(text, options?)	Element text content
toHaveValue(value)	Input element value

expect.configure()

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

expect.configure()

The expect.configure() method creates a new configured expect instance with custom behavior for the k6 testing library, including timeouts, display options, and soft assertion behavior.

This new instance can be used in place of the default expect function, and will apply the specified configuration to all assertions made with it.

The imported expect instance remains unchanged and continues to use the default configuration, allowing different assertion configurations to co-exist within a test.

Syntax

const configuredExpect = expect.configure(options);

Parameters

Parameter	Type	Description
options	object	Configuration options object

Options

Property	Type	Default	Description
timeout	number	`5000`	Default timeout in milliseconds for retrying assertions
interval	number	`100`	Polling interval in milliseconds for retrying assertions
colorize	boolean	`true`	Enable colorized output in assertion messages
display	string	`"pretty"`	Output format for assertion messages (`"pretty"` or `"inline"`)
softMode	string	`"fail"`	Soft assertion behavior (`"fail"` or `"throw"`)

Returns

Type	Description
Expect	A new expect instance with the specified configuration

Timeout configuration

The timeout option controls how long retrying assertions will wait for a condition to become true:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Create a configured expect instance with longer timeout for slow-loading elements
const slowExpect = expect.configure({
  timeout: 10000, // 10 seconds
  interval: 500, // Check every 500ms
});

Display Options

The display and colorize options control how assertion failures are reported:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Create expect instance with inline output and no colors
const inlineExpect = expect.configure({
  display: 'inline',
  colorize: false,
});

Soft Assertion Mode

The softMode option controls whether failed assertions stop test execution:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// The default behavior of soft assertions is mark the test as failed, the `softMode` option
// allows to configure soft assertions to throw an exception and fail the current iteration instead.
const softExpect = expect.configure({
  softMode: 'throw',
});

Environment Variables

Configuration options can also be set using environment variables:

Environment Variable	Option	Description
`K6_TESTING_TIMEOUT`	`timeout`	Default timeout in milliseconds
`K6_TESTING_INTERVAL`	`interval`	Polling interval in milliseconds
`K6_TESTING_COLORIZE`	`colorize`	Enable colored output (`true`/`false`)
`K6_TESTING_DISPLAY`	`display`	Output format (`pretty`/`inline`)
`K6_TESTING_SOFT_MODE`	`softMode`	Soft assertion mode (`fail`/`throw`)

# Set environment variables
export K6_TESTING_TIMEOUT=10000
export K6_TESTING_SOFT_MODE=throw
k6 run test.js

Examples

Basic Configuration

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Create a configured expect instance
const myExpect = expect.configure({
  timeout: 8000,
  interval: 200,
  colorize: true,
  display: 'pretty',
});

export default function () {
  // Use the configured instance
  myExpect(response.status).toBe(200);

  // Original expect instance still works with defaults
  expect(response.status).toBe(200);
}

Browser Testing Configuration

import { browser } from 'k6/experimental/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

// Create expect instance configured for browser testing with longer timeouts
const browserExpect = expect.configure({
  timeout: 15000, // Longer timeout for browser operations
  interval: 500, // Less frequent polling
});

export default async function () {
  const page = browser.newPage();
  await page.goto('https://test.k6.io');

  // Will wait up to 15 seconds for element to be visible
  await browserExpect(page.locator('h1')).toBeVisible();
}

CI/CD Configuration

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Create expect instance configured for CI environment
const ciExpect = expect.configure({
  colorize: false, // Disable colors in CI logs
  display: 'inline', // inline output for CI
  timeout: 30000, // Longer timeout for CI environment
});

Development vs Production

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Different configuration based on environment
const isDevelopment = __ENV.NODE_ENV === 'development';

const envExpect = expect.configure({
  timeout: isDevelopment ? 5000 : 15000,
  colorize: isDevelopment,
  display: isDevelopment ? 'pretty' : 'inline',
  softMode: isDevelopment ? 'continue' : 'fail',
});

Multiple Configured Instances

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export default function () {
  // Create specific expect instances for different scenarios
  const fastExpect = expect.configure({
    timeout: 1000,
    interval: 50,
  });

  const slowExpect = expect.configure({
    timeout: 30000,
    softMode: 'continue',
  });

  // Use appropriate instance for each test
  fastExpect(quickOperation()).toBe(true);
  slowExpect(slowOperation()).toBe(true);

  // Original expect instance still available
  expect(normalOperation()).toBe(true);
}

Soft Assertion Examples

import http from 'k6/http';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Create expect instance with soft assertions enabled
const softExpect = expect.configure({
  softMode: 'continue',
});

export default function () {
  const response = http.get('https://test-api.k6.io/public/crocodiles/1/');

  // These assertions will not stop test execution on failure
  softExpect(response.status).toBe(200);
  softExpect(response.json()).toHaveProperty('name');
  softExpect(response.json()).toHaveProperty('age');

  // Test continues even if assertions fail
  console.log('Test completed');
}

Non-Retrying Assertions

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

Non-Retrying Assertions

Non-retrying assertions are synchronous assertions that allow to test any conditions, but do not auto-retry. They are ideal for testing static values, API responses, and any scenario where the expected condition should be true at the moment of evaluation.

Non-retrying assertions differ from retrying assertions in that they:

Evaluate immediately - They check the condition once and return the result
Are synchronous - They don’t need to be awaited and return results immediately
Have no timeout behavior - They either pass or fail instantly
Are ideal for static content - Perfect for testing values that don’t change over time

import http from 'k6/http';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export default function () {
  const response = http.get('https://quickpizza.grafana.com/');

  // Immediate assertions
  expect(response.status).toBe(200);
  expect(response.body).toBeDefined();
  expect(response.body).toBeTruthy();
  expect(typeof response.body).toBe('string');
  expect(response.body).toContain('Pizza');
}

When to Use Non-Retrying Assertions

Non-retrying assertions are best suited for:

API response testing - Checking status codes, response data, headers
Static values - Testing constants, configuration values, or computed results
Data validation - Verifying object properties, array contents, or data types
Known state verification - Checking values that should be immediately available

Non-retrying assertions methods

Equality Assertions

Method	Description
toBe()	Exact equality using Object.is()
toEqual()	Deep equality comparison

Truthiness Assertions

Method	Description
toBeTruthy()	Value is truthy
toBeFalsy()	Value is falsy
toBeDefined()	Value is not undefined
toBeUndefined()	Value is undefined
toBeNull()	Value is null

Comparison Assertions

Method	Description
toBeGreaterThan()	Numeric greater than
toBeGreaterThanOrEqual()	Numeric greater than or equal
toBeLessThan()	Numeric less than
toBeLessThanOrEqual()	Numeric less than or equal
toBeCloseTo()	Floating point comparison

Collection Assertions

Method	Description
toContain()	Array/string contains value
toContainEqual()	Array contains object with matching content
toHaveLength()	Array/string has specific length

Property Assertions

Method	Description
toHaveProperty()	Object has specific property

Type Assertions

Method	Description
toBeInstanceOf()	Value is instance of class

Common Patterns

API Response Validation

export default function () {
  const response = http.get('https://quickpizza.grafana.com/');

  // Response status and headers
  expect(response.status).toBe(200);
  expect(response.headers['content-type']).toContain('text/html');

  // Response data structure
  expect(response.body).toBeDefined();
  expect(response.body).toBeTruthy();
  expect(response.body).toContain('pizza');
  expect(response.body).toContain('Pizza');

  // Data types
  expect(typeof response.body).toBe('string');
  expect(response.body.length).toBeGreaterThan(0);
}

Data Validation

export default function () {
  const userData = {
    name: 'John Doe',
    email: 'john@example.com',
    age: 30,
    hobbies: ['reading', 'gaming'],
    address: {
      city: 'New York',
      country: 'USA',
    },
  };

  // Object structure validation
  expect(userData).toHaveProperty('name');
  expect(userData).toHaveProperty('address.city');
  expect(userData.hobbies).toHaveLength(2);

  // Value validation
  expect(userData.name).toBeDefined();
  expect(userData.email).toContain('@');
  expect(userData.age).toBeGreaterThan(0);
  expect(userData.hobbies).toContain('reading');
}

Configuration Testing

export default function () {
  const config = {
    apiUrl: __ENV.API_URL || 'https://api.example.com',
    timeout: parseInt(__ENV.TIMEOUT || '5000'),
    retries: parseInt(__ENV.RETRIES || '3'),
    features: (__ENV.FEATURES || 'feature1,feature2').split(','),
  };

  // Configuration validation
  expect(config.apiUrl).toContain('http');
  expect(config.timeout).toBeGreaterThan(0);
  expect(config.retries).toBeGreaterThanOrEqual(0);
  expect(config.features).toContain('feature1');
  expect(config.features).toHaveLength(2);
}

Error Handling Patterns

Graceful Error Handling

export default function () {
  const response = http.get('https://quickpizza.grafana.com/');

  // Check response status first
  if (response.status === 200) {
    expect(response.body).toBeDefined();
    expect(response.body).toBeTruthy();
    expect(response.body).toContain('Pizza');
  } else {
    // Handle error response
    expect(response.status).toBeGreaterThanOrEqual(400);
    expect(response.body).toContain('error');
  }
}

Retrying Assertions

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

Retrying Assertions

Retrying assertions are asynchronous assertions that automatically retry until a condition becomes true or a timeout is reached. They are particularly useful for browser testing where elements may not be immediately available or when testing dynamic content that changes over time.

Overview

Retrying assertions differ from non-retrying assertions in that they:

Automatically retry - They continuously check the condition until it passes or times out
Are asynchronous - They return promises and must be await-ed
Have configurable timeouts - You can set custom timeout and polling intervals
Are ideal for dynamic content - Perfect for testing UI elements that appear/disappear or change over time

When to Use Retrying Assertions

Retrying assertions are best suited for:

Browser testing - Checking element visibility, text content, or state changes
Dynamic content - Testing content that loads asynchronously
User interactions - Verifying UI changes after clicks, form submissions, etc.
Loading states - Waiting for spinners to disappear or content to appear
API polling - Waiting for external systems to reach expected states

Usage

All retrying assertions must be awaited since they return promises:

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  }
};

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Wait for element to become visible
  await expect(page.locator('h1')).toBeVisible();

  // Wait for specific text content
  await expect(page.locator('h1')).toHaveText('Looking to break out of your pizza routine?');

  // Wait for element to be enabled
  await expect(page.locator('button[name="pizza-please"]')).toBeEnabled();
}

Configuration

You can configure timeout and polling behavior by creating a configured expect instance or per assertion:

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Create configured expect instance
const slowExpect = expect.configure({
  timeout: 10000, // 10 seconds timeout
  interval: 200, // Check every 200ms
});

export default async function () {
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  // Use configured timeout
  await slowExpect(page.locator('h1')).toBeVisible();

  // Override timeout for specific assertion
  await slowExpect(page.locator('button[name="pizza-please"]')).toBeVisible({
    timeout: 30000,
  });

  // Original expect instance still available with defaults
  await expect(page.locator('h1')).toBeVisible();
}

Available Retrying Assertions

Method	Description
toBeVisible()	Element is visible on the page
toBeHidden()	Element is hidden or not visible
toBeEnabled()	Element is enabled and interactive
toBeDisabled()	Element is disabled
toBeChecked()	Checkbox or radio button is checked
toBeEditable()	Element is editable
toBeEmpty()	Element is empty
toHaveText()	Element has specific text content
toContainText()	Element contains specific text
toHaveValue()	Input element has specific value
toHaveAttribute()	Element has specific attribute value
toHaveTitle()	Page has specific title