Skip to content

Commit fe7d3d9

Browse files
AgnesTouletAgnesToulet
committed
Merge branch 'main' into add/getBy-and-frameLocator
2 parents 5006ef1 + 628e64b commit fe7d3d9

File tree

44 files changed

+691
-166
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+691
-166
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/next/javascript-api/k6-browser/_index.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,9 @@ weight: 02
88

99
# browser
1010

11-
The browser module APIs aim for rough compatibility with the [Playwright API for NodeJS](https://playwright.dev/docs/api/class-playwright).
11+
The browser module APIs are inspired by Playwright and other frontend testing frameworks.
1212

13-
Note that because k6 does not run in NodeJS, the browser module APIs will slightly differ from their Playwright counterparts.
14-
15-
You can find examples of using [the browser module API](#browser-module-api) in our [getting started guide](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser).
13+
You can find examples of using [the browser module API](#browser-module-api) in the [getting started guide](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser).
1614

1715
{{< admonition type="note" >}}
1816

‎docs/sources/k6/next/javascript-api/k6-browser/console-message.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
title: 'ConsoleMessage'
3-
slug: 'consolemessage'
43
description: 'Browser module: ConsoleMessage Class'
54
weight: 03
65
---
@@ -11,9 +10,9 @@ weight: 03
1110

1211
## Supported APIs
1312

14-
| Method | Playwright Relevant Distinctions |
15-
| --------------------------------------------------------------------------------------------------------------- | -------------------------------- |
16-
| <a href="https://playwright.dev/docs/api/class-consolemessage#console-message-args" target="_blank" >args()</a> | - |
17-
| <a href="https://playwright.dev/docs/api/class-consolemessage#console-message-page" target="_blank" >page()</a> | - |
18-
| <a href="https://playwright.dev/docs/api/class-consolemessage#console-message-text" target="_blank" >text()</a> | - |
19-
| <a href="https://playwright.dev/docs/api/class-consolemessage#console-message-type" target="_blank" >type()</a> | - |
13+
| Method | Description |
14+
| ------ | ---------------------------------------------------------------- |
15+
| args() | List of arguments passed to a `console` function call. |
16+
| page() | The page that produced this console message. |
17+
| text() | The text of the console message. |
18+
| type() | The type of the console message. For example: `log`, or `debug`. |

‎docs/sources/k6/next/javascript-api/k6-browser/frame/locator.md‎

Lines changed: 53 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,65 @@
11
---
2-
title: 'locator(selector)'
3-
description: 'Browser module: frame.locator(selector) method'
2+
title: 'locator(selector[, options])'
3+
description: 'Browser module: frame.locator(selector[, options]) method'
44
---
55

6-
# locator(selector)
6+
# locator(selector[, options])
77

88
The method returns an element [Locator](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/). Locators resolve to the element when the action takes place, which means locators can span over navigations where the underlying dom changes.
99

10-
| Parameter | Type | Default | Description |
11-
| --------- | ------ | ------- | --------------------------------------------- |
12-
| selector | string | `''` | A selector to use when resolving DOM element. |
10+
<TableWithNestedRows>
11+
12+
| Parameter | Type | Default | Description |
13+
| ------------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14+
| selector | string | `''` | A selector to use when resolving a DOM element. |
15+
| options | object | `null` | |
16+
| options.hasText | string or RegExp | `null` | Matches only elements that contain the specified text. String or regular expression. Optional. |
17+
| options.hasNotText | string or RegExp | `null` | Matches only elements that do not contain the specified text. String or regular expression. Optional. |
18+
19+
</TableWithNestedRows>
1320

1421
### Returns
1522

1623
| Type | Description |
1724
| -------------------------------------------------------------------------------------- | ------------------------------------------------ |
1825
| [Locator](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/) | The element `Locator` associated with the frame. |
26+
27+
### Example
28+
29+
{{< code >}}
30+
31+
```javascript
32+
import { browser } from 'k6/browser';
33+
34+
export const options = {
35+
scenarios: {
36+
ui: {
37+
executor: 'shared-iterations',
38+
options: {
39+
browser: {
40+
type: 'chromium',
41+
},
42+
},
43+
},
44+
},
45+
};
46+
47+
export default async function () {
48+
const page = await browser.newPage();
49+
50+
try {
51+
await page.goto('https://quickpizza.grafana.com');
52+
53+
// Get the mainframe of the page
54+
const frame = page.mainFrame();
55+
56+
// Create a locator with text filtering options
57+
const submitButton = frame.locator('button', { hasText: 'Pizza, Please!' });
58+
await submitButton.click();
59+
} finally {
60+
await page.close();
61+
}
62+
}
63+
```
64+
65+
{{< /code >}}

‎docs/sources/k6/next/javascript-api/k6-browser/framelocator/_index.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
---
2-
title: 'FrameLocator'
3-
description: 'Browser module: FrameLocator Class'
4-
weight: 10
2+
title: "FrameLocator"
3+
description: "Browser module: FrameLocator Class"
4+
weight: 09
55
---
66

77
# FrameLocator
88

9-
FrameLocator represents a view to an `iframe` on the page. It captures the logic sufficient to retrieve the `iframe` and locate elements in that `iframe`. FrameLocator can be created with `locator.contentFrame()` method.
9+
FrameLocator represents a way to find element(s) in an `iframe`. Frames can be nested, and this locator supports selecting a frame element and then working with it.
10+
11+
A FrameLocator can be created with the `locator.contentFrame()` method.
1012

1113
| Method | Description |
1214
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -17,4 +19,4 @@ FrameLocator represents a view to an `iframe` on the page. It captures the logic
1719
| [getByTestId(testId)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/framelocator/getbytestid/) | Returns a locator for elements with the specified `data-testid` attribute. |
1820
| [getByText(text[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/framelocator/getbytext/) | Returns a locator for elements containing the specified text. |
1921
| [getByTitle(title[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/framelocator/getbytitle/) | Returns a locator for elements with the specified `title` attribute. |
20-
| [locator(selector)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/framelocator/locator) | Returns a [Locator](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator) for the given `selector`. |
22+
| [locator(selector[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/framelocator/locator) | Returns a new chained `locator` for the given `selector` within the frame. |

0 commit comments

Comments
 (0)