diff --git a/docs/sources/next/javascript-api/_index.md b/docs/sources/next/javascript-api/_index.md index 3b46585cf6..e2ba996899 100644 --- a/docs/sources/next/javascript-api/_index.md +++ b/docs/sources/next/javascript-api/_index.md @@ -13,16 +13,16 @@ Before the k6 starts the test logic, code in the _init context_ prepares the scr A few functions are available only in init context. For details about the runtime, refer to the [Test lifecycle](https://grafana.com/docs/k6//using-k6/test-lifecycle). -| Function | Description | -| ------------------------------------------------------------- | ---------------------------------------------------- | +| Function | Description | +| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [open( filePath, [mode] )](https://grafana.com/docs/k6//javascript-api/init-context/open) | Opens a file and reads all the contents into memory. | ## k6 The k6 module contains k6-specific functionality. -| Function | Description | -| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| Function | Description | +| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | [check(val, sets, [tags])](https://grafana.com/docs/k6//javascript-api/k6/check) | Runs one or more checks on a value and generates a pass/fail result but does not throw errors or otherwise interrupt execution upon failure. | | [fail([err])](https://grafana.com/docs/k6//javascript-api/k6/fail) | Throws an error, failing and aborting the current VU script iteration immediately. | | [group(name, fn)](https://grafana.com/docs/k6//javascript-api/k6/group) | Runs code inside a group. Used to organize results in a test. | @@ -33,8 +33,8 @@ The k6 module contains k6-specific functionality. The k6/crypto `module` provides common hashing functionality available in the GoLang [crypto](https://golang.org/pkg/crypto/) package. -| Function | Description | -| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| Function | Description | +| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | [createHash(algorithm)](https://grafana.com/docs/k6//javascript-api/k6-crypto/createhash) | Create a Hasher object, allowing the user to add data to hash multiple times, and extract hash digests along the way. | | [createHMAC(algorithm, secret)](https://grafana.com/docs/k6//javascript-api/k6-crypto/createhmac) | Create an HMAC hashing object, allowing the user to add data to hash multiple times, and extract hash digests along the way. | | [hmac(algorithm, secret, data, outputEncoding)](https://grafana.com/docs/k6//javascript-api/k6-crypto/hmac) | Use HMAC to sign an input string. | @@ -49,16 +49,16 @@ The k6/crypto `module` provides common hashing functionality available in the Go | [sha512_224(input, outputEncoding)](https://grafana.com/docs/k6//javascript-api/k6-crypto/sha512_224) | Use SHA-512/224 to hash an input string. | | [sha512_256(input, outputEncoding)](https://grafana.com/docs/k6//javascript-api/k6-crypto/sha512_256) | Use SHA-512/256 to hash an input string. | -| Class | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Class | Description | +| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Hasher](https://grafana.com/docs/k6//javascript-api/k6-crypto/hasher) | Object returned by [crypto.createHash()](https://grafana.com/docs/k6//javascript-api/k6-crypto/createhash). It allows adding more data to be hashed and to extract digests along the way. | ## k6/data The data module provides helpers to work with data. -| Class/Method | Description | -| --------------------------------------------------------------------------- | ------------------------------------------------------------- | +| Class/Method | Description | +| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | | [SharedArray](https://grafana.com/docs/k6//javascript-api/k6-data/sharedarray) | read-only array like structure that shares memory between VUs | ## k6/encoding @@ -66,8 +66,8 @@ The data module provides helpers to work with data. The encoding module provides [base64](https://en.wikipedia.org/wiki/Base64) encoding/decoding as defined by [RFC4648](https://tools.ietf.org/html/rfc4648). -| Function | Description | -| -------------------------------------------------------------------------------- | ----------------------- | +| Function | Description | +| ----------------------------------------------------------------------------------------------------------------- | ----------------------- | | [b64decode(input, [encoding], [format])](http://grafana.com/docs/k6/latest/javascript-api/k6-encoding/b64decode/) | Base64 decode a string. | | [b64encode(input, [encoding])](http://grafana.com/docs/k6/latest/javascript-api/k6-encoding/b64encode/) | Base64 encode a string. | @@ -101,7 +101,7 @@ Meta information and execution details about the current running [scenario](http | Property | Type | Description | | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | string | The assigned name of the running scenario. | -| executor | string | The name of the running [Executor](https://grafana.com/docs/k6//using-k6/scenarios#executors) type. | +| executor | string | The name of the running [Executor](https://grafana.com/docs/k6//using-k6/scenarios#executors) type. | | startTime | integer | The Unix timestamp in milliseconds when the scenario started. | | progress | float | Percentage in a 0 to 1 interval of the scenario progress. | | iterationInInstance | integer | The unique and zero-based sequential number of the current iteration in the scenario, across the current instance. | @@ -111,27 +111,26 @@ Meta information and execution details about the current running [scenario](http Control the test execution. -| Property | Type | Description | -| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| abort([String]) | function | It aborts the test run with the exit code `108`, and an optional string parameter can provide an error message. Aborting the test will not prevent the `teardown()` execution. | +| Property | Type | Description | +| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| abort([String]) | function | It aborts the test run with the exit code `108`, and an optional string parameter can provide an error message. Aborting the test will not prevent the `teardown()` execution. | | options | Object | It returns an object with all the test options as properties. The options' values are consolidated following the [order of precedence](https://grafana.com/docs/k6//using-k6/k6-options/how-to#order-of-precedence) and derived if shortcuts have been used. It returns `null` for properties where the relative option hasn't been defined. | #### vu Meta information and execution details about the current vu. -| Property | Type | Description | -| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| iterationInInstance | integer | The identifier of the iteration in the current instance for this VU. This is only unique for current VU and this instance (if multiple instances). This keeps being aggregated if a given VU is reused between multiple scenarios. | -| iterationInScenario | integer | The identifier of the iteration in the current scenario for this VU. This is only unique for current VU and scenario it is currently executing. | -| idInInstance | integer | The identifier of the VU across the instance. Not unique across multiple instances. | -| idInTest | integer | The globally unique (across the whole test run) identifier of the VU. | - +| Property | Type | Description | +| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| iterationInInstance | integer | The identifier of the iteration in the current instance for this VU. This is only unique for current VU and this instance (if multiple instances). This keeps being aggregated if a given VU is reused between multiple scenarios. | +| iterationInScenario | integer | The identifier of the iteration in the current scenario for this VU. This is only unique for current VU and scenario it is currently executing. | +| idInInstance | integer | The identifier of the VU across the instance. Not unique across multiple instances. | +| idInTest | integer | The globally unique (across the whole test run) identifier of the VU. | ## k6/experimental -| Modules | Description | -| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| Modules | Description | +| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | [browser](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser) | Provides browser-level APIs to interact with browsers and collect frontend performance metrics as part of your k6 tests. | | [redis](https://grafana.com/docs/k6//javascript-api/k6-experimental/redis) | Functionality to interact with [Redis](https://redis.io/). | | [timers](https://grafana.com/docs/k6//javascript-api/k6-experimental/timers) | `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` | @@ -139,44 +138,45 @@ Meta information and execution details about the current vu. | [webcrypto](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto) | Implements the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). | | [websockets](https://grafana.com/docs/k6//javascript-api/k6-experimental/websockets) | Implements the browser's [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket). | | [grpc](https://grafana.com/docs/k6//javascript-api/k6-experimental/grpc) | Extends `k6/net/grpc` with the streaming capabilities. | +| [fs](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs) | Provides a memory-efficient way to handle file interactions within your test scripts. | ## k6/html The k6/html module contains functionality for HTML parsing. -| Function | Description | -| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| Function | Description | +| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | [parseHTML(src)](https://grafana.com/docs/k6//javascript-api/k6-html/parsehtml) | Parse an HTML string and populate a [Selection](https://grafana.com/docs/k6//javascript-api/k6-html/selection) object. | -| Class | Description | -| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| Class | Description | +| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | [Element](https://grafana.com/docs/k6//javascript-api/k6-html/element) | An HTML DOM element as returned by the [Selection](https://grafana.com/docs/k6//javascript-api/k6-html/selection) API. | -| [Selection](https://grafana.com/docs/k6//javascript-api/k6-html/selection) | A jQuery-like API for accessing HTML DOM elements. | +| [Selection](https://grafana.com/docs/k6//javascript-api/k6-html/selection) | A jQuery-like API for accessing HTML DOM elements. | ## k6/http The k6/http module contains functionality for performing HTTP transactions. -| Function | Description | -| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| [batch( requests )](https://grafana.com/docs/k6//javascript-api/k6-http/batch) | Issue multiple HTTP requests in parallel (like e.g. browsers tend to do). | -| [cookieJar()](https://grafana.com/docs/k6//javascript-api/k6-http/cookiejar) | Get active HTTP Cookie jar. | -| [del( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/del) | Issue an HTTP DELETE request. | -| [file( data, [filename], [contentType] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/file) | Create a file object that is used for building multi-part requests. | -| [get( url, [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/get) | Issue an HTTP GET request. | -| [head( url, [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/head) | Issue an HTTP HEAD request. | -| [options( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/options) | Issue an HTTP OPTIONS request. | -| [patch( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/patch) | Issue an HTTP PATCH request. | -| [post( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/post) | Issue an HTTP POST request. | -| [put( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/put) | Issue an HTTP PUT request. | -| [request( method, url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/request) | Issue any type of HTTP request. | -| [asyncRequest( method, url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/asyncrequest) | Issue any type of HTTP request asynchronously. | -| [setResponseCallback(expectedStatuses)](https://grafana.com/docs/k6//javascript-api/k6-http/set-response-callback) | Sets a response callback to mark responses as expected. | +| Function | Description | +| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | +| [batch( requests )](https://grafana.com/docs/k6//javascript-api/k6-http/batch) | Issue multiple HTTP requests in parallel (like e.g. browsers tend to do). | +| [cookieJar()](https://grafana.com/docs/k6//javascript-api/k6-http/cookiejar) | Get active HTTP Cookie jar. | +| [del( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/del) | Issue an HTTP DELETE request. | +| [file( data, [filename], [contentType] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/file) | Create a file object that is used for building multi-part requests. | +| [get( url, [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/get) | Issue an HTTP GET request. | +| [head( url, [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/head) | Issue an HTTP HEAD request. | +| [options( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/options) | Issue an HTTP OPTIONS request. | +| [patch( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/patch) | Issue an HTTP PATCH request. | +| [post( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/post) | Issue an HTTP POST request. | +| [put( url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/put) | Issue an HTTP PUT request. | +| [request( method, url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/request) | Issue any type of HTTP request. | +| [asyncRequest( method, url, [body], [params] )](https://grafana.com/docs/k6/latest/javascript-api/k6-http/asyncrequest) | Issue any type of HTTP request asynchronously. | +| [setResponseCallback(expectedStatuses)](https://grafana.com/docs/k6//javascript-api/k6-http/set-response-callback) | Sets a response callback to mark responses as expected. | | [url\`url\`](https://grafana.com/docs/k6//javascript-api/k6-http/url) | Creates a URL with a name tag. Read more on [URL Grouping](https://grafana.com/docs/k6//using-k6/http-requests#url-grouping). | -| [expectedStatuses( statusCodes )](https://grafana.com/docs/k6//javascript-api/k6-http/expected-statuses) | Create a callback for setResponseCallback that checks status codes. | +| [expectedStatuses( statusCodes )](https://grafana.com/docs/k6//javascript-api/k6-http/expected-statuses) | Create a callback for setResponseCallback that checks status codes. | -| Class | Description | -| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Class | Description | +| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | [CookieJar](https://grafana.com/docs/k6//javascript-api/k6-http/cookiejar) | Used for storing cookies, set by the server and/or added by the client. | | [FileData](https://grafana.com/docs/k6//javascript-api/k6-http/filedata) | Used for wrapping data representing a file when doing multipart requests (file uploads). | | [Params](https://grafana.com/docs/k6//javascript-api/k6-http/params) | Used for setting various HTTP request-specific parameters such as headers, cookies, etc. | @@ -189,8 +189,8 @@ All metrics (both the [built-in metrics](https://grafana.com/docs/k6//using-k6/tags-and-groups) all values added to a custom metric, which can be useful when analysing the test results. -| Metric type | Description | -| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| Metric type | Description | +| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | [Counter](https://grafana.com/docs/k6//javascript-api/k6-metrics/counter) | A metric that cumulatively sums added values. | | [Gauge](https://grafana.com/docs/k6//javascript-api/k6-metrics/gauge) | A metric that stores the min, max and last values added to it. | | [Rate](https://grafana.com/docs/k6//javascript-api/k6-metrics/rate) | A metric that tracks the percentage of added values that are non-zero. | @@ -202,27 +202,27 @@ You can optionally [tag](https://grafana.com/docs/k6//using-k6/tags- The `k6/net/grpc` module provides a [gRPC](https://grpc.io/) client for Remote Procedure Calls (RPC) over HTTP/2. -| Class/Method | Description | -| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -| [Client](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/client) | gRPC client used for making RPC calls to a gRPC Server. | -| [Client.load(importPaths, ...protoFiles)](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/client/client-load) | Loads and parses the given protocol buffer definitions to be made available for RPC requests. | -| [Client.connect(address [,params])](https://grafana.com/docs/k6/latest/javascript-api/k6-net-grpc/client/client-connect) | Connects to a given gRPC service. | -| [Client.invoke(url, request [,params])](https://grafana.com/docs/k6/latest/javascript-api/k6-net-grpc/client/client-invoke) | Makes an unary RPC for the given service/method and returns a [Response](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/response). | -| [Client.close()](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/client/client-close) | Close the connection to the gRPC service. | -| [Params](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/params) | RPC Request specific options. | -| [Response](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/response) | Returned by RPC requests. | +| Class/Method | Description | +| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Client](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/client) | gRPC client used for making RPC calls to a gRPC Server. | +| [Client.load(importPaths, ...protoFiles)](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/client/client-load) | Loads and parses the given protocol buffer definitions to be made available for RPC requests. | +| [Client.connect(address [,params])](https://grafana.com/docs/k6/latest/javascript-api/k6-net-grpc/client/client-connect) | Connects to a given gRPC service. | +| [Client.invoke(url, request [,params])](https://grafana.com/docs/k6/latest/javascript-api/k6-net-grpc/client/client-invoke) | Makes an unary RPC for the given service/method and returns a [Response](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/response). | +| [Client.close()](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/client/client-close) | Close the connection to the gRPC service. | +| [Params](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/params) | RPC Request specific options. | +| [Response](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/response) | Returned by RPC requests. | | [Constants](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/constants) | Define constants to distinguish between [gRPC Response](https://grafana.com/docs/k6//javascript-api/k6-net-grpc/response) statuses. | ## k6/ws The ws module provides a [WebSocket](https://en.wikipedia.org/wiki/WebSocket) client implementing the [WebSocket protocol](http://www.rfc-editor.org/rfc/rfc6455.txt). -| Function | Description | -| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Function | Description | +| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [connect( url, params, callback )](https://grafana.com/docs/k6//javascript-api/k6-ws/connect) | Create a WebSocket connection, and provides a [Socket](https://grafana.com/docs/k6//javascript-api/k6-ws/socket) client to interact with the service. The method blocks the test finalization until the connection is closed. | -| Class/Method | Description | -| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Class/Method | Description | +| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Params](https://grafana.com/docs/k6//javascript-api/k6-ws/params) | Used for setting various WebSocket connection parameters such as headers, cookie jar, compression, etc. | | [Socket](https://grafana.com/docs/k6//javascript-api/k6-ws/socket) | WebSocket client used to interact with a WS connection. | | [Socket.close()](https://grafana.com/docs/k6//javascript-api/k6-ws/socket/socket-close) | Close the WebSocket connection. | diff --git a/docs/sources/next/javascript-api/k6-experimental/_index.md b/docs/sources/next/javascript-api/k6-experimental/_index.md index 2928de50cb..500cd3b6b5 100644 --- a/docs/sources/next/javascript-api/k6-experimental/_index.md +++ b/docs/sources/next/javascript-api/k6-experimental/_index.md @@ -1,6 +1,6 @@ --- -title: "k6/experimental" -excerpt: "k6 experimental APIs" +title: 'k6/experimental' +description: 'k6 experimental APIs' weight: 07 --- @@ -8,12 +8,13 @@ weight: 07 {{< docs/shared source="k6" lookup="experimental-module.md" version="" >}} -| Modules | Description | -| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| Modules | Description | +| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | [browser](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser) | Provides browser-level APIs to interact with browsers and collect frontend performance metrics as part of your k6 tests. | +| [fs](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs) | Provides a memory-efficient way to handle file interactions within your test scripts. | +| [grpc](https://grafana.com/docs/k6//javascript-api/k6-experimental/grpc) | Extends `k6/net/grpc` with the streaming capabilities. | | [redis](https://grafana.com/docs/k6//javascript-api/k6-experimental/redis) | Functionality to interact with [Redis](https://redis.io/). | | [timers](https://grafana.com/docs/k6//javascript-api/k6-experimental/timers) | `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` | | [tracing](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing) | Support for instrumenting HTTP requests with tracing information. | | [webcrypto](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto) | Implements the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). | | [websockets](https://grafana.com/docs/k6//javascript-api/k6-experimental/websockets) | Implements the browser's [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket). | -| [grpc](https://grafana.com/docs/k6//javascript-api/k6-experimental/grpc) | Extends `k6/net/grpc` with the streaming capabilities. | diff --git a/docs/sources/next/javascript-api/k6-experimental/fs/FileInfo.md b/docs/sources/next/javascript-api/k6-experimental/fs/FileInfo.md new file mode 100644 index 0000000000..bde24c4084 --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/fs/FileInfo.md @@ -0,0 +1,39 @@ +--- +title: 'FileInfo' +description: 'FileInfo represents information about a file.' +weight: 30 +--- + +# FileInfo + +The `FileInfo` class represents information about a [file](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file). + +## Properties + +| Property | Type | Description | +| :------- | :----- | :----------------------------- | +| name | string | The name of the file. | +| size | number | The size of the file in bytes. | + +## Example + +{{< code >}} + +```javascript +import { open, SeekMode } from 'k6/experimental/fs'; + +let file; +(async function () { + file = await open('bonjour.txt'); +})(); + +export default async function () { + // Retrieve information about the file + const fileinfo = await file.stat(); + if (fileinfo.name != 'bonjour.txt') { + throw new Error('Unexpected file name'); + } +} +``` + +{{< /code >}} diff --git a/docs/sources/next/javascript-api/k6-experimental/fs/SeekMode.md b/docs/sources/next/javascript-api/k6-experimental/fs/SeekMode.md new file mode 100644 index 0000000000..07c03943cc --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/fs/SeekMode.md @@ -0,0 +1,43 @@ +--- +title: 'SeekMode' +description: 'SeekMode is used to specify the position from which to seek in a file.' +weight: 40 +--- + +# SeekMode + +The `SeekMode` enum specifies the position from which to [seek](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file/seek) in a file. + +## Members + +| Member | Value | Description | +| :------ | :---- | :------------------------------------------ | +| Start | 0 | Seek from the start of the file. | +| Current | 1 | Seek from the current position in the file. | +| End | 2 | Seek from the end of the file. | + +## Example + +{{< code >}} + +```javascript +import { open, SeekMode } from 'k6/experimental/fs'; + +let file; +(async function () { + file = await open('bonjour.txt'); +})(); + +export default async function () { + // Seek 6 bytes from the start of the file + await file.seek(6, SeekMode.Start); + + // Seek 2 more bytes from the current position + await file.seek(2, SeekMode.Current); + + // Seek backwards 2 bytes from the end of the file + await file.seek(-2, SeekMode.End); +} +``` + +{{< /code >}} diff --git a/docs/sources/next/javascript-api/k6-experimental/fs/_index.md b/docs/sources/next/javascript-api/k6-experimental/fs/_index.md new file mode 100644 index 0000000000..a31b80efde --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/fs/_index.md @@ -0,0 +1,84 @@ +--- +title: 'fs' +description: 'k6 fs experimental API' +weight: 10 +--- + +# fs + +{{< docs/shared source="k6" lookup="experimental-module.md" version="" >}} + +The k6 filesystem experimental module provides a memory-efficient way to handle file interactions within your test scripts. It currently offers support for opening files, reading their content, seeking through their content, and retrieving metadata about them. + +### Memory efficiency + +One of the key advantages of the filesystem module is its memory efficiency. 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 reduces the risk of encountering out-of-memory errors, especially in load tests involving large files. + +### Notes on usage + +An important consideration when using the filesystem module is its handling of external file modifications. Once k6 loads a file, it behaves like a "view" over its contents. If you modify the underlying file during a test, k6 will not reflect those changes in the loaded [File](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file/) instance. + +## API Overview + +The module exports functions and objects to interact with the file system: + +| Function/Object | Description | +| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| [open](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/open) | Opens a file and returns a promise resolving to a `File` instance. | +| [File](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file) | Represents a file with methods for reading, seeking, and obtaining file stats. | +| [SeekMode](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/seekmode) | Enum for specifying the reference point for seek operations. Includes `Start`, `Current`, and `End`. | + +## Example + +{{< code >}} + +```javascript +import { open, SeekMode } 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(4); + + 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); +} +``` + +{{< /code >}} diff --git a/docs/sources/next/javascript-api/k6-experimental/fs/file/_index.md b/docs/sources/next/javascript-api/k6-experimental/fs/file/_index.md new file mode 100644 index 0000000000..c92c485dda --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/fs/file/_index.md @@ -0,0 +1,74 @@ +--- +title: 'File' +description: 'File represents a file with methods for reading, seeking, and obtaining file stats.' +weight: 10 +--- + +# File + +The `File` class represents a file with methods for reading, seeking, and obtaining file stats. It's returned by the [open](https://grafana.com/docs/k6/latest/javascript-api/init-context/open/) function. + +## Properties + +| Property | Type | Description | +| :------- | :----- | :----------------------------- | +| path | string | The absolute path to the file. | + +## Methods + +| Method | Description | +| :------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | +| [read](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file/read) | Reads up to `buffer.byteLength` bytes from the file into the passed `buffer`. Returns a promise resolving to the number of bytes read. | +| [seek](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file/seek) | Sets the file position indicator for the file to the passed `offset` bytes. Returns a promise resolving to the new offset. | +| [stat](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file/stat) | Returns a promise resolving to a [FileInfo](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/fileinfo/) object with information about the file. | + +## Example + +{{< code >}} + +```javascript +import { open, SeekMode } from 'k6/experimental/fs'; + +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(4); + + 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); +} +``` + +{{< /code >}} diff --git a/docs/sources/next/javascript-api/k6-experimental/fs/file/read.md b/docs/sources/next/javascript-api/k6-experimental/fs/file/read.md new file mode 100644 index 0000000000..7e285145a7 --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/fs/file/read.md @@ -0,0 +1,109 @@ +--- +title: 'read' +description: 'the read method is used to read a chunk of the file.' +weight: 20 +--- + +# read + +The `read` method is used to read a chunk of the file into an [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) buffer. + +It resolves to either the number of bytes read during the operation, or `null` if there was nothing more to read. + +## Parameters + +| Parameter | Type | Description | +| :-------- | :-------------------------------------------------------------------------------------------------------- | :-------------------------------- | +| buffer | [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | The buffer to read the data into. | + +## Returns + +A [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) resolving to the number of bytes read or `null` if the end of the file has been reached. + +## Example + +### Reading a file + +In the following example, we open a file and read it in chunks of 128 bytes until we reach the end of the file. + +{{< code >}} + +```javascript +import { open, SeekMode } from 'k6/experimental/fs'; + +let file; +(async function () { + file = await open('bonjour.txt'); +})(); + +export default async function () { + 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; + } + } + + // Seek back to the beginning of the file + await file.seek(0, SeekMode.Start); +} +``` + +{{< /code >}} + +### `readAll` helper function + +The following helper function can be used to read the entire contents of a file into a [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) buffer. + +{{< code >}} + +```javascript +import { open, SeekMode } from 'k6/experimental/fs'; + +let file; +(async function () { + file = await open('bonjour.txt'); +})(); + +async function readAll(file) { + const fileInfo = await file.stat(); + const buffer = new Uint8Array(fileInfo.size); + + const bytesRead = await file.read(buffer); + if (bytesRead !== fileInfo.size) { + throw new Error( + 'unexpected number of bytes read; expected ' + + fileInfo.size + + ' but got ' + + bytesRead + + ' bytes' + ); + } + + return buffer; +} + +export default async function () { + // Read the whole file + const fileContent = await readAll(file); + console.log(JSON.stringify(fileContent)); + + // Seek back to the beginning of the file + await file.seek(0, SeekMode.Start); +} +``` + +{{< /code >}} diff --git a/docs/sources/next/javascript-api/k6-experimental/fs/file/seek.md b/docs/sources/next/javascript-api/k6-experimental/fs/file/seek.md new file mode 100644 index 0000000000..654b49dc16 --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/fs/file/seek.md @@ -0,0 +1,52 @@ +--- +title: 'seek' +description: 'seek sets the file position indicator for the file to the passed offset bytes.' +weight: 30 +--- + +# seek + +The `seek` method sets the file position indicator for the file to the passed `offset` bytes, under the mode given by `whence`. The call resolves to the new position within the resource (bytes from the start). + +Based on the [SeekMode](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/seekmode) passed, the offset is interpreted as follows: + +- when using `SeekMode.Start`, the offset must be greater than or equal to zero. +- when using `SeekMode.Current`, the offset can be positive or negative. +- when using `SeekMode.End`, the offset must be less than or equal to zero. + +## Parameters + +| Parameter | Type | Description | +| :-------- | :---------------------------------------------------------------------------------------------- | :----------------------------------------------------------- | +| offset | number | The offset in bytes from the position specified by `whence`. | +| whence | [SeekMode](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/seekmode) | The position from which the offset is applied. | + +## Returns + +A [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) resolving to the new offset within the file. + +## Example + +{{< code >}} + +```javascript +import { open, SeekMode } from 'k6/experimental/fs'; + +let file; +(async function () { + file = await open('bonjour.txt'); +})(); + +export default async function () { + // Seek 6 bytes from the start of the file + await file.seek(6, SeekMode.Start); + + // Seek 2 more bytes from the current position + await file.seek(2, SeekMode.Current); + + // Seek backwards 2 bytes from the end of the file + await file.seek(-2, SeekMode.End); +} +``` + +{{< /code >}} diff --git a/docs/sources/next/javascript-api/k6-experimental/fs/file/stat.md b/docs/sources/next/javascript-api/k6-experimental/fs/file/stat.md new file mode 100644 index 0000000000..a7cd8be433 --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/fs/file/stat.md @@ -0,0 +1,38 @@ +--- +title: 'stat' +description: 'stat returns a promise resolving to a FileInfo object with information about the file.' +weight: 40 +--- + +# stat + +The `stat` method returns a promise resolving to a [FileInfo](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/fileinfo) object with information about the file. + +## Returns + +A [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) resolving to a [FileInfo](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/fileinfo) object with information about the file. + +## Examples + +{{< code >}} + +```javascript +import { open, SeekMode } from 'k6/experimental/fs'; + +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'); + } + + console.log(JSON.stringify(fileinfo)); +} +``` + +{{< /code >}} diff --git a/docs/sources/next/javascript-api/k6-experimental/fs/open.md b/docs/sources/next/javascript-api/k6-experimental/fs/open.md new file mode 100644 index 0000000000..78ce0d7c26 --- /dev/null +++ b/docs/sources/next/javascript-api/k6-experimental/fs/open.md @@ -0,0 +1,63 @@ +--- +title: 'open' +description: 'open opens a file and returns a promise resolving to a File instance.' +weight: 20 +--- + +# open + +The `open` function opens a file and returns a promise that resolves to a [File](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file) instance. 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 possible, and sharing the same memory space between all VUs. This approach reduces the risk of encountering out-of-memory errors, especially in load tests involving large files. + +### Asynchronous nature + +It's important to note that `open` is asynchronous and returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). Due to k6's current limitation with the Init context (which doesn't support asynchronous functions directly), you need to use an asynchronous wrapper like this: + +{{< code >}} + +```javascript +let file; +(async function () { + file = await open('bonjour.txt'); +})(); +``` + +{{< /code >}} + +## Parameters + +| Parameter | Type | Description | +| :-------- | :----- | :----------------------------------------------------------------------------------- | +| path | string | The path to the file to open. Relative paths are resolved relative to the k6 script. | + +## Returns + +A promise resolving to a [File](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs/file) instance. + +## Example + +{{< code >}} + +```javascript +import { open } 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'); + } + + console.log(JSON.stringify(fileinfo)); +} +``` + +{{< /code >}}