testing
The k6 testing library provides assertion capabilities for both protocol and browser testing, and draws inspiration from Playwright’s test API design. The entire library is centered around the
expect() function, which can be configured for convenience.
Note
The k6 testing library source code is available on GitHub.
Features
- Playwright-inspired assertions: API designed with patterns inspired by Playwright’s testing approach
- Protocol and browser testing: Works with both HTTP/API testing and browser automation
- Auto-retrying assertions: Automatically retry assertions until they pass or timeout
- Soft assertions: Continue test execution even after assertion failures
- Configurable timeouts: Customizable timeout and polling intervals
Usage
To use the testing library in your k6 script, import it in your tests directly from the jslib repository:
import { expect } from 'https://jslib.k6.io/k6-testing/0.5.0/index.js';Demo
Protocol Testing
import { check } from 'k6';
import http from 'k6/http';
import { expect } from 'https://jslib.k6.io/k6-testing/0.5.0/index.js';
export default function () {
const response = http.get('https://test-api.k6.io/public/crocodiles/1/');
// Traditional k6 check
check(response, {
'status is 200': (r) => r.status === 200,
});
// Using expect assertions
expect(response.status).toBe(200);
expect(response.json()).toHaveProperty('name');
}Browser Testing
import { browser } from 'k6/experimental/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.5.0/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');
}Configuration
Create configured expect instances for custom behavior:
import { expect } from 'https://jslib.k6.io/k6-testing/0.5.0/index.js';
// Create configured expect instance
const myExpect = expect.configure({
timeout: 10000, // Default timeout for retrying assertions
interval: 200, // Polling interval for retrying assertions
colorize: true, // Enable colored output
display: 'pretty', // Output format
softMode: 'fail' // Soft assertion behavior
});Assertion types
The testing library provides two types of assertions:
Non-Retrying Assertions
Synchronous assertions that evaluate immediately. These are ideal for testing static values, API responses, and scenarios where the expected condition should be true at the moment of evaluation.
Retrying Assertions
Asynchronous assertions that automatically retry until conditions become true or timeout. These are suitable for browser testing, dynamic content, and scenarios where conditions may change over time.
API Reference
| Function | Description |
|---|---|
| expect() | Main assertion function |
| expect.configure() | Create configured expect instances |
| Non-Retrying Assertions | Synchronous assertions for immediate evaluation |
| Retrying Assertions | Asynchronous assertions for dynamic content |