diff --git a/docs/sources/next/javascript-api/k6-experimental/browser/_index.md b/docs/sources/next/javascript-api/k6-experimental/browser/_index.md index dcb03ecb3c..cdbecef59c 100644 --- a/docs/sources/next/javascript-api/k6-experimental/browser/_index.md +++ b/docs/sources/next/javascript-api/k6-experimental/browser/_index.md @@ -18,7 +18,7 @@ You can find examples of using [the browser module API](#browser-module-api) in To work with the browser module, make sure you are using the latest [k6 version](https://github.com/grafana/k6/releases). - {{% /admonition %}} +{{% /admonition %}} ## Properties @@ -36,14 +36,14 @@ The browser module is the entry point for all your tests, and it is what interac - [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext) which is where you can set a variety of attributes to control the behavior of pages; - and [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page) which is where your rendered site is displayed. -| Method | Description | -| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [browser.context()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/context) | Returns the current [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | -| [browser.closeContext()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/closecontext) | Closes the current [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | -| [browser.isConnected](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/isconnected) | Indicates whether the [CDP](https://chromedevtools.github.io/devtools-protocol/) connection to the browser process is active or not. | -| [browser.newContext([options])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/newcontext/) | Creates and returns a new [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | -| [browser.newPage([options])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/newpage) | Creates a new [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page) in a new [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext) and returns the page. Pages that have been opened ought to be closed using [`Page.close`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page/close). Pages left open could potentially distort the results of Web Vital metrics. | -| [browser.version()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/version) | Returns the browser application's version. | +| Method | Description | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [browser.context()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/context) | Returns the current [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | +| [browser.closeContext()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/closecontext) | Closes the current [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | +| [browser.isConnected](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/isconnected) | Indicates whether the [CDP](https://chromedevtools.github.io/devtools-protocol/) connection to the browser process is active or not. | +| [browser.newContext([options])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/newcontext/) | Creates and returns a new [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext). | +| [browser.newPage([options])](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/newpage) | Creates a new [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page) in a new [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext) and returns the page. Pages that have been opened ought to be closed using [`Page.close`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page/close). Pages left open could potentially distort the results of Web Vital metrics. | +| [browser.version()](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/version) | Returns the browser application's version. | ### Example @@ -84,6 +84,7 @@ export default async function () { Then, you can run the test with this command. Also, see the [browser module options](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser#browser-module-options) for customizing the browser module's behavior using environment variables. {{< code >}} + ```bash $ k6 run script.js ``` @@ -109,41 +110,44 @@ C:\k6> k6 run script.js ```windows-powershell PS C:\k6> k6 run script.js ``` + {{< /code >}} ## Browser-level APIs -| k6 Class | Description | -| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| k6 Class | Description | +| -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [BrowserContext](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/browsercontext) | Enables independent browser sessions with separate [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page)s, cache, and cookies. | -| [ElementHandle](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/elementhandle) | Represents an in-page DOM element. | +| [ElementHandle](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/elementhandle) | Represents an in-page DOM element. | | [Frame](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/frame) | Access and interact with the [`Page`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page).'s `Frame`s. | -| [JSHandle](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/jshandle) | Represents an in-page JavaScript object. | +| [JSHandle](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/jshandle) | Represents an in-page JavaScript object. | | [Keyboard](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/keyboard) | Used to simulate the keyboard interactions with the associated [`Page`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page). | -| [Locator](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/locator) | The Locator API makes it easier to work with dynamically changing elements. | +| [Locator](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/locator) | The Locator API makes it easier to work with dynamically changing elements. | | [Mouse](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/mouse) | Used to simulate the mouse interactions with the associated [`Page`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page). | -| [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page) | Provides methods to interact with a single tab in a browser. | +| [Page](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page) | Provides methods to interact with a single tab in a browser. | | [Request](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/request) | Used to keep track of the request the [`Page`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page) makes. | | [Response](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/response) | Represents the response received by the [`Page`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page). | | [Touchscreen](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/touchscreen) | Used to simulate touch interactions with the associated [`Page`](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/page). | -| [Worker](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/worker) | Represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | +| [Worker](https://grafana.com/docs/k6//javascript-api/k6-experimental/browser/worker) | Represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | ## Browser Module Options You can customize the behavior of the browser module by providing browser options as environment variables. -| Environment Variable | Description | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| K6_BROWSER_ARGS | Extra command line arguments to include when launching browser process. See [this link](https://peter.sh/experiments/chromium-command-line-switches/) for a list of Chromium arguments. Note that arguments should not start with `--` (see the [example](#example)). | -| K6_BROWSER_DEBUG | All CDP messages and internal fine grained logs will be logged if set to `true`. | -| K6_BROWSER_EXECUTABLE_PATH | Override search for browser executable in favor of specified absolute path. | -| K6_BROWSER_HEADLESS | Show browser GUI or not. `true` by default. | -| K6_BROWSER_IGNORE_DEFAULT_ARGS | Ignore any of the [default arguments](#default-arguments) included when launching a browser process. | -| K6_BROWSER_TIMEOUT | Default timeout to use for various actions and navigation. `'30s'` if not set. | +| Environment Variable | Description | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| K6_BROWSER_ARGS | Extra command line arguments to include when launching browser process. See [this link](https://peter.sh/experiments/chromium-command-line-switches/) for a list of Chromium arguments. Note that arguments should not start with `--` (see the [example](#example)). | +| K6_BROWSER_DEBUG | All CDP messages and internal fine grained logs will be logged if set to `true`. | +| K6_BROWSER_EXECUTABLE_PATH | Override search for browser executable in favor of specified absolute path. | +| K6_BROWSER_HEADLESS | Show browser GUI or not. `true` by default. | +| K6_BROWSER_IGNORE_DEFAULT_ARGS | Ignore any of the [default arguments](#default-arguments) included when launching a browser process. | +| K6_BROWSER_TIMEOUT | Default timeout to use for various actions and navigation. `'30s'` if not set. | +| K6_BROWSER_TRACES_METADATA | Sets additional _key-value_ metadata that is included as attributes in every span generated from browser module traces. Example: `K6_BROWSER_TRACES_METADATA=attr1=val1,attr2=val2`. This only applies if traces generation is enabled, refer to [Traces output](https://grafana.com/docs/k6//using-k6/k6-options/reference#traces-output) for more details. | The following command passes the [browser module options](#browser-module-options) as environment variables to launch a headful browser with custom arguments. {{< code >}} + ```bash $ K6_BROWSER_HEADLESS=false K6_BROWSER_ARGS='show-property-changed-rects' k6 run script.js ``` @@ -169,6 +173,7 @@ C:\k6> set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_ARGS='show-property-ch ```windows-powershell PS C:\k6> $env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_ARGS='show-property-changed-rects' ; k6 run script.js ``` + {{< /code >}} ## Default arguments @@ -179,7 +184,7 @@ List of default arguments included when launching the browser process. You can p The starting '--' have been omitted from the argument names in these lists. - {{% /admonition %}} +{{% /admonition %}} | Argument | Value | Description | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |