Release Notes for v0.54.0

release notes/v0.54.0.md

@@ -0,0 +1,209 @@
+k6 `v0.54.0` is here 🎉! This release includes:
+
+- A new experimental CSV module
+- new ECMAScript features
+
+## Breaking changes
+
+- [#3913](https://github.com/grafana/k6/pull/3913) changes mapping of the Golang's `math/big.Int` type to `bigint` type in k6.
+- [#3922](https://github.com/grafana/k6/pull/3922) removes `lib.Min` and `lib.Max` from k6's Go API, which could affect custom extensions that rely on these functions.
+
+### (_optional h3_) `<big_breaking_change>` `#pr`
+
+## New features
+
+### New experimental CSV module for efficient CSV data handling [`#3743`](https://github.com/grafana/k6/pull/3743)
+
+We’ve added a new experimental csv module to k6 for more efficient and convenient CSV parsing and streaming, addressing the limitations of preexisting JavaScript-based solutions like [papaparse](https://www.papaparse.com/).
+
+#### What is it?
+
+The csv module offers two key features:
+
+* `csv.parse()` **Function**: Parses an entire CSV file at once into a [SharedArray](https://grafana.com/docs/k6/latest/javascript-api/k6-data/sharedarray/), using Go-based processing to using Go-based processing for faster parsing and lower memory usage compared to JavaScript alternatives.
+* `csv.Parser` **Class**: Provides a streaming parser to read CSV files line-by-line, minimizing memory consumption and offering more control over parsing through a stream-like API. This is ideal for scenarios where memory optimization or fine-grained control of the parsing process is crucial.
+
+#### Benefits for Users 
+
+* **Faster Parsing**: `csv.parse` bypasses most of the JavaScript runtime, offering significant speed improvements for large files.
+* **Lower Memory Usage**: both solution support shared memory across virtual users (VUs) with the `fs.open` function.
+* **Flexibility**: choose between full-file parsing with csv.parse() or memory-efficient streaming with csv.Parser.
+
+#### Tradeoffs
+
+* **`csv.Parse`**: Parses the entire file in the initialization phase of the test, which can increase startup time and memory usage for large files. Best suited for scenarios where performance is prioritized over memory consumption.
+* **`csv.Parser`**: Reads the file line-by-line, making it more memory-efficient but potentially slower due to reading overhead for each line. Ideal for scenarios where memory usage is a concern or where fine-grained control over parsing is needed.
+
+#### Example Usage
+
+<details>
+<summary> Expand to see an example of Parsing a full CSV file into a SharedArray.</summary>
+
+```javascript
+import { open } from 'k6/experimental/fs'
+import csv from 'k6/experimental/csv'
+import { scenario } from 'k6/execution'
+
+export const options = {
+    iterations: 10,
+}
+
+let file;
+let csvRecords;
+(async function () {
+    file = await open('data.csv');
+
+    // The `csv.parse` function consumes the entire file at once, and returns
+    // the parsed records as a SharedArray object.
+    csvRecords = await csv.parse(file, {delimiter: ','})
+})();
+
+
+export default async function() {
+    // The csvRecords a SharedArray. Each element is a record from the CSV file, represented as an array
+    // where each element is a field from the CSV record.
+    //
+    // Thus, `csvRecords[scenario.iterationInTest]` will give us the record for the current iteration.
+    console.log(csvRecords[scenario.iterationInTest])
+}
+```
+
+</details>
+
+<details>
+<summary> Expand to see an example of streaming a CSV file line-by-line.</summary>
+
+```javascript
+import { open } from 'k6/experimental/fs'
+import csv from 'k6/experimental/csv'
+
+export const options = {
+    iterations: 10,
+}
+
+let file;
+let parser;
+(async function () {
+    file = await open('data.csv');
+    parser = new csv.Parser(file);
+})();
+
+export default async function() {
+    // The parser `next` method attempts to read the next row from the CSV file.
+    //
+    // It returns an iterator-like object with a `done` property that indicates whether
+    // there are more rows to read, and a `value` property that contains the row fields
+    // as an array.
+    const {done, value} = await parser.next();
+    if (done) {
+        throw new Error("No more rows to read");
+    }
+
+    // We expect the `value` property to be an array of strings, where each string is a field
+    // from the CSV record.
+    console.log(done, value);
+}
+```
+
+</details>
+
+### New `k6 cloud upload` command for uploading test files to the cloud [`#3906`](https://github.com/grafana/k6/pull/3906)
+
+Although we continue to refine and improve the cloud service to handle better the uploading of test files,
+as well as the overall user experience, we've added a new `k6 cloud upload` command that replaces the
+`k6 cloud --upload-only` flag used so far, which is now considered deprecated.
+
+### gRPC module updates driven by contributors
+
+#### New `discardResponseMessage` option
+
+[#3877](https://github.com/grafana/k6/pull/3877) and [#3820](https://github.com/grafana/k6/pull/3820) add a new option for gRPC module `discardResponseMessage` which allows users to discard the messages received from the server.
+
+```javascript
+const resp = client.invoke('main.RouteGuide/GetFeature', req, {discardResponseMessage: true});
+```
+
+This reduces the amount of memory required, and the amount of garbage collection, which reduces the load on the testing machine and can help produce more reliable test results.
+
+Thank you, @lzakharov!
+
+#### New argument `meta` for gRPC's stream callbacks
+
+[#3801](https://github.com/grafana/k6/pull/3801) adds a new argument `meta` to gRPC's stream callback, which handles the timestamp of the original event (e.g. when message has been received).
+
+```javascript
+let stream = new grpc.Stream(client, "main.FeatureExplorer/ListFeatures")
+stream.on('data', function (data, meta) {
+    // will print the timestamp when message has been received
+    call(meta.ts);
+});
+```
+
+Thank you, @cchamplin!
+
+#### Allow missing file descriptors for gRPC reflection
+
+[#3871](https://github.com/grafana/k6/pull/3871) allows missing file descriptors for gRPC reflection.
+
+Thank you, @Lordnibbler!
+
+### Sobek updates brings support of new ECMAScript features into k6 [`#3925`](https://github.com/grafana/k6/pull/3925), [`#3913`](https://github.com/grafana/k6/pull/3913)
+
+With this release, we've updated [Sobek](https://github.com/grafana/sobek) (the `ECMAScript` implementation in Go) which contains the new ECMAScript features that are now available in k6.
+
+This includes support for numeric literal separators, like:
+
+```javascript
+const billion = 1_000_000_000
+```
+
+And also support for `BigInt`, the values which are too large to be represented by the number primitive.
+
+```javascript
+const huge = BigInt(9007199254740991);
+```
+
+Note: that prior k6 version v0.54, Golang's type `math/big.Int` mapped to another type, so it might be a breaking change for some extensions or users.
+
+### New `setChecked` method for the browser module [`#3914`](https://github.com/grafana/xk6-browser/pull/1403)
+
+Previously, users could check or uncheck checkbox and radio button elements using the [`check`](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/page/check/) and [`uncheck`](https://grafana.com/docs/k6/latest/javascript-api/k6-browser/page/uncheck/) methods. Now, we've added a `setChecked` method that allows users to set either the checked or unchecked state of a checkbox or radio button with a single method and a boolean argument.
+
+```javascript
+await page.setChecked('#checkbox', true);   // check the checkbox
+await page.setChecked('#checkbox', false);  // uncheck the checkbox
+```
+
+[Page](https://grafana.com/docs/k6/next/javascript-api/k6-browser/page/setchecked/), [Frame](https://grafana.com/docs/k6/next/javascript-api/k6-browser/frame/), [ElementHandle](https://grafana.com/docs/k6/next/javascript-api/k6-browser/elementhandle/), and [Locator](https://grafana.com/docs/k6/next/javascript-api/k6-browser/locator/) now support the new `setChecked` method.
+
+## UX improvements and enhancements
+
+- [#3898](https://github.com/grafana/k6/pull/3898) adds `SetupTimeout` option validation. Thank you, @tsukasaI!
+- [#3930](https://github.com/grafana/k6/pull/3930) adds token validation for `k6 cloud login`, so now you get immediate feedback right after logging in.
+- [#3876](https://github.com/grafana/k6/pull/3876), [#3923](https://github.com/grafana/k6/pull/3923) adjusts the process' exit code for cloud test runs where thresholds have failed.
+- [#3765](https://github.com/grafana/k6/pull/3765) stops using the confusing `✓` and `✗` for `Rate` metrics, and instead uses the form: `{x} out of {y}`.
+
+## Bug fixes
+
+- [#3947](https://github.com/grafana/k6/pull/3947) fixes panic when `options` is `nil` (e.g. exported from a module where it isn't really exported).
+- [browser#1406](https://github.com/grafana/xk6-browser/pull/1406) fixes panic on iframe attach when iframe didn't contain any UI elements.
+- [browser#1420](https://github.com/grafana/xk6-browser/pull/1420) uses the VU context to control the iterations lifecycle which helps k6 shutdown in a timely manner when a test is aborted.
+- [browser#1421](https://github.com/grafana/xk6-browser/pull/1421) fixes the navigation span by starting when the page starts to load so that it's a better representation of how long the test was on a page.
+- [browser#1408](https://github.com/grafana/xk6-browser/pull/1408), [#1422](https://github.com/grafana/xk6-browser/pull/1422) fixes the `page.reload` API so handles `null` responses without exceptions.
+
+## Maintenance and internal improvements
+
+- [#3915](https://github.com/grafana/k6/pull/3915) switches `go.mod` to the go1.21, introduces toolchain.
+- [#3938](https://github.com/grafana/k6/pull/3938) updates k6's CI workflows to go 1.23.
+- [#3939](https://github.com/grafana/k6/pull/3939) updates Dockerfile to use go 1.23 and alpine 3.20.
+- [#3909](https://github.com/grafana/k6/pull/3909) fixes `ExitCode` description typo. Thank you, @eltociear!
+- [#3926](https://github.com/grafana/k6/pull/3926) documents maintenance of tc39 tests.
+- [#3881](https://github.com/grafana/k6/pull/3881) adds top-level roadmap link.
+- [#3945](https://github.com/grafana/k6/pull/3945) updates the endpoint where [usage reports](https://grafana.com/docs/k6/latest/set-up/usage-collection/) are sent to.
+- [#3903](https://github.com/grafana/k6/pull/3903), [#3912](https://github.com/grafana/k6/pull/3912), [#3928](https://github.com/grafana/k6/pull/3928) update dependencies.
+- [browser#1419](https://github.com/grafana/xk6-browser/pull/1419), [browser#1423](https://github.com/grafana/xk6-browser/pull/1423) adds a new remote file upload protocol.
+
+## _Optional_ Roadmap
+
+_Discussion of future plans_
+