Skip to content

Commit 197585d

Browse files
ankur22ankur22
committed
Add v1.4.x release documentation
1 parent 0ef876e commit 197585d

File tree

984 files changed

+77483
-0
lines changed

Some content is hidden

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

984 files changed

+77483
-0
lines changed

‎docs/sources/k6/next/release-notes/v1.4.0.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: Version 1.4.0 release notes
3+
menuTitle: v1.4.0
4+
description: The release notes for Grafana k6 version 1.4.0
5+
weight: 9985
6+
---
7+
8+
# Version 1.4.0 release notes
9+
10+
<!-- md-k6:skipall -->
11+
12+
k6 `v1.4.0` is here 🎉! This release includes:
13+
14+
- OpenTelemetry output graduated from experimental to stable status.
15+
- Changes in the Browser module:
16+
- `page.waitForRequest` for waiting on specific HTTP requests.
17+
- `QueryAll` methods now return elements in DOM order.
18+
- `locator.evaluate` and `locator.evaluateHandle` for executing JavaScript code in the page context with access to the matching element.
19+
- `page.unroute(url)` and `page.unrouteAll` for removing routes registered with `page.route`.
20+
21+
## Breaking changes
22+
23+
As per our [stability guarantees](https://grafana.com/docs/k6/latest/reference/versioning-and-stability-guarantees/), breaking changes across minor releases are allowed only for experimental features.
24+
25+
### Breaking changes for experimental modules
26+
27+
- [#5164](https://github.com/grafana/k6/pull/5164) OpenTelemetry output now exports rate metrics as a single counter with `zero`/`nonzero` labels instead of separate metrics.
28+
- [#5333](https://github.com/grafana/k6/pull/5333) OpenTelemetry output configuration: `K6_OTEL_EXPORTER_TYPE` is deprecated in favor of `K6_OTEL_EXPORTER_PROTOCOL` to align with OpenTelemetry standards.
29+
30+
### Breaking changes for undefined behaviours
31+
- [#5320](https://github.com/grafana/k6/pull/5320), [#5239](https://github.com/grafana/k6/pull/5239), [#5342](https://github.com/grafana/k6/pull/5342) Automatic extension resolution now only inspects ES module `import` statements and no longer supports CommonJS `require()` calls. CommonJS `require()` calls are dynamic, and it is not possible to know for certain if they will be called, or if they will be called with static strings - the only way they were even previously loaded. This functionality was a quirk of the previous implementation and had numerous problems. Additionally, `use k6` directives are now only recognized when they appear at the beginning of files (after optional shebang and whitespace/comments). This was the original intention, but due to implementation bugs, it did not accurately reflect what was happening.
32+
33+
## New features
34+
35+
### OpenTelemetry output graduation [#5334](https://github.com/grafana/k6/pull/5334)
36+
37+
The OpenTelemetry output has graduated from experimental status and is now available as a stable output using the name `opentelemetry`. This change makes OpenTelemetry the recommended vendor-agnostic solution for exporting k6 telemetry data.
38+
39+
You can now use the stable output name in your k6 commands:
40+
41+
```bash
42+
# Previous experimental usage (still supported for backward compatibility)
43+
k6 run --out experimental-opentelemetry script.js
44+
45+
# New stable usage
46+
k6 run --out opentelemetry script.js
47+
```
48+
49+
The `experimental-opentelemetry` name will continue to work for backward compatibility for now but it's deprecated and we might remove it in future versions. We recommend migrating to use the new `opentelemetry` name.
50+
51+
### `page.waitForRequest` [#5330](https://github.com/grafana/k6/pull/5330)
52+
53+
The browser module now supports [`page.waitForRequest()`](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/page/waitforrequest/), which allows you to wait for HTTP requests that match specific URL patterns during browser automation. This method is particularly valuable for testing scenarios where you need to ensure specific network requests are initiated before proceeding with test actions.
54+
55+
The method supports multiple URL pattern matching strategies:
56+
57+
```javascript
58+
// Wait for exact URL match
59+
const requestPromise = page.waitForRequest('https://api.example.com/data');
60+
await page.click('button[data-testid="load-data"]');
61+
const request = await requestPromise;
62+
63+
// Wait for regex pattern match
64+
await page.waitForRequest(/\/api\/.*\.json$/);
65+
66+
// Use with Promise.all for coordinated actions
67+
await Promise.all([
68+
page.waitForRequest('https://api.example.com/user-data'),
69+
page.click('button[data-testid="load-user-data"]')
70+
]);
71+
```
72+
73+
This complements the existing [`page.waitForResponse()`](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/page/waitforresponse/) method by focusing on HTTP requests rather than responses, providing more granular control over network-dependent test scenarios.
74+
75+
### `page.unroute(url)` and `page.unrouteAll()` [#5223](https://github.com/grafana/k6/pull/5223)
76+
77+
The browser module now supports [`page.unroute(url)`](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/page/unroute/) and [`page.unrouteAll()`](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/page/unrouteall/), allowing you to remove routes previously registered with `page.route`.
78+
79+
Example usage:
80+
```javascript
81+
await page.route(/.*\/api\/pizza/, function (route) {
82+
console.log('Modifying request to /api/pizza');
83+
route.continue({
84+
postData: JSON.stringify({
85+
customName: 'My Pizza',
86+
}),
87+
});
88+
});
89+
...
90+
91+
await page.unroute(/.*\/api\/pizza/); // The URL needs to be exactly the same as the one used in the call to the `route` function
92+
```
93+
94+
```javascript
95+
await page.route(/.*\/api\/pizza/, function (route) {
96+
console.log('Modifying request to /api/pizza');
97+
route.continue({
98+
postData: JSON.stringify({
99+
customName: 'My Pizza',
100+
}),
101+
});
102+
});
103+
...
104+
105+
await page.unrouteAll();
106+
```
107+
108+
### `locator.evaluate` and `locator.evaluateHandle` [#5306](https://github.com/grafana/k6/pull/5306)
109+
110+
The browser module now supports [`locator.evaluate`](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/locator/evaluate/) and [`locator.evaluateHandle`](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/locator/evaluatehandle/), allowing you to execute JavaScript code in the page context with access to the matching element. The only difference between `evaluate` and `evaluateHandle` is that `evaluateHandle` returns a [JSHandle](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/jshandle/).
111+
112+
Example usage:
113+
```javascript
114+
await check(page, {
115+
'calling evaluate': async p => {
116+
const n = await p.locator('#pizza-name').evaluate(pizzaName => pizzaName.textContent);
117+
return n == 'Our recommendation:';
118+
}
119+
});
120+
121+
await check(page, {
122+
'calling evaluate with arguments': async p => {
123+
const n = await p.locator('#pizza-name').evaluate((pizzaName, extra) => pizzaName.textContent + extra, ' Super pizza!');
124+
return n == 'Our recommendation: Super pizza!';
125+
}
126+
});
127+
```
128+
129+
```javascript
130+
const jsHandle = await page.locator('#pizza-name').evaluateHandle((pizzaName) => pizzaName);
131+
132+
const obj = await jsHandle.evaluateHandle((handle) => {
133+
return { innerText: handle.innerText };
134+
});
135+
console.log(await obj.jsonValue()); // {"innerText":"Our recommendation:"}
136+
```
137+
138+
### New officially supported [k6 DNS extension](https://github.com/grafana/xk6-dns)
139+
140+
The [`xk6-dns` extension](https://grafana.com/docs/k6/latest/javascript-api/k6-x-dns) is now officially supported in k6 OSS and k6 Cloud. You can import `k6/x/dns` directly in your scripts thanks to [automatic extension resolution](https://grafana.com/docs/grafana-cloud/testing/k6/author-run/use-k6-extensions/), with no custom build required.
141+
142+
Use it to perform DNS resolution testing as part of your tests: resolve names via custom or system DNS, measure resolution latency and errors, validate records before HTTP steps, compare resolvers, and even load test DNS servers in end‑to‑end scenarios.
143+
144+
For example:
145+
146+
```javascript
147+
import dns from 'k6/x/dns';
148+
149+
export default function () {
150+
const answer = dns.resolve('grafana.com', { recordType: 'A' });
151+
console.log(answer.records.map(({ address }) => address).join(', '));
152+
}
153+
```
154+
155+
The extension currently supports A and AAAA record lookups. If you would like to see additional record types supported, please consider [contributing to the extension](https://github.com/grafana/xk6-dns).
156+
157+
158+
### Automatic extension resolution improvements [#5320](https://github.com/grafana/k6/pull/5320), [#5239](https://github.com/grafana/k6/pull/5239), [#5342](https://github.com/grafana/k6/pull/5342), [#5332](https://github.com/grafana/k6/pull/5332), [#5240](https://github.com/grafana/k6/pull/5240)
159+
160+
Automatic extension resolution has been completely reimplemented to use k6's internal module loader instead of the external `k6deps`/esbuild pipeline. This change brings significant improvements in reliability and maintainability.
161+
162+
As part of the rewrite, a few issues and unintended _features_ were found, namely:
163+
1. Trying to follow `require` calls, which, due to their dynamic nature, don't work particularly stably. That is, depending on where and how the `require` call was used, k6 might decide whether it is needed or not. And it definitely doesn't work when using actual string variables. Support for CommonJS is primarily for backward compatibility, so after an internal discussion, we opted not to support it at all. We could bring this back until v2, if there is enough interest. However, in the long term, it is intended that this not be part of k6.
164+
2. "use k6 with ..." directives were parsed from the whole file instead of just the beginning, which leads to numerous problems, and was not the intended case. As such, they are now only parsed at the beginning of files (not just the main one) with potential empty lines and comments preceding them.
165+
166+
**Example:**
167+
168+
```javascript
169+
// main.js
170+
"use k6 with k6/x/faker"
171+
import { faker } from 'k6/x/faker';
172+
import { helper } from './utils.js';
173+
174+
export default function() {
175+
console.log(faker.name());
176+
helper();
177+
}
178+
```
179+
Or, an example using the directive with CommonJS
180+
```javascript
181+
// utils.js
182+
"use k6 with k6/x/redis"
183+
const redis = require('k6/x/redis');
184+
185+
exports.helper = function() {
186+
// Use redis extension
187+
}
188+
```
189+
190+
In this example, k6 will detect both `k6/x/faker` and `k6/x/redis` extensions from the `use k6` directives in both files and provision a binary that includes both extensions if needed.
191+
192+
Other fixes this brings are:
193+
1. Fixes for path related issues (irregardless of usage of the feature) on windows, especially between drives. It is possible there were problems on other OSes that were just not reported. [#5176](https://github.com/grafana/k6/issues/5176)
194+
2. Syntax errors were not reported as such, as the underlying `esbuild` parsing will fail, but won't be handled well. [#5127](https://github.com/grafana/k6/issues/5127), [#5104](https://github.com/grafana/k6/issues/5104)
195+
196+
3. Propagating exit codes from a sub-process running the new k6. This lets you use the result of the exit code.

‎docs/sources/k6/v1.4.x/_index.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
aliases:
3+
- /docs/k6/
4+
description: 'The k6 documentation covers everything you need to know about k6 OSS, load testing, and performance testing.'
5+
menuTitle: Grafana k6
6+
title: Grafana k6
7+
weight: -10
8+
hero:
9+
title: Grafana k6
10+
level: 1
11+
image: /media/docs/k6/GrafanaLogo_k6_orange_icon.svg
12+
width: 100
13+
height: 100
14+
description: Grafana k6 is an open-source, developer-friendly, and extensible load testing tool. k6 allows you to prevent performance issues and proactively improve reliability.
15+
cards:
16+
title_class: pt-0 lh-1
17+
items:
18+
- title: Run your first k6 test
19+
href: ./get-started/
20+
description: Learn how to install the k6 CLI, run your first k6 test, and view metric results in the terminal.
21+
height: 24
22+
- title: Using k6
23+
href: ./using-k6/
24+
description: Learn about k6 options and concepts such as thresholds, metrics, lifecycle hooks, and more.
25+
height: 24
26+
- title: Testing guides
27+
href: ./testing-guides/
28+
description: Discover how to plan and define your performance testing strategy with these guides.
29+
height: 24
30+
- title: k6 JavaScript API
31+
href: ./javascript-api/
32+
description: Explore the k6 APIs through their documentation and examples.
33+
height: 24
34+
- title: Explore k6 extensions
35+
href: ./extensions/
36+
description: Have a particular testing need? Find k6 extensions that extend the native k6 functionality.
37+
height: 24
38+
- title: k6 script examples
39+
href: ./examples/
40+
description: Learn how to write test scripts with this list of common k6 examples.
41+
height: 24
42+
- title: Grafana Cloud k6
43+
href: https://grafana.com/docs/grafana-cloud/testing/k6/
44+
description: Leverage the k6 OSS capabilities in Grafana Cloud, with built-in dashboards, insights into your application performance, and the ability to bring together teams in one place to resolve issues faster.
45+
height: 24
46+
- title: k6 Studio
47+
href: https://grafana.com/docs/k6-studio/
48+
description: Use the k6 Studio desktop application to quickly generate test scripts using a visual interface.
49+
height: 24
50+
---
51+
52+
{{< docs/hero-simple key="hero" >}}
53+
54+
---
55+
56+
## Overview
57+
58+
Using k6, you can test the reliability and performance of your application and infrastructure.
59+
60+
k6 helps engineering teams prevent errors and SLO breaches, enabling them to build resilient and high-performing applications that scale.
61+
62+
Engineering teams, including Developers, QA Engineers, SDETs, and SREs, commonly use k6 for:
63+
64+
- **Load and performance testing**
65+
66+
k6 is optimized for minimal resource consumption and designed for running high-load performance tests such as
67+
[spike](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/spike-testing), [stress](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/stress-testing), or [soak tests](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/test-types/soak-testing).
68+
69+
- **Browser performance testing**
70+
71+
Through the [k6 browser API](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser), you can run browser-based performance tests and collect browser metrics to identify performance issues related to browsers. Additionally, you can mix browser tests with other performance tests to get a comprehensive view of your website's performance.
72+
73+
- **Performance and synthetic monitoring**
74+
75+
You can schedule tests to run with minimal load very frequently, continuously validating the performance and availability of your production environment. For this, you can also use [Grafana Cloud Synthetic Monitoring](https://grafana.com/docs/grafana-cloud/testing/synthetic-monitoring/create-checks/checks/k6/), which supports running k6 scripts.
76+
77+
- **Automation of performance tests**
78+
79+
k6 integrates seamlessly with CI/CD and automation tools, enabling engineering teams to [automate performance testing](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/automated-performance-testing/) as part of their development and release cycle.
80+
81+
- **Chaos and resilience testing**
82+
83+
You can use k6 to simulate traffic as part of your chaos experiments, trigger them from your k6 tests or inject different types of faults in Kubernetes with [xk6-disruptor](https://grafana.com/docs/k6/<K6_VERSION>/testing-guides/injecting-faults-with-xk6-disruptor/xk6-disruptor).
84+
85+
- **Infrastructure testing**
86+
87+
With [k6 extensions](https://grafana.com/docs/k6/<K6_VERSION>/extensions/), you can add support to k6 for new protocols or use a particular client to directly test individual systems within your infrastructure.
88+
89+
Watch the video below to learn more about k6 and why it could be the missing puzzle in your Grafana stack.
90+
91+
{{< youtube id="1mtYVDA2_iQ" >}}
92+
93+
## Explore
94+
95+
{{< card-grid key="cards" type="simple" >}}

‎docs/sources/k6/v1.4.x/examples/_index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Examples
3+
weight: 800
4+
---
5+
6+
# Examples
7+
8+
<!-- TODO: Add content -->
9+
10+
{{< section >}}

0 commit comments

Comments
 (0)