Skip to content

Commit 8bbc3b3

Browse files
DarleiCDarleiC
authored
Update k6 testing documentation and examples (#2056)
* feat(tests): update k6 testing documentation and examples * set param version in examples * set hash last commit writers-toolkit * fix(workflows): revert writers-toolkit version to v1 for consistency * fix(workflows): update writers-toolkit version to v1 for consistency
1 parent 034463c commit 8bbc3b3

File tree

3 files changed

+83
-66
lines changed

3 files changed

+83
-66
lines changed

‎docs/sources/k6/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ cascade:
2323
JSLIB_PYROSCOPE_VERSION: 1.0.2
2424
JSLIB_TEMPO_VERSION: 1.0.1
2525
JSLIB_TESTING_VERSION: 0.5.0
26+
JSLIB_UTILS_VERSION: 1.4.0
2627
versioned: true
2728
versioned_next: true
2829
---

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

Lines changed: 42 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,21 @@
11
---
2-
title: 'testing'
2+
title: 'k6-testing'
33
description: 'The k6 testing library provides test assertion capabilities for both protocol and browser testing.'
44
weight: 00
55
---
66

7-
# testing
7+
# k6-testing
88

9-
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()`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect) function, which can be configured for convenience.
9+
The k6 testing library provides assertion capabilities for both protocol and browser testing, and draws inspiration from _Playwright_'s test API design.
10+
The entire library is centered around the [`expect()`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect) function, which can be configured for convenience.
1011

1112
{{< admonition type="note" >}}
1213
The k6 testing library source code is available on [GitHub](https://github.com/grafana/k6-jslib-testing).
1314
{{< /admonition >}}
1415

1516
## Features
1617

17-
- **Playwright-inspired assertions**: API designed with patterns inspired by Playwright's testing approach
18+
- **[Playwright-inspired assertions](https://playwright.dev/docs/test-assertions)**: API designed with patterns inspired by Playwright's testing approach
1819
- **[Protocol and browser testing](#demo)**: Works with both HTTP/API testing and browser automation
1920
- **[Auto-retrying assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect#retrying-assertions)**: Automatically retry assertions until they pass or timeout
2021
- **[Soft assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect#soft-assertions)**: Continue test execution even after assertion failures
@@ -38,20 +39,27 @@ import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_TESTING_
3839

3940
```javascript
4041
import { check } from 'k6';
41-
import http from 'k6/http';
4242
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_TESTING_VERSION" >}}/index.js';
43+
import { randomString } from 'https://jslib.k6.io/k6-utils/{{< param "JSLIB_UTILS_VERSION" >}}/index.js';
44+
import http from 'k6/http';
4345

4446
export default function () {
45-
const response = http.get('https://test-api.k6.io/public/crocodiles/1/');
46-
47-
// Traditional k6 check
47+
const payload = JSON.stringify({
48+
username: `${randomString(5)}[email protected]`,
49+
password: 'secret',
50+
});
51+
const response = http.post(`https://quickpizza.grafana.com/api/users`, payload); // create user
52+
53+
console.info(response.json());
54+
55+
//Traditional k6 check
4856
check(response, {
49-
'status is 200': (r) => r.status === 200,
57+
'status is 201': (r) => r.status === 201,
5058
});
51-
52-
// Using expect assertions
53-
expect(response.status).toBe(200);
54-
expect(response.json()).toHaveProperty('name');
59+
60+
//Using expect assertions
61+
expect(response.status).toBe(201);
62+
expect(response.json()).toHaveProperty('id');
5563
}
5664
```
5765

@@ -60,7 +68,7 @@ export default function () {
6068
<!-- md-k6:skip -->
6169

6270
```javascript
63-
import { browser } from 'k6/experimental/browser';
71+
import { browser } from 'k6/browser';
6472
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_TESTING_VERSION" >}}/index.js';
6573

6674
export const options = {
@@ -73,23 +81,23 @@ export const options = {
7381
},
7482
},
7583
},
76-
}
84+
},
7785
};
7886

7987
export default async function () {
80-
const page = browser.newPage();
81-
82-
await page.goto('https://test.k6.io');
83-
84-
// Auto-retrying assertions
88+
const page = await browser.newPage();
89+
90+
await page.goto('https://quickpizza.grafana.com');
91+
92+
// Retrying Assertions
8593
await expect(page.locator('h1')).toBeVisible();
86-
await expect(page.locator('h1')).toHaveText('Welcome to the k6 test site');
94+
await expect(page.locator('h1')).toHaveText('Looking to break out of your pizza routine?');
8795
}
8896
```
8997

9098
## Configuration
9199

92-
Create configured `expect` instances for custom behavior:
100+
Create configured [`expect.configure()`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/configure) instances for custom behavior:
93101

94102
<!-- md-k6:skip -->
95103

@@ -98,31 +106,31 @@ import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_TESTING_
98106

99107
// Create configured expect instance
100108
const myExpect = expect.configure({
101-
timeout: 10000, // Default timeout for retrying assertions
102-
interval: 200, // Polling interval for retrying assertions
103-
colorize: true, // Enable colored output
104-
display: 'pretty', // Output format
105-
softMode: 'fail' // Soft assertion behavior
109+
timeout: 10000, // Default timeout for retrying assertions
110+
interval: 200, // Polling interval for retrying assertions
111+
colorize: true, // Enable colored output
112+
display: 'pretty', // Output format
113+
softMode: 'fail', // Soft assertion behavior
106114
});
107115
```
108116

109117
## Assertion types
110118

111119
The testing library provides two types of assertions:
112120

113-
### [Non-Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect/non-retrying-assertions/)
121+
### [Non-Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/non-retrying-assertions/)
114122

115123
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.
116124

117-
### [Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect/retrying-assertions/)
125+
### [Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/retrying-assertions/)
118126

119127
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.
120128

121129
## API Reference
122130

123-
| Function | Description |
124-
| --- | --- |
125-
| [expect()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect) | Main assertion function |
126-
| [expect.configure()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/configure) | Create configured expect instances |
131+
| Function | Description |
132+
| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
133+
| [expect()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect) | Main assertion function |
134+
| [expect.configure()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/configure) | Create configured expect instances |
127135
| [Non-Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/non-retrying-assertions) | Synchronous assertions for immediate evaluation |
128-
| [Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/retrying-assertions) | Asynchronous assertions for dynamic content |
136+
| [Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/retrying-assertions) | Asynchronous assertions for dynamic content |

‎docs/sources/k6/v1.2.x/javascript-api/jslib/testing/_index.md‎

Lines changed: 40 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,21 @@
11
---
2-
title: 'testing'
2+
title: 'k6-testing'
33
description: 'The k6 testing library provides test assertion capabilities for both protocol and browser testing.'
44
weight: 00
55
---
66

7-
# testing
7+
# k6-testing
88

9-
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()`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect) function, which can be configured for convenience.
9+
The k6 testing library provides assertion capabilities for both protocol and browser testing, and draws inspiration from _Playwright_'s test API design.
10+
The entire library is centered around the [`expect()`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect) function, which can be configured for convenience.
1011

1112
{{< admonition type="note" >}}
1213
The k6 testing library source code is available on [GitHub](https://github.com/grafana/k6-jslib-testing).
1314
{{< /admonition >}}
1415

1516
## Features
1617

17-
- **Playwright-inspired assertions**: API designed with patterns inspired by Playwright's testing approach
18+
- **[Playwright-inspired assertions](https://playwright.dev/docs/test-assertions)**: API designed with patterns inspired by Playwright's testing approach
1819
- **[Protocol and browser testing](#demo)**: Works with both HTTP/API testing and browser automation
1920
- **[Auto-retrying assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect#retrying-assertions)**: Automatically retry assertions until they pass or timeout
2021
- **[Soft assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect#soft-assertions)**: Continue test execution even after assertion failures
@@ -38,20 +39,27 @@ import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_TESTING_
3839

3940
```javascript
4041
import { check } from 'k6';
41-
import http from 'k6/http';
4242
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_TESTING_VERSION" >}}/index.js';
43+
import { randomString } from 'https://jslib.k6.io/k6-utils/{{< param "JSLIB_UTILS_VERSION" >}}/index.js';
44+
import http from 'k6/http';
4345

4446
export default function () {
45-
const response = http.get('https://test-api.k6.io/public/crocodiles/1/');
46-
47-
// Traditional k6 check
47+
const payload = JSON.stringify({
48+
username: `${randomString(5)}[email protected]`,
49+
password: 'secret',
50+
});
51+
const response = http.post(`https://quickpizza.grafana.com/api/users`, payload); // create user
52+
53+
console.info(response.json());
54+
55+
//Traditional k6 check
4856
check(response, {
49-
'status is 200': (r) => r.status === 200,
57+
'status is 201': (r) => r.status === 201,
5058
});
51-
52-
// Using expect assertions
53-
expect(response.status).toBe(200);
54-
expect(response.json()).toHaveProperty('name');
59+
60+
//Using expect assertions
61+
expect(response.status).toBe(201);
62+
expect(response.json()).toHaveProperty('id');
5563
}
5664
```
5765

@@ -60,7 +68,7 @@ export default function () {
6068
<!-- md-k6:skip -->
6169

6270
```javascript
63-
import { browser } from 'k6/experimental/browser';
71+
import { browser } from 'k6/browser';
6472
import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_TESTING_VERSION" >}}/index.js';
6573

6674
export const options = {
@@ -73,23 +81,23 @@ export const options = {
7381
},
7482
},
7583
},
76-
}
84+
},
7785
};
7886

7987
export default async function () {
80-
const page = browser.newPage();
81-
82-
await page.goto('https://test.k6.io');
83-
84-
// Auto-retrying assertions
88+
const page = await browser.newPage();
89+
90+
await page.goto('https://quickpizza.grafana.com');
91+
92+
// Retrying Assertions
8593
await expect(page.locator('h1')).toBeVisible();
86-
await expect(page.locator('h1')).toHaveText('Welcome to the k6 test site');
94+
await expect(page.locator('h1')).toHaveText('Looking to break out of your pizza routine?');
8795
}
8896
```
8997

9098
## Configuration
9199

92-
Create configured `expect` instances for custom behavior:
100+
Create configured [`expect.configure()`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/configure) instances for custom behavior:
93101

94102
<!-- md-k6:skip -->
95103

@@ -98,11 +106,11 @@ import { expect } from 'https://jslib.k6.io/k6-testing/{{< param "JSLIB_TESTING_
98106

99107
// Create configured expect instance
100108
const myExpect = expect.configure({
101-
timeout: 10000, // Default timeout for retrying assertions
102-
interval: 200, // Polling interval for retrying assertions
103-
colorize: true, // Enable colored output
104-
display: 'pretty', // Output format
105-
softMode: 'fail' // Soft assertion behavior
109+
timeout: 10000, // Default timeout for retrying assertions
110+
interval: 200, // Polling interval for retrying assertions
111+
colorize: true, // Enable colored output
112+
display: 'pretty', // Output format
113+
softMode: 'fail', // Soft assertion behavior
106114
});
107115
```
108116

@@ -120,9 +128,9 @@ Asynchronous assertions that automatically retry until conditions become true or
120128

121129
## API Reference
122130

123-
| Function | Description |
124-
| --- | --- |
125-
| [expect()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect) | Main assertion function |
126-
| [expect.configure()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/configure) | Create configured expect instances |
131+
| Function | Description |
132+
| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
133+
| [expect()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/expect) | Main assertion function |
134+
| [expect.configure()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/configure) | Create configured expect instances |
127135
| [Non-Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/non-retrying-assertions) | Synchronous assertions for immediate evaluation |
128-
| [Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/retrying-assertions) | Asynchronous assertions for dynamic content |
136+
| [Retrying Assertions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/testing/retrying-assertions) | Asynchronous assertions for dynamic content |

0 commit comments

Comments
 (0)