--- title: "k6/browser | Grafana k6 documentation" description: "An overview of the browser-level APIs from browser module." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # browser The browser module APIs are inspired by Playwright and other frontend testing frameworks. You can find examples of using [the browser module API](#browser-module-api) in the [getting started guide](/docs/k6/v2.3.x/using-k6-browser/). > Note > > To work with the browser module, make sure you are using the latest [k6 version](https://github.com/grafana/k6/releases). ## Asynchronous metric context The experimental and opt-in [`async-metric-context` feature flag](/docs/k6/v2.3.x/using-k6/feature-flags/) changes how the browser module assigns tags and metadata across asynchronous operations: - Page event handlers, predicates passed to `page.waitForEvent()` and `browserContext.waitForEvent()`, and route handlers run with the metric context active when you register them. Promise reactions and `await` continuations created by a callback keep any context changes made by that callback. - Browser network requests copy the context of the browser operation that most likely initiated them. Request and response metrics keep that context for the request’s lifetime, including redirects. Browser network attribution is best-effort because the Chrome DevTools Protocol doesn’t always identify the JavaScript operation that caused a request. k6 uses frame and loader information when available, followed by the active or most recently completed page operation, the page’s creation or opener context, and finally the live VU context. Without the feature flag, browser metrics continue to use the context active when k6 emits them. For details about the affected network metrics and group tags, refer to [Browser metrics](/docs/k6/v2.3.x/using-k6-browser/metrics/). ## Properties The table below lists the properties you can import from the browser module (`'k6/browser'`). Expand table | Property | Description | |----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | browser | The browser module API is the entry point for all your tests. See the [example](#example) and the [API](#browser-module-api) below. | | chromium | A [Chromium](/docs/k6/v2.3.x/javascript-api/k6-browser/chromium/) browser type that can attach to an already running Chromium-based browser instead of one that k6 launches. See [chromium.connectOverCDP()](/docs/k6/v2.3.x/javascript-api/k6-browser/chromium/connectovercdp/). | | devices | Returns predefined emulation settings for many end-user devices that can be used to simulate browser behavior on a mobile device. See the [devices example](#devices-example) below. | ## Browser Module API The browser module is the entry point for all your tests, and it is what interacts with the actual web browser via [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP). It manages: - [BrowserContext](/docs/k6/v2.3.x/javascript-api/k6-browser/browsercontext/) which is where you can set a variety of attributes to control the behavior of pages; - and [Page](/docs/k6/v2.3.x/javascript-api/k6-browser/page/) which is where your rendered site is displayed. Expand table | Method | Description | |------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [browser.close()](/docs/k6/v2.3.x/javascript-api/k6-browser/close/) | Closes the connection to the browser. Only available on a browser returned by [chromium.connectOverCDP()](/docs/k6/v2.3.x/javascript-api/k6-browser/chromium/connectovercdp/). | | [browser.closeContext()](/docs/k6/v2.3.x/javascript-api/k6-browser/closecontext/) | Closes the current [BrowserContext](/docs/k6/v2.3.x/javascript-api/k6-browser/browsercontext/). | | [browser.context()](/docs/k6/v2.3.x/javascript-api/k6-browser/context/) | Returns the current [BrowserContext](/docs/k6/v2.3.x/javascript-api/k6-browser/browsercontext/). | | [browser.isConnected](/docs/k6/v2.3.x/javascript-api/k6-browser/isconnected/) [](https://github.com/grafana/xk6-browser/issues/453) | Indicates whether the [CDP](https://chromedevtools.github.io/devtools-protocol/) connection to the browser process is active or not. | | [browser.newContext(\[options\])](/docs/k6/v2.3.x/javascript-api/k6-browser/newcontext/) [](https://github.com/grafana/xk6-browser/issues/455) | Creates and returns a new [BrowserContext](/docs/k6/v2.3.x/javascript-api/k6-browser/browsercontext/). | | [browser.newPage(\[options\])](/docs/k6/v2.3.x/javascript-api/k6-browser/newpage/) [](https://github.com/grafana/xk6-browser/issues/455) | Creates a new [Page](/docs/k6/v2.3.x/javascript-api/k6-browser/page/) in a new [BrowserContext](/docs/k6/v2.3.x/javascript-api/k6-browser/browsercontext/) and returns the page. Pages that have been opened ought to be closed using [`Page.close`](/docs/k6/v2.3.x/javascript-api/k6-browser/page/close/). Pages left open could potentially distort the results of Web Vital metrics. | | [browser.version()](/docs/k6/v2.3.x/javascript-api/k6-browser/version/) | Returns the browser application’s version. | ### Example JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```javascript import { browser } from 'k6/browser'; export const options = { scenarios: { browser: { executor: 'shared-iterations', options: { browser: { type: 'chromium', }, }, }, }, thresholds: { checks: ['rate==1.0'], }, }; export default async function () { const page = await browser.newPage(); try { await page.goto('https://test.k6.io/'); } finally { await page.close(); } } ``` Then, you can run the test with this command. Also, see the [browser module options](/docs/k6/v2.3.x/using-k6-browser/options/) for customizing the browser module’s behavior using environment variables. Bash docker windows windows-powershell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash k6 run script.js ``` docker ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```docker # WARNING! # The grafana/k6:master-with-browser image launches a Chrome browser by setting the # 'no-sandbox' argument. Only use it with trustworthy websites. # # As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the # Chrome arguments to not use 'no-sandbox' such as: # docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - Note > > Arguments should not start with `--` when passing them to `K6_BROWSER_ARGS`. Expand table | Argument | Type | Description | |---------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | disable-web-security | boolean | Disables the same-origin policy. Useful when testing a site whose CORS configuration blocks the browser from interacting with cross-origin iframes or assets. | | ignore-certificate-errors | boolean | Ignores TLS certificate errors. Useful when testing against hosts with self-signed or otherwise invalid certificates. | | no-sandbox | boolean | Disables the Chromium sandbox. Needed when running as root inside Docker, CI, or Kubernetes. Only use with trustworthy targets. | | proxy-server | string | Routes browser traffic through an HTTP or SOCKS proxy. Pass the proxy address (`host:port`) as the value. Useful for corporate proxies or inspecting traffic with tools like mitmproxy. | For example, pass the following arguments to the `K6_BROWSER_ARGS` environment variable to ignore TLS certificate errors and route browser traffic through a proxy when running a browser test: Bash docker windows windows-powershell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' k6 run script.js ``` docker ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```docker docker run --rm -i -e K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' grafana/k6:master-with-browser run -