Skip to content

Commit 91077b2

Browse files
oleiadeankur22
oleiade
authored and
ankur22
committed
feat: document testing jslib
1 parent 20c726b commit 91077b2

36 files changed

+2802
-0
lines changed

‎docs/sources/k6/_index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ cascade:
2222
JSLIB_AWS_VERSION: 0.14.0
2323
JSLIB_PYROSCOPE_VERSION: 1.0.2
2424
JSLIB_TEMPO_VERSION: 1.0.1
25+
JSLIB_TESTING_VERSION: 0.5.0
2526
versioned: true
2627
versioned_next: true
2728
---

‎docs/sources/k6/next/javascript-api/jslib/testing/_index.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: 'testing'
3+
head_title: 'testing'
4+
description: 'k6 testing library for advanced assertions and Playwright-compatible testing'
5+
weight: 00
6+
---
7+
8+
# testing
9+
10+
The k6 testing library provides assertion capabilities for both protocol and browser testing, and aims for compatibility with Playwright's test API. The entire library is centered around the [`expect()`]({{< relref "./expect" >}}) function, which can be configured for convenience.
11+
12+
{{< admonition type="note" >}}
13+
The k6 testing library source code can be found on [GitHub](https://github.com/grafana/k6-jslib-testing).
14+
{{< /admonition >}}
15+
16+
## Features
17+
18+
- **Playwright-compatible assertions**: API designed for familiarity with Playwright's testing patterns
19+
- **[Protocol and browser testing](#demo)**: Works with both HTTP/API testing and browser automation
20+
- **[Auto-retrying assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/k6-testing/expect#retrying-assertions)**: Automatically retry assertions until they pass or timeout
21+
- **[Soft assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/k6-testing/expect#soft-assertions)**: Continue test execution even after assertion failures
22+
- **[Configurable timeouts](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/k6-testing/configure)**: Customizable timeout and polling intervals
23+
24+
## Usage
25+
26+
To use the testing library in your k6 script, import it in your tests, directly from the jslib repository:
27+
28+
```javascript
29+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
30+
```
31+
32+
## Demo
33+
34+
### Protocol Testing
35+
36+
```javascript
37+
import { check } from 'k6';
38+
import http from 'k6/http';
39+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
40+
41+
export default function () {
42+
const response = http.get('https://test-api.k6.io/public/crocodiles/1/');
43+
44+
// Traditional k6 check
45+
check(response, {
46+
'status is 200': (r) => r.status === 200,
47+
});
48+
49+
// Using expect assertions
50+
expect(response.status).toBe(200);
51+
expect(response.json()).toHaveProperty('name');
52+
}
53+
```
54+
55+
### Browser Testing
56+
57+
```javascript
58+
import { browser } from 'k6/experimental/browser';
59+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
60+
61+
export default async function () {
62+
const page = browser.newPage();
63+
64+
await page.goto('https://test.k6.io');
65+
66+
// Auto-retrying assertions
67+
await expect(page.locator('h1')).toBeVisible();
68+
await expect(page.locator('h1')).toHaveText('Welcome to the k6 test site');
69+
}
70+
```
71+
72+
## Configuration
73+
74+
Create configured expect instances for custom behavior:
75+
76+
```javascript
77+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
78+
79+
// Create configured expect instance
80+
const myExpect = expect.configure({
81+
timeout: 10000, // Default timeout for retrying assertions
82+
interval: 200, // Polling interval for retrying assertions
83+
colorize: true, // Enable colored output
84+
display: 'pretty', // Output format
85+
softMode: 'fail' // Soft assertion behavior
86+
});
87+
```
88+
89+
## Assertion Types
90+
91+
The testing library provides two types of assertions:
92+
93+
### [Non-Retrying Assertions]({{< relref "./non-retrying-assertions" >}})
94+
Synchronous assertions that evaluate immediately - perfect for testing static values, API responses, and any scenario where the expected condition should be true at the moment of evaluation.
95+
96+
### [Retrying Assertions]({{< relref "./retrying-assertions" >}})
97+
Asynchronous assertions that automatically retry until conditions become true or timeout - ideal for browser testing, dynamic content, and any scenario where conditions may change over time.
98+
99+
## API Reference
100+
101+
| Function | Description |
102+
| --- | --- |
103+
| [expect()]({{< relref "./expect" >}}) | Main assertion function |
104+
| [expect.configure()]({{< relref "./configure" >}}) | Create configured expect instances |
105+
| [Non-Retrying Assertions]({{< relref "./non-retrying-assertions" >}}) | Synchronous assertions for immediate evaluation |
106+
| [Retrying Assertions]({{< relref "./retrying-assertions" >}}) | Asynchronous assertions for dynamic content |

‎docs/sources/k6/next/javascript-api/jslib/testing/configure.md

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
---
2+
title: 'expect.configure()'
3+
head_title: 'expect.configure(options)'
4+
description: 'Configure global assertion behavior for the k6 testing library'
5+
weight: 20
6+
---
7+
8+
# expect.configure()
9+
10+
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. The original expect instance remains unchanged.
11+
12+
## Syntax
13+
14+
```javascript
15+
const configuredExpect = expect.configure(options)
16+
```
17+
18+
## Parameters
19+
20+
| Parameter | Type | Description |
21+
| --- | --- | --- |
22+
| options | object | Configuration options object |
23+
24+
### Options
25+
26+
| Property | Type | Default | Description |
27+
| --- | --- | --- | --- |
28+
| timeout | number | `5000` | Default timeout in milliseconds for retrying assertions |
29+
| interval | number | `100` | Polling interval in milliseconds for retrying assertions |
30+
| colorize | boolean | `true` | Enable colored output in assertion messages |
31+
| display | string | `"pretty"` | Output format for assertion messages (`"pretty"` or `"inline"`) |
32+
| softMode | string | `"fail"` | Soft assertion behavior (`"fail"` or `"throw"`) |
33+
34+
## Returns
35+
36+
| Type | Description |
37+
| --- | --- |
38+
| Expect | A new expect instance with the specified configuration |
39+
40+
## Description
41+
42+
The `expect.configure()` method creates a new expect instance with custom configuration options. 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 original expect instance remains unchanged and continues to use the default configuration.
43+
44+
### Timeout Configuration
45+
46+
The `timeout` option controls how long retrying assertions will wait for a condition to become true:
47+
48+
```javascript
49+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
50+
51+
// Create a configured expect instance with longer timeout for slow-loading elements
52+
const slowExpect = expect.configure({
53+
timeout: 10000, // 10 seconds
54+
interval: 500, // Check every 500ms
55+
});
56+
```
57+
58+
### Display Options
59+
60+
The `display` and `colorize` options control how assertion failures are reported:
61+
62+
```javascript
63+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
64+
65+
// Create expect instance with inline output and no colors
66+
const inlineExpect = expect.configure({
67+
display: 'inline',
68+
colorize: false,
69+
});
70+
```
71+
72+
### Soft Assertion Mode
73+
74+
The `softMode` option controls whether failed assertions stop test execution:
75+
76+
```javascript
77+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
78+
79+
// The default behavior of soft assertions is mark the test as failed, the `softMode` option
80+
// allows to configure soft assertions to throw an exception and fail the current iteration instead.
81+
const softExpect = expect.configure({
82+
softMode: 'throw',
83+
});
84+
```
85+
86+
## Environment Variables
87+
88+
Configuration options can also be set using environment variables:
89+
90+
| Environment Variable | Option | Description |
91+
| --- | --- | --- |
92+
| `K6_TESTING_TIMEOUT` | `timeout` | Default timeout in milliseconds |
93+
| `K6_TESTING_INTERVAL` | `interval` | Polling interval in milliseconds |
94+
| `K6_TESTING_COLORIZE` | `colorize` | Enable colored output (`true`/`false`) |
95+
| `K6_TESTING_DISPLAY` | `display` | Output format (`pretty`/`inline`) |
96+
| `K6_TESTING_SOFT_MODE` | `softMode` | Soft assertion mode (`fail`/`throw`) |
97+
98+
```bash
99+
# Set environment variables
100+
export K6_TESTING_TIMEOUT=10000
101+
export K6_TESTING_SOFT_MODE=throw
102+
k6 run test.js
103+
```
104+
105+
## Examples
106+
107+
### Basic Configuration
108+
109+
```javascript
110+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
111+
112+
// Create a configured expect instance
113+
const myExpect = expect.configure({
114+
timeout: 8000,
115+
interval: 200,
116+
colorize: true,
117+
display: 'pretty'
118+
});
119+
120+
export default function () {
121+
// Use the configured instance
122+
myExpect(response.status).toBe(200);
123+
124+
// Original expect instance still works with defaults
125+
expect(response.status).toBe(200);
126+
}
127+
```
128+
129+
### Browser Testing Configuration
130+
131+
```javascript
132+
import { browser } from 'k6/experimental/browser';
133+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
134+
135+
// Create expect instance configured for browser testing with longer timeouts
136+
const browserExpect = expect.configure({
137+
timeout: 15000, // Longer timeout for browser operations
138+
interval: 500, // Less frequent polling
139+
});
140+
141+
export default async function () {
142+
const page = browser.newPage();
143+
await page.goto('https://test.k6.io');
144+
145+
// Will wait up to 15 seconds for element to be visible
146+
await browserExpect(page.locator('h1')).toBeVisible();
147+
}
148+
```
149+
150+
### CI/CD Configuration
151+
152+
```javascript
153+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
154+
155+
// Create expect instance configured for CI environment
156+
const ciExpect = expect.configure({
157+
colorize: false, // Disable colors in CI logs
158+
display: 'inline', // inline output for CI
159+
timeout: 30000, // Longer timeout for CI environment
160+
});
161+
```
162+
163+
### Development vs Production
164+
165+
```javascript
166+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
167+
168+
// Different configuration based on environment
169+
const isDevelopment = __ENV.NODE_ENV === 'development';
170+
171+
const envExpect = expect.configure({
172+
timeout: isDevelopment ? 5000 : 15000,
173+
colorize: isDevelopment,
174+
display: isDevelopment ? 'pretty' : 'inline',
175+
softMode: isDevelopment ? 'continue' : 'fail',
176+
});
177+
```
178+
179+
### Multiple Configured Instances
180+
181+
```javascript
182+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
183+
184+
export default function () {
185+
// Create specific expect instances for different scenarios
186+
const fastExpect = expect.configure({
187+
timeout: 1000,
188+
interval: 50,
189+
});
190+
191+
const slowExpect = expect.configure({
192+
timeout: 30000,
193+
softMode: 'continue',
194+
});
195+
196+
// Use appropriate instance for each test
197+
fastExpect(quickOperation()).toBe(true);
198+
slowExpect(slowOperation()).toBe(true);
199+
200+
// Original expect instance still available
201+
expect(normalOperation()).toBe(true);
202+
}
203+
```
204+
205+
### Soft Assertion Examples
206+
207+
```javascript
208+
import http from 'k6/http';
209+
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_AWS_VERSION" >}}/index.js';
210+
211+
// Create expect instance with soft assertions enabled
212+
const softExpect = expect.configure({
213+
softMode: 'continue',
214+
});
215+
216+
export default function () {
217+
const response = http.get('https://test-api.k6.io/public/crocodiles/1/');
218+
219+
// These assertions will not stop test execution on failure
220+
softExpect(response.status).toBe(200);
221+
softExpect(response.json()).toHaveProperty('name');
222+
softExpect(response.json()).toHaveProperty('age');
223+
224+
// Test continues even if assertions fail
225+
console.log('Test completed');
226+
}
227+
```
228+
229+
## See Also
230+
231+
- [expect()]({{< relref "./expect" >}}) - Main assertion function
232+
- [Environment Variables]({{< relref "../../../using-k6/environment-variables" >}}) - k6 environment variable usage

0 commit comments

Comments
 (0)