From befc5e7f80e4800e3fba204fb883c045d12ba1e5 Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Fri, 19 Jul 2024 16:36:12 -0500 Subject: [PATCH] chore: move release notes folder and v0.52 release notes (#1644) * chore: add release notes folder and v0.52 release notes * chore: reorder sections * chore: add link to k6 repo release notes folder * chore: add release-notes folder to eslintignore * chore: add release notes for the last 6 versions * Set `weight` to order the release notes list * Update weight and add canonical links --------- Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> --- .eslintignore | 1 + docs/sources/next/get-started/_index.md | 2 +- docs/sources/next/misc/release-notes.md | 9 - docs/sources/next/release-notes/_index.md | 14 + docs/sources/next/release-notes/v0.47.0.md | 157 +++++++++++ docs/sources/next/release-notes/v0.48.0.md | 310 +++++++++++++++++++++ docs/sources/next/release-notes/v0.49.0.md | 209 ++++++++++++++ docs/sources/next/release-notes/v0.50.0.md | 183 ++++++++++++ docs/sources/next/release-notes/v0.51.0.md | 295 ++++++++++++++++++++ docs/sources/next/release-notes/v0.52.0.md | 145 ++++++++++ docs/sources/next/set-up/_index.md | 2 +- 11 files changed, 1316 insertions(+), 11 deletions(-) delete mode 100644 docs/sources/next/misc/release-notes.md create mode 100644 docs/sources/next/release-notes/_index.md create mode 100644 docs/sources/next/release-notes/v0.47.0.md create mode 100644 docs/sources/next/release-notes/v0.48.0.md create mode 100644 docs/sources/next/release-notes/v0.49.0.md create mode 100644 docs/sources/next/release-notes/v0.50.0.md create mode 100644 docs/sources/next/release-notes/v0.51.0.md create mode 100644 docs/sources/next/release-notes/v0.52.0.md diff --git a/.eslintignore b/.eslintignore index 9456f27a47..1c8f5f6328 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,6 +1,7 @@ .cache/ public/ node_modules/ +docs/sources/*/release-notes docs/sources/get-started/run-cloud-tests-from-the-CLI.md docs/sources/get-started/run-your-first-tests.md docs/sources/*/using-k6/metrics/create-custom-metrics.md diff --git a/docs/sources/next/get-started/_index.md b/docs/sources/next/get-started/_index.md index 6df58599b8..8e5613cb6d 100644 --- a/docs/sources/next/get-started/_index.md +++ b/docs/sources/next/get-started/_index.md @@ -1,5 +1,5 @@ --- -weight: 01 +weight: 150 title: Get started --- diff --git a/docs/sources/next/misc/release-notes.md b/docs/sources/next/misc/release-notes.md deleted file mode 100644 index e27d9eac8c..0000000000 --- a/docs/sources/next/misc/release-notes.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Release notes -redirect: 'https://github.com/grafana/k6/releases' -weight: 06 ---- - -# Release notes - -You can find the k6 release notes in the k6 GitHub repository on the [Releases page](https://github.com/grafana/k6/releases), and the "[release notes](https://github.com/grafana/k6/tree/master/release%20notes)" folder. diff --git a/docs/sources/next/release-notes/_index.md b/docs/sources/next/release-notes/_index.md new file mode 100644 index 0000000000..967b1fd86d --- /dev/null +++ b/docs/sources/next/release-notes/_index.md @@ -0,0 +1,14 @@ +--- +aliases: + - ../misc/release-notes # docs/k6//misc/release-notes +title: Grafana k6 release notes +menuTitle: Release notes +description: Learn more about new features, breaking changes, and bug fixes for each Grafana k6 version with the release notes. +weight: 100 +--- + +# Grafana k6 release notes + +{{< section >}} + +You can find a full list of release notes in the [k6 GitHub repository](https://github.com/grafana/k6/tree/master/release%20notes). diff --git a/docs/sources/next/release-notes/v0.47.0.md b/docs/sources/next/release-notes/v0.47.0.md new file mode 100644 index 0000000000..970c9b5bd4 --- /dev/null +++ b/docs/sources/next/release-notes/v0.47.0.md @@ -0,0 +1,157 @@ +--- +title: Grafana k6 version 0.47.0 release notes +menuTitle: v0.47.0 +description: The release notes for Grafana k6 version 0.47.0 +weight: 10000 +canonical: https://github.com/grafana/k6/blob/master/release%20notes/v0.47.0.md +--- + +# Grafana k6 version 0.47.0 release notes + +k6 `v0.47.0` is here πŸŽ‰! This release includes: + +## Deprecations + +- [#3347](https://github.com/grafana/k6/pull/3347) The built-in `statsd` output option has been deprecated, and users should use the [xk6-output-statsd](https://github.com/LeonAdato/xk6-output-statsd) extension instead. See [#2982](https://github.com/grafana/k6/issues/2982) for future plans. +- [#3288](https://github.com/grafana/k6/pull/3288) Loading remote modules now requires users to prepend them with `https://`. Before, k6 would try to resolve importing remote modules by prepending `https://` if it was missing. This behavior has been deprecated and will be fully removed in the next release (v0.48.0). + +## New features + +### Add gRPC's binary metadata support [#3234](https://github.com/grafana/k6/pull/3234), [xk6-grpc#46](https://github.com/grafana/xk6-grpc/pull/46) + +The k6 gRPC modules (`k6/net/grpc` and `k6/experimental/grpc`) now support handling binary metadata that uses the `-bin` postfix, according to the gRPC specification. + +```js +let resp = client.invoke( + 'grpc.testing.TestService/EmptyCall', + {}, + { metadata: { 'X-Load-Tester-bin': new Uint8Array([2, 200]) } } +); +``` + +Thanks to @sapphire-janrain for the contribution! + +### Add gRPC's reflection metadata support [#3343](https://github.com/grafana/k6/pull/3343), [xk6-grpc#46](https://github.com/grafana/xk6-grpc/pull/46) + +The k6 gRPC modules (`k6/net/grpc` and `k6/experimental/grpc`) now support adding metadata to reflection requests by using a new connection parameter [`reflectMetadata`](https://k6.io/docs/javascript-api/k6-net-grpc/client/client-connect/#connectparams). + +### Higher precision for Trend metrics in Grafana Cloud k6 [#3302](https://github.com/grafana/k6/pull/3302) + +Grafana Cloud k6 is now able to store and visualize Trend metrics up to 3 digits of precision for decimal numbers. + +### Docker support for browser-based tests [#3199](https://github.com/grafana/k6/pull/3199) + +k6 is now publishig Docker images that include Chromium web browser. This allows k6 users to run tests that use [Browser API](https://k6.io/docs/javascript-api/k6-experimental/browser/) without having to install Chrome first. Check the ["A note on running browser tests" section](https://hub.docker.com/r/grafana/k6) of the Overview page on DockerHub for details. + +### Docker images for ARM64 architecture [#3320](https://github.com/grafana/k6/pull/3320) + +The k6's release process now builds and pushes dedicated Docker images for ARM64. Check k6's [tags page](https://hub.docker.com/r/grafana/k6/tags) on DockerHub for details. + +### New authentication methods and HTTP headers API for Prometheus remote write output [xk6-output-prometheus-remote#143](https://github.com/grafana/xk6-output-prometheus-remote/pull/143), [xk6-output-prometheus-remote#145](https://github.com/grafana/xk6-output-prometheus-remote/pull/145), [xk6-output-prometheus-remote#147](https://github.com/grafana/xk6-output-prometheus-remote/pull/147) + +The experimental Prometheus remote write output now supports two new authentication methods: Bearer token and TLS certificates. Check out the [documentation](https://k6.io/docs/results-output/real-time/prometheus-remote-write/#options) to learn more about how to define them using the new environment variables. +We've also added the `K6_PROMETHEUS_RW_HTTP_HEADERS` that defines a new and more convenient way to set custom HTTP headers to pass through each flush metrics' request. + +### Improved the browser module's cookie API + +The browser module now provides a more complete and robust API for handling cookies. The cookie API was stabilized by defining a new [`Cookie` class](https://k6.io/docs/javascript-api/k6-experimental/browser/browsercontext/cookie) ([browser#1008](https://github.com/grafana/xk6-browser/pull/1008), [browser#1030](https://github.com/grafana/xk6-browser/pull/1030)) that can be used while creating and retrieving cookies. This enabled us to add a new [`browserContext.cookies([urls])`](https://k6.io/docs/javascript-api/k6-experimental/browser/browsercontext/cookies/) method ([browser#1005](https://github.com/grafana/xk6-browser/pull/1005)) that returns all cookies from the current [browser context](https://k6.io/docs/javascript-api/k6-experimental/browser/browsercontext). The new API also supports filtering cookies by URL ([browser#1016](https://github.com/grafana/xk6-browser/pull/1016)). + +That led to fixing a bug where the `expires` field was not being set correctly while adding cookies using the [`context.addCookie()`](https://k6.io/docs/javascript-api/k6-experimental/browser/browsercontext/addcookies/) method ([browser#1031](https://github.com/grafana/xk6-browser/pull/1031)). Lastly, the existing [`context.clearCookies()`](https://k6.io/docs/javascript-api/k6-experimental/browser/browsercontext/clearcookies) method was fixed to clear all cookies from the current [browser context](https://k6.io/docs/javascript-api/k6-experimental/browser/browsercontext) ([browser#1040](https://github.com/grafana/xk6-browser/pull/1040)). + +```js +const context = browser.newContext(); +context.addCookies([ + { name: 'foo', value: 'bar', url: 'https://test.k6.io' }, + { name: 'baz', value: 'qux', url: 'https://grafana.com' }, +]); + +const cookies = context.cookies('https://test.k6.io'); +console.log(cookies.length); // 1 +console.log(cookies[0].name); // foo +console.log(cookies[0].value); // bar + +context.clearCookies(); +console.log(context.cookies.length); // 0 +``` + +### Add support for browser module's `page.on('console')` [browser#1006](https://github.com/grafana/xk6-browser/pull/1006) + +Allows users to register a handler to be executed every time the `console` API methods are called from within the page's JavaScript context. The arguments passed into the handler are defined by the [ConsoleMessage](https://k6.io/docs/javascript-api/k6-experimental/browser/consolemessage/) class. + +```js +page.on('console', (msg) => { + check(msg, { + assertConsoleMessageType: (msg) => msg.type() == 'log', + assertConsoleMessageText: (msg) => msg.text() == 'this is a console.log message 42', + assertConsoleMessageArgs0: (msg) => + msg.args()[0].jsonValue() == 'this is a console.log message', + assertConsoleMessageArgs1: (msg) => msg.args()[1].jsonValue() == 42, + }); +}); + +page.evaluate(() => console.log('this is a console.log message', 42)); +``` + +## UX improvements and enhancements + +- [#3338](https://github.com/grafana/k6/pull/3338), [xk6-grpc#48](https://github.com/grafana/xk6-grpc/pull/48) Adds support for the gRPC reflection protocol v1. +- [#3290](https://github.com/grafana/k6/pull/3290) Adds error logging when executing `setup` and `teardown` via REST API. Thanks to @kmtym1998 for the contribution! +- [#3327](https://github.com/grafana/k6/pull/3327) Adds commit identifier for the k6 build when running `k6 version`. +- [#3340](https://github.com/grafana/k6/pull/3340) Updates k6 `*-with-browser` Docker images to automatically set the `no-sandbox` environment variable. +- [#3335](https://github.com/grafana/k6/pull/3335) The character limit for metric names increased from 63 to 128 after the OpenTelemetry update. k6 will return an error starting on the next release (v0.48.0) if users hit the limit. +- [browser#1007](https://github.com/grafana/xk6-browser/pull/1007) Adds a `k6` object (`window.k6 = {};`) to help identify k6 browser module tests. +- [browser#1022](https://github.com/grafana/xk6-browser/pull/1022) Refactors the `check` in `examples/fillform.js` so that it matches the type definitions and documentation for `check`. + +## Bug fixes + +- [xk6-grpc#47](https://github.com/grafana/xk6-grpc/pull/47) Fixes the premature closing of a gRPC stream when a stream's client has finished sending. Thanks to @thiagodpf for reporting! +- [#3344](https://github.com/grafana/k6/pull/3344), [xk6-grpc#49](https://github.com/grafana/xk6-grpc/pull/49) Adds support for Google's protobuf wrappers. Thanks to @zibul444 for reporting! +- [#3308](https://github.com/grafana/k6/pull/3308) Updates `goja` version, and fixes a compiler bug when a class is declared in a function with an argument. +- [browser#1039](https://github.com/grafana/xk6-browser/pull/1039) Fixes `goja` conversions while adding and retrieving cookies. +- [browser#1038](https://github.com/grafana/xk6-browser/pull/1038) Fixes read/write data race for edge case with remote browsers. +- [browser#1034](https://github.com/grafana/xk6-browser/pull/1034) Fixes `page.reload` & `page.setContent` to use the default navigation timeout over the default timeout. +- [browser#1033](https://github.com/grafana/xk6-browser/pull/1033) Fixes the `page` timeouts so it is actually used after being set. + +## Maintenance and internal improvements + +- [#3342](https://github.com/grafana/k6/pull/3342) Updates xk6-grpc to the latest version. This change brings all the latest fixes and improvements to the experimental gRPC module. +- [#3271](https://github.com/grafana/k6/pull/3271),[#3272](https://github.com/grafana/k6/pull/3272) Updates the golangci version and adds the `interfacebloat` linter. +- [#3279](https://github.com/grafana/k6/pull/3279) Fixes the CI not publishing the SBOM file on a new release. +- [#3283](https://github.com/grafana/k6/pull/3283) Updates the Go version in k6's CI used to build the binaries. +- [#3341](https://github.com/grafana/k6/pull/3341), [#3339](https://github.com/grafana/k6/pull/3339) Updates `goja`, includes runtime initialization speed-up and a fix for source indexes. +- [#3311](https://github.com/grafana/k6/pull/3311) Updates the `alpine` image version that is used as the base of the k6 Docker image. +- [browser#1043](https://github.com/grafana/xk6-browser/pull/1043), [browser#1021](https://github.com/grafana/xk6-browser/pull/1021), [browser#1019](https://github.com/grafana/xk6-browser/pull/1019), [browser#1014](https://github.com/grafana/xk6-browser/pull/1014) Fixes xk6-browser tests. +- [browser#1000](https://github.com/grafana/xk6-browser/pull/1000), [browser#1024](https://github.com/grafana/xk6-browser/pull/1024) Refines xk6-browser issue and PR templates. +- [browser#1003](https://github.com/grafana/xk6-browser/pull/1003), [browser#1009](https://github.com/grafana/xk6-browser/pull/1009), [browser#1010](https://github.com/grafana/xk6-browser/pull/1010) Internal changes to xk6-browser. +- [browser#997](https://github.com/grafana/xk6-browser/pull/997) Updates xk6-browser readme. +- [browser#962](https://github.com/grafana/xk6-browser/pull/962) CI fixes. +- [browser#1035](https://github.com/grafana/xk6-browser/pull/1035) Refactors `int64` timeout to `time.Duration`, to help avoid confusion as to whether a timeout is in milliseconds or seconds. + +## Roadmap + +### Native ECMAScript Modules support + +Work on this [epic issue](https://github.com/grafana/k6/issues/3265) has been picked up and there is some progress in the underlying implementation. + +One of the main internal changes will be dropping [Babel](https://babeljs.io), which is currently used to transpile [ESM](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) code to [CommonJS](https://en.wikipedia.org/wiki/CommonJS). + +For users, it will mean better JavaScript support as this change will automatically get [object spread](https://github.com/grafana/k6/issues/824) working and likely faster startup for _big_ scripts. In the future, this also means JavaScript compatibility will be easier to add, since it'll only need to be supported in the JavaScript VM we use - [goja](https://github.com/dop251/goja). + +There's a risk that some k6 tests using both CommonJS and ECMAScript modules syntax will change in behavior. In practice, using both should never really be done as they're not compatible. + +Because there are risks involved, we are going to do this very carefully and only once we have done a lot of tests. That means this is currently planned for v0.49.0, but with the majority of the remaining work done in the v0.48.0 cycle. + +This way, we will also be able to have most of our users test these changes from our `master` branch, using Docker images, for example. + +### Future breaking changes + +There are several changes in the next release that are entering the final stage of their deprecation period. That means the next release will include the following breaking changes: + +- [#3065](https://github.com/grafana/k6/issues/3065) Metric names will be limited to 128 characters and a set of allowed symbols. This was going to be changed to a 63 character limit to ensure compatibility with OpenTelemetry standards, but since then, the OTel limit has been updated to 255 characters. You can find more details about the changes in the linked issue. +- [#3365](https://github.com/grafana/k6/pull/3365) The `k6 converter` command will be removed. +- [#3350](https://github.com/grafana/k6/pull/3350) The `headers` param for the gRPC module will be removed. Users should use the [metadata](https://k6.io/docs/javascript-api/k6-experimental/grpc/params) property instead. +- [#3287](https://github.com/grafana/k6/issues/3287) Loading remote modules will require users to include the `https://` protocol in their URLs, otherwise it will return an error. +- CSV output no longer accepts arguments in snake case (for example, [fileName](https://k6.io/docs/results-output/real-time/csv/#csv-options) should be used instead of `file_name`). +- The `--logformat` flag for defining the Log format option will be removed. [--log-format](https://k6.io/docs/using-k6/k6-options/reference/#logformat) should be used instead. + +We recommend checking this list to see if you are impacted, and updating your scripts or CI/CD processes to avoid any issues. If you have any feedback, please open an issue. diff --git a/docs/sources/next/release-notes/v0.48.0.md b/docs/sources/next/release-notes/v0.48.0.md new file mode 100644 index 0000000000..5f3e2a3ddf --- /dev/null +++ b/docs/sources/next/release-notes/v0.48.0.md @@ -0,0 +1,310 @@ +--- +title: Grafana k6 version 0.48.0 release notes +menuTitle: v0.48.0 +description: The release notes for Grafana k6 version 0.48.0 +weight: 9999 +canonical: https://github.com/grafana/k6/blob/master/release%20notes/v0.48.0.md +--- + +# Grafana k6 version 0.48.0 release notes + +k6 v0.48.0 is here πŸŽ‰! This release includes: + +- Numerous long-awaited breaking changes. +- A new `k6 new` subcommand to generate a new test script. +- A new `k6/experimental/fs` module for file interactions. +- CPU and network throttling support for the k6 browser module. + +## Breaking changes + +This release includes several breaking changes, mainly cleaning up deprecations from previous versions. They should have a straightforward migration process, and not heavily impact existing users. + +- [#3448](https://github.com/grafana/k6/pull/3448) limits metric names, aligning to both OpenTelemetry (OTEL) and Prometheus name requirements, while still being limited to 128 ASCII characters. Warnings about the limit started in [v0.45](https://github.com/grafana/k6/releases/tag/v0.45.0). +- [#3439](https://github.com/grafana/k6/pull/3439) changes the `Client` signature in `k6/experimental/redis` module. Refer to the module-related section below. +- [#3350](https://github.com/grafana/k6/pull/3350) removes the `grpc.invoke()`'s parameter `headers`, deprecated in k6 [v0.37](https://github.com/grafana/k6/releases/tag/v0.37.0). Use the `metadata` parameter instead. +- [#3389](https://github.com/grafana/k6/pull/3389) removes the `--logformat` flag, deprecated in [v0.38](https://github.com/grafana/k6/releases/tag/v0.38.0). Use the `--log-format` flag instead. +- [#3390](https://github.com/grafana/k6/pull/3390) removes all CSV output's CLI arguments, deprecated in [v0.35](https://github.com/grafana/k6/releases/tag/v0.35.0). This change makes the CSV output consistent with other output formats. +- [#3365](https://github.com/grafana/k6/pull/3365) removes the `k6 convert` CLI command, deprecated in [v0.41](https://github.com/grafana/k6/releases/tag/v0.41.0). Use the [har-to-k6](https://github.com/grafana/har-to-k6) package instead. +- [#3451](https://github.com/grafana/k6/pull/3451) removes logic that would attempt to prepend a `https://` scheme to module specifiers that were not recognized. Deprecated in k6 [v0.25](https://github.com/grafana/k6/releases/tag/v0.25.0). Use full URLs if you want to load remote modules instead. + +## New features + +### Add `k6 new` subcommand [#3394](https://github.com/grafana/k6/pull/3394) + +`k6` now has a `new` subcommand that generates a new test script. This is useful for new users who want to get started quickly, or for experienced users who want to save time when creating new test scripts. To use the subcommand, open your terminal and type: + +```bash +k6 new [filename] +``` + +If no filename is provided, k6 uses `script.js` as the default filename. The subcommand will create a new file with the provided name in the current directory, and populate it with a basic test script that can be run with `k6 run`. + +### Add a `k6/experimental/fs` module [#3165](https://github.com/grafana/k6/pull/3165) + +`k6` now has a new `k6/experimenal/fs` module providing a memory-efficient way to handle file interactions within your test scripts. It currently offers support for opening files, reading their content, seeking through it, and retrieving metadata about them. + +Unlike the traditional [open](https://grafana.com/docs/k6/latest/javascript-api/init-context/open/) function, which loads a file multiple times into memory, the filesystem module reduces memory usage by loading the file as little as possible, and sharing the same memory space between all VUs. This approach significantly reduces the memory footprint of your test script and lets you load and process large files without running out of memory. + +For more information, refer to the [module documentation](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/fs/). + +
+ Expand to see an example of the new functionality. + +This example shows the new module usage: + +```javascript +import fs from 'k6/experimental/fs'; + +// k6 doesn't support async in the init context. We use a top-level async function for `await`. +// +// Each Virtual User gets its own `file` copy. +// So, operations like `seek` or `read` won't impact other VUs. +let file; +(async function () { + file = await open('bonjour.txt'); +})(); + +export default async function () { + // About information about the file + const fileinfo = await file.stat(); + if (fileinfo.name != 'bonjour.txt') { + throw new Error('Unexpected file name'); + } + + const buffer = new Uint8Array(128); + + let totalBytesRead = 0; + while (true) { + // Read into the buffer + const bytesRead = await file.read(buffer); + if (bytesRead == null) { + // EOF + break; + } + + // Do something useful with the content of the buffer + totalBytesRead += bytesRead; + + // If bytesRead is less than the buffer size, we've read the whole file + if (bytesRead < buffer.byteLength) { + break; + } + } + + // Check that we read the expected number of bytes + if (totalBytesRead != fileinfo.size) { + throw new Error('Unexpected number of bytes read'); + } + + // Seek back to the beginning of the file + await file.seek(0, SeekMode.Start); +} +``` + +
+ +### Redis (m)TLS support and new Client constructor options [#3439](https://github.com/grafana/k6/pull/3439), [xk6-redis/#17](https://github.com/grafana/xk6-redis/pull/17) + +In this release, the `k6/experimental/redis` module receives several important updates, including breaking changes. + +#### Connection URLs + +The `Client` constructor now supports connection URLs to configure connections to Redis servers or clusters. These URLs can be in the format `redis://[[username][:password]@][host][:port][/db-number]` for standard connections, or `rediss://[[username][]:password@]][host][:port][/db-number]` for TLS-secured connections. For more details, refer to the [documentation](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/redis/). + +##### Example usage + +```javascript +import redis from 'k6/experimental/redis'; + +const redisClient = new redis.Client('redis://someusername:somepassword@localhost:6379/0'); +``` + +#### Revamped Options object + +The `Client` constructor has been updated with a new [Options](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/redis/redis-options/) object format. This change aligns the module with familiar patterns from Node.js and Deno libraries, offering enhanced flexibility and control over Redis connections. For more details, refer to the [documentation](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/redis/redis-options/). + +
+ Expand to see an example of the new functionality. + +This example shows the usage of the new `Options` object: + +```javascript +import redis from 'k6/experimental/redis'; + +const redisClient = new redis.Client({ + socket: { + host: 'localhost', + port: 6379, + }, + username: 'someusername', + password: 'somepassword', +}); +``` + +
+ +#### (m)TLS support + +The Redis module now includes (m)TLS support, enhancing security for connections. This update also improves support for Redis clusters and sentinel modes (failover). For connections using self-signed certificates, enable k6's [insecureSkipTLSVerify](https://grafana.com/docs/k6/latest/using-k6/k6-options/reference/#insecure-skip-tls-verify) option (set to `true`). + +
+ Expand to see an example of the new functionality. + +This example shows the configuration of a TLS connection: + +```javascript +import redis from 'k6/experimental/redis'; + +const redisClient = new redis.Client({ + socket: { + host: 'localhost', + port: 6379, + tls: { + ca: [open('ca.crt')], + cert: open('client.crt'), // client certificate + key: open('client.key'), // client private key + }, + }, +}); +``` + +
+ +### Add tracing instrumentation [#3445](https://github.com/grafana/k6/pull/3445) + +`k6` now supports a new _traces output_ option that allows you to configure the output for traces generated during its execution. This option can be set through the `--traces-output` argument in the `k6 run` command or by setting the `K6_TRACES_OUTPUT` environment variable. + +Currently, no traces are generated by `k6` itself, but this feature represents the first step towards richer tracing functionalities in `k6` and its extensions. + +By default traces output is set to `none`, and currently the only supported output is `otel` which uses the [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go)'s [Open Telemetry](https://opentelemetry.io/) API and SDK implementations. The format for the `otel` _traces output_ configuration is the following: + +``` +--traces-output=[,opt1=val1,opt2=val2] +``` + +Where `opt`s can be one of the following options: + +- `proto`: Specifies the protocol to use in the connection to the traces backend. Supports `grpc` _(default)_ and `http`. +- `header.`: Specifies an additional header to include in the connection to the traces backend. + +Example: + +``` +K6_TRACES_OUTPUT=https://traces.k6.io/v1/traces,proto=http,header.Authorization=Bearer token +``` + +### Add support for browser module's `page.throttleCPU` [browser#1095](https://github.com/grafana/xk6-browser/pull/1095) + +The browser module now supports throttling the CPU from chrome/chromium's perspective by using the `throttleCPU` API, which helps emulate slower devices when testing the website's frontend. It requires an argument of type `CPUProfile`, which includes a `rate` field that is a slow-down factor, where `1` means no throttling, `2` means 2x slowdown, and so on. For more details, refer to the [documentation](https://grafana.com/docs/k6/v0.48.x/javascript-api/k6-experimental/browser/page/throttlecpu). + +```js +... + const context = browser.newContext(); + const page = context.newPage(); + + try { + page.throttleCPU({ rate: 4 }); +... +``` + +### Add support for browser module's `page.throttleNetwork` [browser#1094](https://github.com/grafana/xk6-browser/pull/1094) + +The browser module now supports throttling the characteristics of the network from chrome/chromium's perspective by using the `throttleNetwork` API, which helps emulate slow network connections when testing the website's frontend. It requires an argument of type `NetworkProfile`, with a definition of: + +```ts +export interface NetworkProfile { + /* + * Minimum latency from request sent to response headers received (ms). + */ + latency: number; + + /* + * Maximal aggregated download throughput (bytes/sec). -1 disables download + * throttling. + */ + download: number; + + /* + * Maximal aggregated upload throughput (bytes/sec). -1 disables upload + * throttling. + */ + upload: number; +} +``` + +You can either define your own network profiles or use the ones we have defined by importing `networkProfiles` from the `browser` module. For more details, refer to the [documentation](https://grafana.com/docs/k6/v0.48.x/javascript-api/k6-experimental/browser/page/throttlenetwork). + +```js +import { browser, networkProfiles } from 'k6/experimental/browser'; +... + const context = browser.newContext(); + const page = context.newPage(); + + try { + page.throttleNetwork(networkProfiles['Slow 3G']); +... +``` + +## k6's documentation is moving under [grafana.com/docs/k6](https://grafana.com/docs/k6) + +It's not directly part of the k6 v0.48 release, but we believe it is worth mentioning that we're moving the documentation from [k6.io/docs](https://k6.io/docs/) to [grafana.com/docs/k6](https://grafana.com/docs/k6). + +The legacy documentation space `k6.io/docs` will be available for a while, but we encourage you to update your bookmarks and links to the new domain. + +## UX improvements and enhancements + +- [browser#1074](https://github.com/grafana/xk6-browser/pull/1074) adds a new `browser.closeContext()` [method](https://grafana.com/docs/k6/v0.48.x/javascript-api/k6-experimental/browser/closecontext) to facilitate closing the current active browser context. +- [#3370](https://github.com/grafana/k6/pull/3370) adds a new flag `--profiling-enabled` which enables exposing [pprof](https://go.dev/blog/pprof) profiling endpoints. The profiling endpoints are exposed on the same port as the HTTP REST API under the `/debug/pprof/` path. This can be useful for extension developers. +- [#3442](https://github.com/grafana/k6/pull/3442) adds a new `--version` flag, which has the same output as `k6 version` command. Thanks, @ffapitalle! +- [#3423](https://github.com/grafana/k6/pull/3423) adds an environment variable `K6_INFLUXDB_PROXY` to the InfluxDB output which allows specifying proxy. Thanks, @IvanovOleg! +- [#3398](https://github.com/grafana/k6/pull/3398) enables k6 cloud traces by default. +- [#3400](https://github.com/grafana/k6/pull/3400) sets a binary-based cloud output (a.k.a. cloud output v2) as the default version for streaming metrics from a local test run via `-o cloud`. +- [#3452](https://github.com/grafana/k6/pull/3452) adds `fsext.Abs` helper function. + +## Bug fixes + +- [#3380](https://github.com/grafana/k6/pull/3380) corrects `console.debug()`, aligning `-v` output to `--console-output` and `stdout`. +- [#3416](https://github.com/grafana/k6/pull/3416) prints the stack trace when there's an exception in `handleSummary()`. +- [#3438](https://github.com/grafana/k6/pull/3438) prevents an error on HTTP requests with `content-encoding` header and HTTP statuses known for having no body. +- [browser#1077](https://github.com/grafana/xk6-browser/pull/1077) fixes `browserContext.clearPermissions` to clear permissions without panic. +- [browser#1042](https://github.com/grafana/xk6-browser/pull/1042) fixes `browserContext.waitForEvent` which involved promisifying the `waitForEvent` API. +- [browser#1078](https://github.com/grafana/xk6-browser/pull/1078) fixes request interception deadlock to improve stability. +- [browser#1101](https://github.com/grafana/xk6-browser/pull/1101) fixes `page.$` so that it returns `null` when no matches with given selector are found. +- [#3397](https://github.com/grafana/k6/pull/3397), [#3427](https://github.com/grafana/k6/pull/3427), [#3417](https://github.com/grafana/k6/pull/3417) update `goja` dependency. Fixes a possible panic and proper handling circular types at `JSON.stringify`. Fixes an issue about dumping the correct stack trace when an error is re-thrown. +- [browser#1106](https://github.com/grafana/xk6-browser/pull/1106) fixes an NPE on NavigateFrame when navigate occurs in the same document. +- [browser#1096](https://github.com/grafana/xk6-browser/pull/1096) fixes a panic when trying to interact within nested `iframe`s. Thanks, @bandorko! + +## Maintenance and internal improvements + +- [#3378](https://github.com/grafana/k6/pull/3378) fixes usage of `gh` in GitHub actions creating the OSS release. +- [#3386](https://github.com/grafana/k6/pull/3386), [#3387](https://github.com/grafana/k6/pull/3387), [#3388](https://github.com/grafana/k6/pull/3388), [browser#1047](https://github.com/grafana/xk6-browser/pull/1047) update dependencies. +- [#3393](https://github.com/grafana/k6/pull/3393), [#3399](https://github.com/grafana/k6/pull/3399) fix lint issues in the `js` package. +- [#3381](https://github.com/grafana/k6/pull/3381) disables temporarily ARM tests on GitHub Actions. +- [#3401](https://github.com/grafana/k6/pull/3401), [#3469](https://github.com/grafana/k6/pull/3469) refactors a Makefile, removes `make ci-like-lint` in favor of `make lint`. Updates a golangci-lint version to v1.55.2. +- [#3410](https://github.com/grafana/k6/pull/3410) fixes the `tests` reference in the all rule of the Makefile. Thanks, @flyck! +- [#3402](https://github.com/grafana/k6/pull/3402) adds a test-case for the `k6 cloud`. +- [#3421](https://github.com/grafana/k6/pull/3421) updates dependencies for xk6 integration tests. +- [browser#1075](https://github.com/grafana/xk6-browser/pull/1075), [browser#1076](https://github.com/grafana/xk6-browser/pull/1076) refactors `clearPermissions` and `grantPermissions`. +- [browser#1043](https://github.com/grafana/xk6-browser/pull/1043) refines tests. +- [browser#1069](https://github.com/grafana/xk6-browser/pull/1069), [browser#1090](https://github.com/grafana/xk6-browser/pull/1090) refactor internal. +- [browser#1102](https://github.com/grafana/xk6-browser/pull/1102) uses `force` and `noWaitAfter` in `frame.newAction`. +- [#3443](https://github.com/grafana/k6/pull/3443) mentions that k6-core team aims to support the last two major golang versions for building a k6 binary. +- [#3437](https://github.com/grafana/k6/pull/3437) switches k6 cloud traces to a new hostname. +- [#3429](https://github.com/grafana/k6/pull/3429) increases timeout expectations for the `TestSetupTimeout` test. +- [#3446](https://github.com/grafana/k6/pull/3446) moves log tokenizer to `lib/strvals` package. + +## Roadmap + +### Graduating from experimental + +It has been a while since we've introduced the `k6/experimental` namespace. This namespace was specifically created to test new features before we fully committed to them. Thanks to it, we have been able to iterate on features and receive valuable feedback from the community before adding them to the core of k6. + +In the following releases, we're going to graduate `k6/experimental/grpc` and `k6/experimental/timers`. + +These modules' "experimental" versions will remain available for a couple of releases, but the goal is to remove the "experimental" imports for them in favor of the core-only imports. + +### New dashboard features + +We're happy to announce our work on a new, upcoming dashboard feature. Based on the [xk6-dashboard](https://github.com/grafana/xk6-dashboard) extension, this upcoming feature will enable you to visualize your test runs and their results in your web browser, in real time. The k6 maintainers team is starting to work towards its integration into the core of k6, and we're aiming to release it in the next couple of releases. + +While the final user-experience might differ, you can already try it out by following the instructions in the [xk6-dashboard](https://github.com/grafana/xk6-dashboard) repository. We update the extension on a regular basis as we're converging towards the first release of the feature in k6. Go ahead and give it a try! Let us know what you think about it! diff --git a/docs/sources/next/release-notes/v0.49.0.md b/docs/sources/next/release-notes/v0.49.0.md new file mode 100644 index 0000000000..619b64ba6a --- /dev/null +++ b/docs/sources/next/release-notes/v0.49.0.md @@ -0,0 +1,209 @@ +--- +title: Grafana k6 version 0.49.0 release notes +menuTitle: v0.49.0 +description: The release notes for Grafana k6 version 0.49.0 +weight: 9998 +canonical: https://github.com/grafana/k6/blob/master/release%20notes/v0.49.0.md +--- + +# Grafana k6 version 0.49.0 release notes + +k6 `v0.49.0` is here πŸŽ‰! This release: + +- Adds a built-in [web dashboard](https://grafana.com/docs/k6/latest/results-output/web-dashboard/) that displays test results in real time. +- Introduces `clear` functionality to the browser module's `locator` classes. +- Merges the gRPC experimental module back into the gRPC core module. +- Enables the ability to get the selection from an element in `k6/html`. +- Collects internal modules and outputs used by a script. +- Prepares `k6/experimental/timers` for stabilization. + +## Breaking changes + +- [#3494](https://github.com/grafana/k6/pull/3494) stops updating `loadimpact/k6` docker image. If you still use it, please migrate to the [grafana/k6](https://hub.docker.com/r/grafana/k6) image. +- [browser#1111](https://github.com/grafana/xk6-browser/pull/1111) removes `timeout` option for `isVisible` and `isHidden` since the API no longer waits for the element to appear on the page. + +## New features + +### Web Dashboard + +The new [web dashboard](https://grafana.com/docs/k6/latest/results-output/web-dashboard/) brings real-time visualization to load testing. This feature allows users to monitor test progress and analyze +results dynamically, enhancing the overall testing experience. + +#### Real-time test results + +Activate this feature using the environment variable `K6_WEB_DASHBOARD=true`. For this initial release, the dashboard is not enabled by default to allow users to opt into this new experience as it evolves. + +```bash +K6_WEB_DASHBOARD=true k6 run script.js +``` + +Once enabled and the test script is running, navigate to [http://localhost:5665](http://localhost:5665) in your web browser to access the dashboard. + +![k6 Web Dashboard Overview](https://github.com/grafana/xk6-dashboard/blob/master/screenshot/k6-dashboard-overview-light.png?raw=true) + +#### Test report + +The web dashboard also offers an HTML test report (see [an example](https://github.com/grafana/xk6-dashboard/blob/master/screenshot/k6-dashboard-html-report-screen-view.png?raw=true)) for detailed analysis, enabling easy sharing and downloading capabilities for +collaboration. + +To access and download the report, click on the **Report** button in the dashboard's top right corner or use the `K6_WEB_DASHBOARD_EXPORT` environment variable. + +```bash +K6_WEB_DASHBOARD=true K6_WEB_DASHBOARD_EXPORT=test-report.html k6 run script.js +``` + +### Add `clear` to the `locator` class [browser#1149](https://github.com/grafana/xk6-browser/pull/1149) + +The new `clear` method on the `locator` class clears the text boxes and input fields. This is useful when navigating to a website where the text boxes and input fields already contain a value that needs to be cleared before filling it with a specific value. + +
+ Expand to see an example of the new functionality. + +```javascript +import { check } from 'k6'; +import { browser } from 'k6/experimental/browser'; + +export const options = { + scenarios: { + ui: { + executor: 'shared-iterations', + options: { + browser: { + type: 'chromium', + }, + }, + }, + }, +}; + +export default async function () { + const context = browser.newContext(); + const page = context.newPage(); + + await page.goto('https://test.k6.io/my_messages.php', { waitUntil: 'networkidle' }); + + // To mimic an input field with existing text. + page.locator('input[name="login"]').type('admin'); + + check(page, { + not_empty: (p) => p.locator('input[name="login"]').inputValue() != '', + }); + + // Clear the text. + page.locator('input[name="login"]').clear(); + + check(page, { + empty: (p) => p.locator('input[name="login"]').inputValue() == '', + }); + + page.close(); +} +``` + +
+ +### Add tracing to the browser module [browser#1100](https://github.com/grafana/xk6-browser/pull/1100) + +The browser module now generates traces that provide a representation of its inner workings, such as API methods executed (for example `browser.newPage` and `page.goto`), page navigations, and [Web Vitals](https://grafana.com/docs/k6/latest/using-k6-browser/metrics/#googles-core-web-vitals) measurements. + +Currently, the instrumented methods are a subset of all the methods exposed by the browser module API, but this will be extended in the future. + +The traces generation for the browser module depends on the overall `k6` traces option introduced in [v0.48.0](https://github.com/grafana/k6/releases/tag/v0.48.0). Check out the [documentation](https://grafana.com/docs/k6/latest/using-k6/k6-options/reference/#traces-output) to learn more about it. + +### gRPC streaming API becomes part of the k6 core [#3490](https://github.com/grafana/k6/pull/3490) + +With this release, gRPC's streaming API becomes part of the core's `k6/net/grpc` module. The experimental `k6/experimental/grpc` has been back-merged into the core. + +You can still use import `k6/experimental/grpc` for a couple of releases, but it's deprecated and will be removed in the future (planned in k6 version `v0.51.0`). + +To migrate your scripts, replace `k6/experimental/grpc` with `k6/net/grpc` in your script imports, and the code should work as before. + +### k6/html: Extract selection from element [#3519](https://github.com/grafana/k6/pull/3519) + +[`k6/html`](https://grafana.com/docs/k6/latest/javascript-api/k6-html/) has been around for a while and allows you to search within an HTML document with a jQuery-like API called [Selection](https://grafana.com/docs/k6/latest/javascript-api/k6-html/selection/), and also has support for the more standard [Element](https://grafana.com/docs/k6/latest/javascript-api/k6-html/element/) that represents DOM element. + +For a long time, you could get an Element from a Selection using the [`.get(index)`](https://grafana.com/docs/k6/latest/javascript-api/k6-html/selection/selection-get/), but you couldn't get back to a Selection from an Element. + +This is not a common case, but one that requires quite a bit of code. For example, see the following jQuery snippet: + +```javascript +let li = http.get('https://test.k6.io').html().find('li'); +li.each(function (_, element) { + // here element is an element not a selection + // but what if for each li we want to select something more? + // in jquery that will be: + let container = $(element).closest('ul.header-icons'); + // but what should `$` do? + // in a browser there is only 1 html document that you have access to + // in k6 though you can be working with multiple ones, so `$` can't know which one it should + // work against +}); +``` + +In order to support the above example, you can use `selection`, without going to the element: + +```javascript +let li = http.get('https://test.k6.io').html().find('li'); +for (; li.size() > 0; li = li.next()) { + let ul = li.closest('ul.header-icons'); // li here is still a selection and we iterate over it. +} +``` + +This is not always possible though, and arguably isn't what most users will naturally do. + +Because of this, we have now added a new [`.selection()`](https://grafana.com/docs/k6/latest/javascript-api/k6-html/element/element-selection/) which returns a selection for its element. + +```javascript +let li = http.get('https://test.k6.io').html().find('li'); +li.each(function (_, element) { + let container = element.selection().closest('ul.header-icons'); + // .. more code +}); +``` + +Thanks to @Azhovan! :bow: :tada: + +### Collect usage data on imported internal modules and outputs [#3525](https://github.com/grafana/k6/pull/3525) + +k6 now collects usage data of the modules and outputs that are being used when the [usage report](https://grafana.com/docs/k6/latest/misc/usage-collection) is enabled. The data collection is only related to the built-in k6 modules and outputs. Private, custom modules and extensions [are never collected](https://github.com/grafana/k6/blob/f35e67902605877ebf2c5e9c8673cd7faf4cdc1e/cmd/report.go#L33-L57). The usage report is enabled by default in k6, but it is possible to opt-out using the [no-usage-report](https://grafana.com/docs/k6/latest/using-k6/k6-options/reference/#no-usage-report) option. + +We always want to improve the product, but at the same time, we need to pay attention to where we allocate our resources. Having data of what are the most used modules and outputs gives us better confidence to make decisions because we are supported by data. +The data can let us know what percentage of our users will benefit from the introduction of a new feature and also, how many of them would be impacted in case of a breaking change. + +## UX improvements and enhancements + +- [#3529](https://github.com/grafana/k6/pull/3529) enables the k6 cloud traces output by default. +- [#3440](https://github.com/grafana/k6/pull/3440) adds a fallback for using built-in certificates if the OS provides none. Thanks to `@mem` for working on it! +- [browser#1104](https://github.com/grafana/xk6-browser/pull/1104) adds support for browser module traces metadata. Users can define _key-value_ metadata that will be included as attributes in every generated span. +- [browser#1135](https://github.com/grafana/xk6-browser/pull/1135) improves the array output from `console` in the k6 logs. +- [browser#1137](https://github.com/grafana/xk6-browser/pull/1137), [browser#1145](https://github.com/grafana/xk6-browser/pull/1145) improves the error messages displayed when Chrome or Chromium isn't found. +- [#3543](https://github.com/grafana/k6/pull/3543) replaces documentation URLs to `grafana.com/docs/k6/latest/`. + +## Bug fixes + +- [#3485](https://github.com/grafana/k6/pull/3485) fixes the REST API always logging a 200 status code response, which was found as part of fixing lint issues in the code. +- [browser#1129](https://github.com/grafana/xk6-browser/pull/1129) mitigates the risk of panics when the website under test uses the `console`. +- [browser#1133](https://github.com/grafana/xk6-browser/pull/1133) fixes `BigInt` parsing. +- [browser#1108](https://github.com/grafana/xk6-browser/pull/1108), [browser#1110](https://github.com/grafana/xk6-browser/pull/1110) fixes `isVisible` and `isHidden` so that it doesn't wait for an element to match with the given `selector`, allowing it to continue on with the test script when elements are not on the page. +- [browser#1121](https://github.com/grafana/xk6-browser/pull/1121) fixes `dblClick` so that it works with `onDblClick` and performs two clicks on the specified element. +- [browser#1152](https://github.com/grafana/xk6-browser/pull/1152) fixes a nil pointer dereference when navigating around on SPA websites. + +## Maintenance and internal improvements + +- [#3204](https://github.com/grafana/k6/pull/3204) internal refactor to make future distributed execution work easier. With a small fix to tests in [#3531](https://github.com/grafana/k6/pull/3531). Thanks to @na-- :tada:. +- Lint fixes throughout the k6 code base [#3460](https://github.com/grafana/k6/pull/3460), [#3462](https://github.com/grafana/k6/pull/3462), [#3463](https://github.com/grafana/k6/pull/3463), [#3478](https://github.com/grafana/k6/pull/3478), [#3479](https://github.com/grafana/k6/pull/3479), [#3480](https://github.com/grafana/k6/pull/3480), [#3481](https://github.com/grafana/k6/pull/3481), [#3482](https://github.com/grafana/k6/pull/3482), [#3483](https://github.com/grafana/k6/pull/3483), [#3484](https://github.com/grafana/k6/pull/3484), [#3485](https://github.com/grafana/k6/pull/3485), [#3495](https://github.com/grafana/k6/pull/3495). +- [#3473](https://github.com/grafana/k6/pull/3473) refinements to the release process. +- Dependency updates across k6 [#3500](https://github.com/grafana/k6/pull/3500), [#3501](https://github.com/grafana/k6/pull/3501), [#3502](https://github.com/grafana/k6/pull/3502), [#3503](https://github.com/grafana/k6/pull/3503), [#3509](https://github.com/grafana/k6/pull/3509), [#3513](https://github.com/grafana/k6/pull/3513), [#3537](https://github.com/grafana/k6/pull/3537), [#3539](https://github.com/grafana/k6/pull/3539), [#3540](https://github.com/grafana/k6/pull/3540). +- [#3489](https://github.com/grafana/k6/pull/3489) migrates pull-requests assignment to `CODEOWNERS` from GitHub Action. +- [#3496](https://github.com/grafana/k6/pull/3496) checks for security issues with a scheduled trivy scan. +- [#3517](https://github.com/grafana/k6/pull/3517) adds unit tests to the cloadapi package. This is the first contribution by external contributor @nilskch. Thanks for this @nilskch :bow:. +- [#3520](https://github.com/grafana/k6/pull/3520) stops using deprecated by golang net.Dialer.DualStack option. +- [#3526](https://github.com/grafana/k6/pull/3526) refactors to JavaScript package test around `open` and `require` and their handling of paths. +- [#3527](https://github.com/grafana/k6/pull/3527) generates test certificates for more tests during the test. This, among other things, fixes macOS tests. +- [#3528](https://github.com/grafana/k6/pull/3528) enables macOS tests in GitHub Actions. +- [browser#1134](https://github.com/grafana/xk6-browser/pull/1134) adds a new error type when parsing objects. +- [browser#1107](https://github.com/grafana/xk6-browser/pull/1107), [browser#1109](https://github.com/grafana/xk6-browser/pull/1109) refactor internals. + +## Roadmap + +As mentioned earlier, there's work in progress to make xk6-timers stable as part of the next release. You can find more information on issue [#3297](https://github.com/grafana/k6/issues/3297). diff --git a/docs/sources/next/release-notes/v0.50.0.md b/docs/sources/next/release-notes/v0.50.0.md new file mode 100644 index 0000000000..efb2a38ecf --- /dev/null +++ b/docs/sources/next/release-notes/v0.50.0.md @@ -0,0 +1,183 @@ +--- +title: Grafana k6 version 0.50.0 release notes +menuTitle: v0.50.0 +description: The release notes for Grafana k6 version 0.50.0 +weight: 9997 +canonical: https://github.com/grafana/k6/blob/master/release%20notes/v0.50.0.md +--- + +# Grafana k6 version 0.50.0 release notes + +k6 `v0.50.0` is here πŸŽ‰! + +This release: + +- Adds support for uploading files from the browser module. +- Introduces the `options.cloud` option. +- Stabilizes the previously experimental timers module as the `k6/timers` module. +- Brings JSON Web Key support to the `k6/experimental/webcrypto` module. + +## Breaking changes + +- [websockets#60](https://github.com/grafana/xk6-websockets/pull/60) allows manually setting the `name` tag, which also overwrites the `url` tag with the `name` value. This change makes it consistent with the logic that was implemented in k6 v0.41. Thanks, @mkadirtan for contributing! + +### Browser APIs to Async + +In future releases, we are going to be moving most of the synchronous browser APIs to asynchronous ones (promisifying them). We expect this will affect most of our users, so we are posting this upfront before making the change. Here are the reasons for making this large breaking change: + +1. Most browser APIs use some form of long-running IO operation (networking) to perform the requested action on the web browser against the website under test. We need to avoid blocking JavaScript's runtime event loop for such operations. +2. We're going to add more asynchronous event-based APIs (such as [page.on](https://github.com/grafana/xk6-browser/issues/1227)) that our current synchronous APIs would block. +3. To align with how developers expect to work with JavaScript APIs. +4. To have better compatibility with Playwright. + +You can find a list of all the APIs that we expect to convert to async in a comment in issue [browser#428](https://github.com/grafana/xk6-browser/issues/428#issuecomment-1964020837). + +Awaiting on something that’s not a thenable just returns that value, which means you can add the `await` keyword against APIs that will become async to future proof your test scripts. + +## New features + +### Add support for uploading files from the browser module [browser#1097](https://github.com/grafana/xk6-browser/pull/1097), [browser#1244](https://github.com/grafana/xk6-browser/pull/1244) + +You can now upload files using the available input forms on the website under test. The new API is `setInputFiles` which can be called from a `page`, `frame` or `elementHandle` types. It can upload one or more files encoded in the test script. To upload files from the local file system, work with the [experimental fs module](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/fs/). + +
+Expand to see the examples. + +For the following examples, we will use the HTML file: + +```html + + +
+ + +
+ + +``` + +Uploading a file can be achieved with the following script: + +```js +// Import the k6 encoder module. +import encoding from 'k6/encoding'; +... +export default async function () { + const page = browser.newPage(); + + await page.goto(url) + + // Encode and upload some data into a plain text file called test.txt. + page.setInputFiles('input[id="upload"]', { name: 'test.txt', mimetype: 'text/plain', buffer: encoding.b64encode('Hello World') }) + + // Click on the submit button on the form to upload the file. + const submitButton = page.locator('input[type="submit"]') + await Promise.all([page.waitForNavigation(), submitButton.click()]) + + page.close(); +} +``` + +Uploading multiple files can be done with the use of an array: + +```js +page.setInputFiles('input[id="upload"]', [ + { name: 'test.txt', mimetype: 'text/plain', buffer: encoding.b64encode('Hello World') }, + { + name: 'test.json', + mimetype: 'text/json', + buffer: encoding.b64encode('{"message": "Hello World"}'), + }, +]); +``` + +
+ +Thanks to @bandorko! :bow: :tada: + +### Introducing options.cloud [#3348](https://github.com/grafana/k6/pull/3348), [#3407](https://github.com/grafana/k6/pull/3407) + +In this release, we introduce a new way of defining cloud options. From now on, you can use `options.cloud` instead of `options.ext.loadimpact`. + +To migrate, you can move the `loadimpact` object to the root of the `options` object and rename it to `cloud`. For example: + +```javascript +export let options = { + ext: { + loadimpact: { + name: 'Legacy way of defining cloud options', + projectID: 12345, + }, + }, +}; + +export let options = { + cloud: { + name: 'Current way of defining cloud options', + projectID: 12345, + }, +}; +``` + +All scripts with legacy `options.ext.loadimpact` will continue to function as before. There's no planned sunset date for the legacy option, but we highly encourage using `options.cloud` going forward. For more details about cloud options, refer to [Cloud options](https://grafana.com/docs/grafana-cloud/k6/author-run/cloud-scripting-extras/cloud-options/). + +### Timers API becomes part of the k6 core [#3587](https://github.com/grafana/k6/pull/3587) + +With this release, the timers API is no longer experimental and can be imported as `k6/timers` instead of as `k6/experimental/timers`. The later will be supported until `v0.52.0`. + +You can also contribute to the discussion on making the current timer exports globally available in [#3589](https://github.com/grafana/k6/issues/3589), or just give it a :+1:. + +### JSON Web Key support in `k6/experimental/webcrypto` module [webcrypto#61](https://github.com/grafana/xk6-webcrypto/pull/61) + +The experimental webcrypto module now supports the JSON Web Key (JWK) format, using the `importKey` and `exportKey` methods. + +This allows you to import and export keys in the JWK format for the supported algorithms. + +```js +const generatedKey = await crypto.subtle.generateKey({ name: 'AES-CBC', length: '256' }, true, [ + 'encrypt', + 'decrypt', +]); + +const exportedKey = await crypto.subtle.exportKey('jwk', generatedKey); +``` + +## UX improvements and enhancements + +- [browser#1197](https://github.com/grafana/xk6-browser/pull/1197), [browser#1202](https://github.com/grafana/xk6-browser/pull/1202), [browser#1203](https://github.com/grafana/xk6-browser/pull/1203), [browser#1221](https://github.com/grafana/xk6-browser/pull/1221) adds the ability to upload screenshots to a remote location. +- [browser#1209](https://github.com/grafana/xk6-browser/pull/1209) adds a shadow DOM usage example. +- [browser#1233](https://github.com/grafana/xk6-browser/pull/1233) returns actionable errors for `evaluate` APIs. +- [browser#1228](https://github.com/grafana/xk6-browser/pull/1228), [browser#1232](https://github.com/grafana/xk6-browser/pull/1232), [browser#1235](https://github.com/grafana/xk6-browser/pull/1235) injects the `testRunId` into the `window.k6` object for external applications to query (for example, Grafana Faro). + +### Browser Context Isolation [browser#1112](https://github.com/grafana/xk6-browser/issues/1112) + +With this release, we have overhauled and (tremendously) improved the performance and stability of the browser module. It's now possible to run tests with a larger number of VUs concurrently without any performance issues. Previously, when running tests with multiple VUs concurrently, each VU's browser context would attach to the pages from the other VUs' browser contexts. This led to unexpected behavior and performance issues and, to an extent, reduced the module's capability to run multi-VU tests. + +## Bug fixes + +- [#3653](https://github.com/grafana/k6/pull/3653) fixes a connectivity issue with non-lowercase `options.hosts`. +- [browser#1215](https://github.com/grafana/xk6-browser/pull/1215) fixes a data race during logging that panics. +- [browser#1238](https://github.com/grafana/xk6-browser/pull/1238) fixes fill functionality for textarea. Thanks @bandorko for the fix! :bow: :tada: +- [browser#1242](https://github.com/grafana/xk6-browser/pull/1242) fixes XPath evaluation on `DocumentFragment`. + +## Maintenance and internal improvements + +- [browser#1164](https://github.com/grafana/xk6-browser/pull/1164), [browser#1166](https://github.com/grafana/xk6-browser/pull/1166), [browser#1171](https://github.com/grafana/xk6-browser/pull/1171), + [browser#1173](https://github.com/grafana/xk6-browser/pull/1173), [browser#1175](https://github.com/grafana/xk6-browser/pull/1175), [browser#1179](https://github.com/grafana/xk6-browser/pull/1179), + [browser#1183](https://github.com/grafana/xk6-browser/pull/1183), [browser#1186](https://github.com/grafana/xk6-browser/pull/1186), [browser#1188](https://github.com/grafana/xk6-browser/pull/1188), + [browser#1189](https://github.com/grafana/xk6-browser/pull/1189), [browser#1190](https://github.com/grafana/xk6-browser/pull/1190), [browser#1191](https://github.com/grafana/xk6-browser/pull/1191), + [browser#1193](https://github.com/grafana/xk6-browser/pull/1193), [browser#1163](https://github.com/grafana/xk6-browser/pull/1163), [browser#1205](https://github.com/grafana/xk6-browser/pull/1205), + [browser#1217](https://github.com/grafana/xk6-browser/pull/1217) refactors internals to improve stability. +- [browser#850](https://github.com/grafana/xk6-browser/pull/850), [browser#1211](https://github.com/grafana/xk6-browser/pull/1211), [browser#1212](https://github.com/grafana/xk6-browser/pull/1212), + [browser#1214](https://github.com/grafana/xk6-browser/pull/1214), [browser#1216](https://github.com/grafana/xk6-browser/pull/1216) refactors to work with errors.Join and sets the minimum Go version to 1.20. +- [browser#1220](https://github.com/grafana/xk6-browser/pull/1220) adds more logging. +- [browser#1112](https://github.com/grafana/xk6-browser/issues/1112) fixes deadlock issues when running multiple VUs, iterations, and Chrome instances. +- [browser#1246](https://github.com/grafana/xk6-browser/issues/1246) removes logging of in-flight requests when a request fails. +- [#3586](https://github.com/grafana/k6/pull/3586) fixes file traversal for the test. +- [#3588](https://github.com/grafana/k6/pull/3588) updates `codeql` GitHub action to v3. + +* [webcrypto#62](https://github.com/grafana/xk6-webcrypto/pull/62) fixes display error message in the console and does minor maintenance. +* [webcrypto#60](https://github.com/grafana/xk6-webcrypto/pull/60) leverages some of the k6 APIs to handle JavaScript operations. +* [webcrypto#59](https://github.com/grafana/xk6-webcrypto/pull/59) makes `newTestSetup` rely on k6's modulestest. +* [webcrypto#58](https://github.com/grafana/xk6-webcrypto/pull/58) addresses linter issues related to repeated static strings. +* [3633](https://github.com/grafana/k6/pull/3633) updates k6 dependencies. diff --git a/docs/sources/next/release-notes/v0.51.0.md b/docs/sources/next/release-notes/v0.51.0.md new file mode 100644 index 0000000000..2165aa14be --- /dev/null +++ b/docs/sources/next/release-notes/v0.51.0.md @@ -0,0 +1,295 @@ +--- +title: Grafana k6 version 0.51.0 release notes +menuTitle: v0.51.0 +description: The release notes for Grafana k6 version 0.51.0 +weight: 9996 +canonical: https://github.com/grafana/k6/blob/master/release%20notes/v0.51.0.md +--- + +# Grafana k6 version 0.51.0 release notes + +k6 `v0.51.0` is here πŸŽ‰! Some special mentions included in this release: + +- [A new experimental streams module](#introduction-of-k6experimentalstreams-module-3696) +- [New algorithms for WebCrypto module](#new-features-and-updates-of-webcrypto-api-support-3714) +- [Timers are globally available](#timers-globally-available-3589) + +## Breaking changes + +### Transition browser APIs to Async + +In the last release notes [we mentioned](https://github.com/grafana/k6/blob/master/release%20notes/v0.50.0.md#browser-apis-to-async) this breaking change, and we wanted to remind and update you on the plan. In the **next** release (v0.52.0), most of the synchronous browser APIs will be migrated to be asynchronous (promisifying them). We expect this will affect most if not all of our users. + +This breaking change will require you to add `await` in front of most of the browser module APIs. Without this `await` you will witness undocumented and unknown behavior during the runtime. To make the migration simpler we advise that you work with the latest [k6 type definitions](https://grafana.com/docs/k6/latest/set-up/configure-k6-intellisense/). + +You can find a list of all the APIs that we expect to convert to async in a comment in issue [browser#428](https://github.com/grafana/xk6-browser/issues/428#issuecomment-1964020837). + +Awaiting on something that’s not a thenable just returns that value, which means you can add the `await` keyword today on the APIs that will become async to future proof your test scripts. + +Here are the reasons for making this large breaking change: + +1. Most browser APIs use some form of long-running IO operation (networking) to perform the requested action on the web browser against the website under test. We need to avoid blocking JavaScript's runtime event loop for such operations. +2. We're going to add more asynchronous event-based APIs (such as [page.on](https://github.com/grafana/xk6-browser/issues/1227)) that our current synchronous APIs would block. +3. To align with how developers expect to work with JavaScript APIs. +4. To have better compatibility with Playwright. + +As a starting point, we have migrated a single API (the `tap` method), which you can find the details below that will help visualize the upcoming breaking changes. + +### Browser `Tap` is now an async method grafana/xk6-browser#1268 + +This release converts the `Tap` method in the `browser` module into an asynchronous method. This change is necessary to ensure that the method can be used in async contexts and to align with the rest of the browser module's planned asynchronous API. To use the `Tap` method, you must now add the `await` keyword before the method call. + +Affected components: + +- [`locator.tap`](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/browser/locator/tap/) +- [`page.tap`](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/browser/page/tap/) +- [`frame.tap`](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/browser/frame/) +- [`elementHandle.tap`](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/browser/elementhandle/) + +See the following example for how to use the `Tap` method after this change: + +**Before**: + +```javascript +import browser from 'k6/experimental/browser'; + +// ... + +export default function () { + // ... + page.tap(selector, { modifiers: ['Alt', 'Control', 'Meta', 'Shift'] }); + // ... +} +``` + +**After**: + +```javascript +import browser from 'k6/experimental/browser' + +// ... + +export default function () { + // ... + await page.tap(selector, { modifiers: ["Alt", "Control", "Meta", "Shift"] }); + // ... +} +``` + +### `k6/experimental/websockets` will not default `binaryType` to `"arraybuffer"' + +As part of the stabilization of the API it needs to become as close to the specification. + +Early in the development the idea of adding `Blob` support as part was deemed feature creep and was dropped in favor of going with only `"arraybuffer"`. But the specification defaults to returning binary responses as `Blob` - which was another thing that was changed. + +While adding `Blob` is still on our radar, moving the default is always going to be a breaking change that we need to do to align with the specification. + +For this release there is now a warning that will be printed if `binaryType` is not set to `"arraybuffer"` _and_ a binary response is received. The warning will go away when `binaryType` is set to `"arraybuffer"`. + +In the next release the warning will become an error. + +More info and place for discussion can be found in an [this issue](https://github.com/grafana/xk6-websockets/issues/67). + +### `k6/experimental/grpc` is no longer available [#3530](https://github.com/grafana/k6/pull/3530) + +As the last step of the graduation process for the experimental gRPC module, we completely removed the module. It is now fully integrated into the stable `k6/net/grpc` module. So, if you haven't done this yet, replace your imports from `k6/experimental/grpc` to `k6/net/grpc`. + +### Deprecations + +The following pull requests start the process to introduce breaking changes. They are currently starting to emit warning if their condition is hit, but they will turn to return errors in the future release. +It is recommended to use the suggested alternative, or to fix the script if you see the warning message. + +- [#3681](https://github.com/grafana/k6/pull/3681) Use of not-compliant `require` expressions. +- [#3680](https://github.com/grafana/k6/pull/3680) Modules resolution of modules not previously seen during the initialization phase. +- [#3676](https://github.com/grafana/k6/pull/3676) Working directory is set to the current location when the script is provided using stdin, instead of the root folder. +- [#3530](https://github.com/grafana/k6/pull/3671) Automagically resolve modules from cdnjs and github "URLs". + +## New features + +### Introduction of `k6/experimental/streams` module [#3696](https://github.com/grafana/k6/pull/3696) + +This release of k6 introduces the new `k6/experimental/streams` module, which partially supports the JavaScript +Streams API, focusing initially on the `ReadableStream` construct. + +With the `ReadableStream`, users can define and consume data streams within k6 scripts. This is particularly useful for +efficiently handling large datasets or for processing data sequentially in a controlled flow. + +
+ Expand to see an example of stream's usage + +The following example demonstrates creating and consuming a simple stream that emits numbers until it reaches a predefined limit: + +```javascript +import { ReadableStream } from 'k6/experimental/streams'; + +function numbersStream() { + let currentNumber = 0; + + return new ReadableStream({ + start(controller) { + const fn = () => { + if (currentNumber < 5) { + controller.enqueue(++currentNumber); + setTimeout(fn, 1000); + return; + } + + controller.close(); + }; + setTimeout(fn, 1000); + }, + }); +} + +export default async function () { + const stream = numbersStream(); + const reader = stream.getReader(); + + while (true) { + const { done, value } = await reader.read(); + if (done) break; + console.log(`received number ${value} from stream`); + } + + console.log('we are done'); +} +``` + +
+ +For more advanced examples, please head to the MDN Web Docs on the [Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API). + +#### Limitations + +Currently, users can define and consume readable streams. However, this release does not include support for byte readers +and controllers, nor does it include support the `tee`, `pipeTo`, and +`pipeThrough` methods of the `ReadableStream` object. + +### New features and updates of WebCrypto API support [#3714](https://github.com/grafana/k6/pull/3714) + +This release brings support for asymmetric cryptography to the `k6/experimental/webcrypto` module. We added support of the elliptic curves algorithms ECDH ([xk6-webcrypto#67](https://github.com/grafana/xk6-webcrypto/pull/67)) and ECDSA ([xk6-webcrypto#69](https://github.com/grafana/xk6-webcrypto/pull/69)) algorithms along with new import/export key formats like `spki` and `pkcs8`. + +One of the newly added operations is `deriveBits`, which allows parties to generate a unique shared secret by using shared public and non-shared private keys. + +
+ Expand to see an example of generating a shared secret for Alice and Bob. + +```javascript +import { crypto } from 'k6/experimental/webcrypto'; + +export default async function () { + // Generate a key pair for Alice + const aliceKeyPair = await crypto.subtle.generateKey( + { + name: 'ECDH', + namedCurve: 'P-256', + }, + true, + ['deriveKey', 'deriveBits'] + ); + + // Generate a key pair for Bob + const bobKeyPair = await crypto.subtle.generateKey( + { + name: 'ECDH', + namedCurve: 'P-256', + }, + true, + ['deriveKey', 'deriveBits'] + ); + + // Derive shared secret for Alice + const aliceSharedSecret = await deriveSharedSecret(aliceKeyPair.privateKey, bobKeyPair.publicKey); + + // Derive shared secret for Bob + const bobSharedSecret = await deriveSharedSecret(bobKeyPair.privateKey, aliceKeyPair.publicKey); + + // alice shared secret and bob shared secret should be the same + console.log('alice shared secret: ' + printArrayBuffer(aliceSharedSecret)); + console.log('bob shared secret: ' + printArrayBuffer(bobSharedSecret)); +} + +async function deriveSharedSecret(privateKey, publicKey) { + return crypto.subtle.deriveBits( + { + name: 'ECDH', + public: publicKey, + }, + privateKey, + 256 + ); +} + +const printArrayBuffer = (buffer) => { + const view = new Uint8Array(buffer); + return Array.from(view); +}; +``` + +
+ +The `sign` and `verify` operations got support for ECDSA algorithm. The `sign` operation allows you to sign a message with a private key, while the `verify` operation allows you to verify the signature with a public key. + +Other notable updates and fixes: + +- [xk6-webcrypto#68](https://github.com/grafana/xk6-webcrypto/pull/68) fixes a degradation for the sign/verify operations for HMAC algorithm. +- [xk6-webcrypto#75](https://github.com/grafana/xk6-webcrypto/pull/75), [xk6-webcrypto#76](https://github.com/grafana/xk6-webcrypto/pull/76) refactor webcrypto module to be thread-safe. +- [xk6-webcrypto#74](https://github.com/grafana/xk6-webcrypto/pull/74) adds JWK import/export support for ECDH and ECDSA. Refactors JWK import/export to use only go standard library. + +See [webcrypto's module documentation](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/webcrypto/) for more details. + +### Timers globally available [#3589](https://github.com/grafana/k6/pull/3589) + +`setTimeout`, `setInterval` and related clear functions have been part of the JavaScript ecosystem, probably for as long as it has existed. + +In the previous releases we stabilized and made them available through `k6/timers` module. While the module isn't going anywhere and might get more identifiers, `setTimeout` is usually used without importing it. For this reason it is now globally available along `clearTimeout`, `setInterval` and `clearInterval`. + +No code needs to be changed, but you no longer need to import `k6/timers` to use this functionality. + +## UX improvements and enhancements + +- [#3670](https://github.com/grafana/k6/issues/3670) adds the ability to [enable profiling](https://grafana.com/docs/k6/latest/using-k6/k6-options/reference/#profiling-enabled) via environment variable. Thanks @Bablzz for your contribution! +- [#3655](https://github.com/grafana/k6/pull/3655) clarifies the error message for the validation of scenario's name. +- [#3693](https://github.com/grafana/k6/pull/3693) adds a gRPC client's `asyncInvoke` method to the `k6/net/grpc` module. It's [a non-blocking version](https://grafana.com/docs/k6/latest/javascript-api/k6-net-grpc/client/client-async-invoke/) of the `invoke` method. +- [browser#1259](https://github.com/grafana/xk6-browser/pull/1259), [browser#1260](https://github.com/grafana/xk6-browser/pull/1260) adds errors to the traces that the browser module generates. + +## Bug fixes + +- [#3708](https://github.com/grafana/k6/pull/3708) denies access to `execution.test.options` from Init context. +- [#3672](https://github.com/grafana/k6/pull/3672) picks the correct value when [SystemTags](https://grafana.com/docs/k6/latest/using-k6/k6-options/reference/#system-tags) are set via the `k6_SYSTEM_TAGS` environment variable. +- [#3657](https://github.com/grafana/k6/pull/3657) fixes a panic when `mappings` field is empty in the provided SourceMap. +- [#3717](https://github.com/grafana/k6/pull/3717) returns a correct line number when an inlined SourceMap is used. +- [browser#1261](https://github.com/grafana/xk6-browser/pull/1261) fixes dispose context canceled errors. +- [browser#1254](https://github.com/grafana/xk6-browser/pull/1254) fixes an indefinite wait when testing websites with iframes. +- [browser#1291](https://github.com/grafana/xk6-browser/pull/1291) fixes a panic on dispose of resources during a navigation. + +## Maintenance and internal improvements + +- [#3663](https://github.com/grafana/k6/pull/3663), [#3673](https://github.com/grafana/k6/pull/3673) updates several dependencies. +- [#3674](https://github.com/grafana/k6/pull/3674) updates the Go version, now k6 binary is built and tested using Go 1.22. +- [#3688](https://github.com/grafana/k6/pull/3688) updates the link to installation instructions for `golangci-lint` in the contribution guide. Thanks @yomek33 for your contribution! +- [browser#1262](https://github.com/grafana/xk6-browser/pull/1262) fixes a flaky test. +- [browser#1264](https://github.com/grafana/xk6-browser/pull/1264) removes unimplemented APIs. + +## Future plans + +### Use Blob as default value for WebSocket.binaryType + +As the changes in documentation mention, [`binaryType`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType) was by default set to `arraybuffer`, now instead it is `""` (empty string). +In a not so remote future, instead, we expect to introduce and use Blob object. + +### WebCrypto graduation + +WebCrypto got more features in the current release, and we expect to continue its expansion in the next iterations. Reaching a wider coverage will push WebCrypto module to being graduated as a stable module. + +### Streams API + +In the not so distant future, we have plans to start using the Streams API in existing modules. Our first iteration being adding a `.readable` property to the already existing [fs.File](https://grafana.com/docs/k6/latest/javascript-api/k6-experimental/fs/file) object. + +### Improve user experience for Cloud related commands + +In the near future, we intend to reiterate on `k6 cloud` and related commands to create a simplified and more ergonomic user experience. + +### Remove experimental timers module + +The `k6/experimental/timers` module is now part of the stable k6 API as `k6/timers` and via the globally available functions. The next release will make the experimental import no longer available. diff --git a/docs/sources/next/release-notes/v0.52.0.md b/docs/sources/next/release-notes/v0.52.0.md new file mode 100644 index 0000000000..15755f0ea5 --- /dev/null +++ b/docs/sources/next/release-notes/v0.52.0.md @@ -0,0 +1,145 @@ +--- +title: Grafana k6 version 0.52.0 release notes +menuTitle: v0.52.0 +description: The release notes for Grafana k6 version 0.52.0 +weight: 9995 +canonical: https://github.com/grafana/k6/blob/master/release%20notes/v0.52.0.md +--- + +# Grafana k6 version 0.52.0 release notes + +k6 `v0.52.0` is here πŸŽ‰! Some special mentions included in this release: + +- [We've switched to our own fork of `goja` named `sobek`](#switch-goja-to-our-own-fork-named-sobek-3775). +- [Panics are no longer captured](#panics-are-no-longer-being-captured-3777). +- [We've added experimental support for TypeScript and ES6+](#experimental-support-for-typescript-and-es6-using-esbuild-3738). +- `k6/browser` has [graduated from an experimental module](#k6browser-has-graduated-from-an-experimental-module-3793), and now has a [fully Async API](#k6browser-has-now-a-fully-async-api-browser428). + +## Breaking changes + +### Switch `goja` to our own fork named `sobek` [#3775](https://github.com/grafana/k6/pull/3775) + +To accelerate the development speed and bring ECMAScript Modules (ESM) support to k6 earlier (https://github.com/grafana/k6/issues/3265), +we have decided to create a fork of the [`goja`](https://github.com/dop251/goja/) project under the Grafana GitHub organization, +named [`sobek`](https://github.com/grafana/sobek). + +Starting on this release, k6 (and its extensions) now use `sobek` instead of the original `goja`, for all (of the +publicly exposed parts of the API) except for a couple of packages that are only used internally by k6. + +All k6 extensions linked in the docs have had a PR for this transition opened, as explained in this [comment](https://github.com/grafana/k6/issues/3773#issuecomment-2182113677). Any extension author who hasn't gotten a PR can follow the same steps. + +Find further details in [#3772](https://github.com/grafana/k6/issues/3772) and [#3773](https://github.com/grafana/k6/issues/3773). + +### Panics are no longer being captured [#3777](https://github.com/grafana/k6/pull/3777) + +Since this release, Go panics are no longer being captured by k6. This means that if a panic occurs while running a test, +the k6 process will crash, and the panic stack trace will be printed to the console. + +We decided to change this behavior because it's something that was left from the past as a safeguard, but it's not as +good as it might seem. For most cases with multiple goroutines/async, it's not enough and also makes a bunch of potential +bugs seem like less of an issue. + +Thus, this will help us to identify and fix bugs earlier, improve the overall stability of k6, and +most likely make the experience of developing k6 extensions friendlier. + +### `lib.State` no longer has `Group` [#3750](https://github.com/grafana/k6/pull/3750) + +As the result of refactoring the implementation of `group` and `check` methods, in order to decouple them, and thus +enable other future improvements, the `lib.State` object no longer has a `Group` field. + +This change should not affect most users, except for a couple of extensions, for which the use of `Group` was +already questionable: + +- `xk6-fasthttp` +- `xk6-g0` + +### Other breaking changes + +- [#3797](https://github.com/grafana/k6/pull/3797) starts using `-` as a special value for `--archive-out` to output the archive to stdout. +- [browser#1318](https://github.com/grafana/xk6-browser/pull/1318) makes the `Mouse.up` and `Mouse.down` methods no longer take x and y coordinates. Instead, they dispatch events on the current mouse position. + +## New features + +### Experimental support for TypeScript and ES6+ using esbuild [#3738](https://github.com/grafana/k6/pull/3738) + +This release of k6 introduces experimental support for TypeScript and ES6+ using esbuild, thanks to a new +[compatibility mode](https://grafana.com/docs/k6/latest/using-k6/javascript-typescript-compatibility-mode/) named `experimental_enhanced`. + +```sh +k6 run --compatibility-mode=experimental_enhanced script.js +``` + +With this new compatibility mode, the test source code is transformed using esbuild instead of Babel, which also means +that source files with the extension _".ts"_ are loaded by esbuild's TypeScript loader, which results in partial +TypeScript support: it removes the type information but doesn't provide type safety. + +### `k6/browser` has graduated from an experimental module [#3793](https://github.com/grafana/k6/pull/3793) + +The browser module is now available as `k6/browser` instead of `k6/experimental/browser`. The previous `k6/experimental/browser` module will be removed on September 23rd, 2024. Refer to [the migration guide](https://grafana.com/docs/k6/latest/using-k6-browser/migrating-to-k6-v0-52/) for more information on how to update your scripts. + +### `k6/browser` has now a fully Async API [browser#428](https://github.com/grafana/xk6-browser/issues/428) + +This release introduces a fully Async API for the `k6/browser` module. This means that nearly all the methods in the module now return promises. This change is part of the ongoing effort to make the browser module more user-friendly and easier to use. Please see [the browser documentation](https://grafana.com/docs/k6/latest/javascript-api/k6-browser) for more information on how to use the new Async API. + +Related Changes: + +- [browser#1310](https://github.com/grafana/xk6-browser/pull/1310), [browser#1311](https://github.com/grafana/xk6-browser/pull/1311), [browser#1312](https://github.com/grafana/xk6-browser/pull/1312), [browser#1316](https://github.com/grafana/xk6-browser/pull/1316), [browser#1328](https://github.com/grafana/xk6-browser/pull/1328), [browser#1337](https://github.com/grafana/xk6-browser/pull/1337), [browser#1367](https://github.com/grafana/xk6-browser/pull/1367), [browser#1366](https://github.com/grafana/xk6-browser/pull/1366), [browser#1314](https://github.com/grafana/xk6-browser/pull/1314), [browser#1332](https://github.com/grafana/xk6-browser/pull/1332), [browser#1323](https://github.com/grafana/xk6-browser/pull/1323), [browser#1355](https://github.com/grafana/xk6-browser/pull/1355), [browser#1348](https://github.com/grafana/xk6-browser/pull/1348), [browser#1364](https://github.com/grafana/xk6-browser/pull/1364) Migrates `Browser`, `BrowserContext`, `ElementHandle`, `Frame`, `JSHandle`, `Keyboard`, `Locator`, `Mouse`, `Page`, `Request`, `Response` APIs to async. + +## UX improvements and enhancements + +- [#3740](https://github.com/grafana/k6/pull/3740) enables k6 extensions to initialize `ReadableStream` objects from Go code (`io.Reader`). +- [#3798](https://github.com/grafana/k6/pull/3798) adjusts a severity level of a log message from `warn` to `debug` for cases when k6 can't detect the terminal's size. +- [#3797](https://github.com/grafana/k6/pull/3797) makes it possible to output the archive to stdout by using `-` as the `--archive-out`. Thanks to @roobre! :bow: :tada: +- [browser#1370](https://github.com/grafana/xk6-browser/issues/1370) makes the `GetAttribute` method now return `false` when the attribute is missing, making it easier to check for the presence of an attribute. +- [browser#1371](https://github.com/grafana/xk6-browser/issues/1371) makes the `TextContent` method now return `false` when the element's text content cannot be grabbed (like a JS `document`), making it easier to check for the presence of text content. +- [browser#1376](https://github.com/grafana/xk6-browser/pull/1376) makes `Request.headerValue` and `Response.headerValue` to be case-insensitive. +- [browser#1368](https://github.com/grafana/xk6-browser/pull/1368) enhances `await` usage in Javascript examples. +- [browser#1326](https://github.com/grafana/xk6-browser/pull/1326) adds forgotten `BrowserContext.browser` and `Page.context` mappings. +- [browser#1360](https://github.com/grafana/xk6-browser/pull/1360), [browser#1327](https://github.com/grafana/xk6-browser/pull/1327), [browser#1335](https://github.com/grafana/xk6-browser/pull/1335), [browser#1365](https://github.com/grafana/xk6-browser/pull/1365), [browser#1313](https://github.com/grafana/xk6-browser/pull/1313), [browser#1322](https://github.com/grafana/xk6-browser/pull/1322), [browser#1330](https://github.com/grafana/xk6-browser/pull/1330), [browser#1343](https://github.com/grafana/xk6-browser/pull/1343), [browser#1345](https://github.com/grafana/xk6-browser/pull/1345), [browser#1352](https://github.com/grafana/xk6-browser/pull/1352) turns the `Browser`, `BrowserContext`, `ElementHandle`, `JSHandle`, `Keyboard`, `Mouse`, `Locator`, and `Page` types' panics into errors for stability and better error handling. + +## Bug fixes + +- [#3774](https://github.com/grafana/k6/pull/3774) fixes a `require` warning for those tests using the stdin. +- [#3776](https://github.com/grafana/k6/pull/3776) fixes a panic caused by passing an undefined handler to timers. +- [#3779](https://github.com/grafana/k6/pull/3779) fixes a panic caused by registering an undefined handler in gRPC streams. +- [xk6-websockets#73](https://github.com/grafana/xk6-websockets/pull/73) fixes a panic caused by registering an undefined handler in WebSockets. +- [browser#1369](https://github.com/grafana/xk6-browser/pull/1369) improves `valueFromRemoteObject` `null` detection by returning a Go `nil` instead of `"null"` as a `string`. +- [browser#1386](https://github.com/grafana/xk6-browser/pull/1386) correctly handles empty string flags that don't have a value. +- [browser#1380](https://github.com/grafana/xk6-browser/pull/1380) ensures that `JSHandle.evaluate` and `JSHandle.evaluateHandle` both set themselves as the first argument. +- [browser#1346](https://github.com/grafana/xk6-browser/pull/1346) fixes an IFrame panic ("we either navigate top level or have old version of the navigated frame") that happens during navigation. +- [browser#1349](https://github.com/grafana/xk6-browser/pull/1349), [browser#1354](https://github.com/grafana/xk6-browser/pull/1354) fixes `Request` mappings. +- [browser#1334](https://github.com/grafana/xk6-browser/pull/1334) fixes an issue where clicking on a link that opens a new tab never navigates to the href link. +- [browser#1318](https://github.com/grafana/xk6-browser/pull/1318) fixes the `Mouse.move` to correctly dispatch a `down` event. +- [browser#1301](https://github.com/grafana/xk6-browser/pull/1301) fixes an error that occurs when working with a second tab and navigating to a URL. +- [browser#1387](https://github.com/grafana/xk6-browser/pull/1387) fixes a panic when the new document or request is missing. + +## Maintenance and internal improvements + +- [#3752](https://github.com/grafana/k6/pull/3752), [#3767](https://github.com/grafana/k6/pull/3767), [#3770](https://github.com/grafana/k6/pull/3770), [#3780](https://github.com/grafana/k6/pull/3780), [#3782](https://github.com/grafana/k6/pull/3782), [#3795](https://github.com/grafana/k6/pull/3795) updates several dependencies. +- [#3786](https://github.com/grafana/k6/pull/3786), [#3787](https://github.com/grafana/k6/pull/3787), [#3788](https://github.com/grafana/k6/pull/3788), [#3789](https://github.com/grafana/k6/pull/3789), [#3803](https://github.com/grafana/k6/pull/3803) updates experimental modules. +- [#3749](https://github.com/grafana/k6/pull/3749) stops printing `goja` stack traces on panics, which has been empty since a while. +- [#3760](https://github.com/grafana/k6/pull/3760) fixes race conditions in ramping-vus tests. +- [#3769](https://github.com/grafana/k6/pull/3769) removes a linter setting no longer used. +- [#3800](https://github.com/grafana/k6/pull/3800) adds test coverage for outputting the archive to stdout. +- [browser#1298](https://github.com/grafana/xk6-browser/pull/1298) splits browser mappings into separate files for better organization and maintainability. +- [browser#1321](https://github.com/grafana/xk6-browser/pull/1321) adds test helpers for async VU execution to reduce the boilerplate in the tests. +- [browser#1357](https://github.com/grafana/xk6-browser/pull/1357) updates `Group` and `Tag` usage for the latest k6. +- [browser#1361](https://github.com/grafana/xk6-browser/pull/1361) precalculates the browser version information to prevent I/O calls when the `version` and `userAgent` methods are called. This change allows the browser module to expose these methods as a sync API to be consistent with the Playwright's API. +- [browser#1377](https://github.com/grafana/xk6-browser/pull/1377) uses the `goja` fork called `sobek` in the browser module. +- [browser#1373](https://github.com/grafana/xk6-browser/pull/1373) provides sync and async APIs within the browser module for making the migration to the async API easier. + +## Roadmap + +### Native ECMAScript modules + +As mentioned above, the k6 team has forked [`goja`](https://github.com/dop251/goja/) into [`sobek`](https://github.com/grafana/sobek) and is currently working on [native ECMAScript modules support](https://github.com/grafana/k6/issues/3265). The current work in progress can be found in this [PR](https://github.com/grafana/k6/pull/3456) and any feedback is welcome. + +As part of that there likely will be some breaking changes due to the current not native support allowing stuff that shouldn't work. Like for example mixing [CommonJS](https://en.wikipedia.org/wiki/CommonJS) and ESM in the same file. Which is for example why we have added a [warning](https://github.com/grafana/k6/pull/3807) that it won't work. + +Support across multiple files is _also_ not standard but due to amount of users that seems to be mixing them _across_ files a lot of work has been done to support it. It is still likely that in the future warnings and potentially at some point future breaking changes will be enacted. + +### OpenTelemetry metrics output + +We're also happy to share that this release cycle, we've been working on [xk6-output-opentelemetry](https://grafana.com/docs/k6/latest/results-output/real-time/opentelemetry/), a k6 output extension that allows you to send k6 metrics to OpenTelemetry-compatible backends. We're looking for feedback from the community. If you're interested, please try it and let us know [via the extension repository](https://github.com/grafana/xk6-output-opentelemetry/issues)! + +Depending on the feedback, we plan to include this extension as an experimental output in the next k6 release. diff --git a/docs/sources/next/set-up/_index.md b/docs/sources/next/set-up/_index.md index 63d1f059af..e277826b50 100644 --- a/docs/sources/next/set-up/_index.md +++ b/docs/sources/next/set-up/_index.md @@ -1,5 +1,5 @@ --- -weight: 100 +weight: 175 title: Set up ---