---
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/latest/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).

## 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.                                                  |
| 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/latest/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/latest/javascript-api/k6-browser/page/) which is where your rendered site is displayed.

Expand table

| Method                                                                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                              |
|------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [browser.closeContext()](/docs/k6/latest/javascript-api/k6-browser/closecontext/)                                                              | Closes the current [BrowserContext](/docs/k6/latest/javascript-api/k6-browser/browsercontext/).                                                                                                                                                                                                                                                                                          |
| [browser.context()](/docs/k6/latest/javascript-api/k6-browser/context/)                                                                        | Returns the current [BrowserContext](/docs/k6/latest/javascript-api/k6-browser/browsercontext/).                                                                                                                                                                                                                                                                                         |
| [browser.isConnected](/docs/k6/latest/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/latest/javascript-api/k6-browser/newcontext/) [](https://github.com/grafana/xk6-browser/issues/455) | Creates and returns a new [BrowserContext](/docs/k6/latest/javascript-api/k6-browser/browsercontext/).                                                                                                                                                                                                                                                                                   |
| [browser.newPage(\[options\])](/docs/k6/latest/javascript-api/k6-browser/newpage/) [](https://github.com/grafana/xk6-browser/issues/455)       | Creates a new [Page](/docs/k6/latest/javascript-api/k6-browser/page/) in a new [BrowserContext](/docs/k6/latest/javascript-api/k6-browser/browsercontext/) and returns the page. Pages that have been opened ought to be closed using [`Page.close`](/docs/k6/latest/javascript-api/k6-browser/page/close/). Pages left open could potentially distort the results of Web Vital metrics. |
| [browser.version()](/docs/k6/latest/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/latest/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 - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i grafana/k6:master-with-browser run - <script.js
```

windows ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```windows
k6 run script.js
```

windows-powershell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```windows-powershell
k6 run script.js
```

### Devices example

To emulate the browser behaviour on a mobile device and approximately measure the browser performance, you can import `devices` from `k6/browser`.

JavaScript ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```javascript
import { browser, devices } 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 iphoneX = devices['iPhone X'];
  const context = await browser.newContext(iphoneX);
  const page = await context.newPage();

  try {
    await page.goto('https://test.k6.io/');
  } finally {
    page.close();
  }
}
```

## Browser-level APIs

Expand table

| k6 Class                                                                    | Description                                                                                                                      |
|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| [BrowserContext](/docs/k6/latest/javascript-api/k6-browser/browsercontext/) | Enables independent browser sessions with separate [Page](/docs/k6/latest/javascript-api/k6-browser/page/)s, cache, and cookies. |
| [ElementHandle](/docs/k6/latest/javascript-api/k6-browser/elementhandle/)   | Represents an in-page DOM element.                                                                                               |
| [Frame](/docs/k6/latest/javascript-api/k6-browser/frame/)                   | Access and interact with the [`Page`](/docs/k6/latest/javascript-api/k6-browser/page/).’s `Frame`s.                              |
| [JSHandle](/docs/k6/latest/javascript-api/k6-browser/jshandle/)             | Represents an in-page JavaScript object.                                                                                         |
| [Keyboard](/docs/k6/latest/javascript-api/k6-browser/keyboard/)             | Used to simulate the keyboard interactions with the associated [`Page`](/docs/k6/latest/javascript-api/k6-browser/page/).        |
| [Locator](/docs/k6/latest/javascript-api/k6-browser/locator/)               | The Locator API makes it easier to work with dynamically changing elements.                                                      |
| [Mouse](/docs/k6/latest/javascript-api/k6-browser/mouse/)                   | Used to simulate the mouse interactions with the associated [`Page`](/docs/k6/latest/javascript-api/k6-browser/page/).           |
| [Page](/docs/k6/latest/javascript-api/k6-browser/page/)                     | Provides methods to interact with a single tab in a browser.                                                                     |
| [Request](/docs/k6/latest/javascript-api/k6-browser/request/)               | Used to keep track of the request the [`Page`](/docs/k6/latest/javascript-api/k6-browser/page/) makes.                           |
| [Response](/docs/k6/latest/javascript-api/k6-browser/response/)             | Represents the response received by the [`Page`](/docs/k6/latest/javascript-api/k6-browser/page/).                               |
| [Touchscreen](/docs/k6/latest/javascript-api/k6-browser/touchscreen/)       | Used to simulate touch interactions with the associated [`Page`](/docs/k6/latest/javascript-api/k6-browser/page/).               |
| [Worker](/docs/k6/latest/javascript-api/k6-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.

Expand table

| Environment Variable               | Description                                                                                                                                                                                                                                                                                                                                      |
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| K6\_BROWSER\_ARGS                  | Extra command line arguments to include when launching browser process. See the [browser arguments](/docs/k6/latest/using-k6-browser/options/#browser-arguments) for usage and common arguments.                                                                                                                                                 |
| 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](/docs/k6/latest/using-k6-browser/options/#default-arguments) included when launching a browser process.                                                                                                                                                                                                    |
| K6\_BROWSER\_TIMEOUT               | Default timeout for initializing the connection to the browser instance. `'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](/docs/k6/latest/using-k6/k6-options/reference/#traces-output) for more details. |

The following command passes the browser options as environment variables to launch a headful browser with custom arguments.

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_HEADLESS=false K6_BROWSER_ARGS='show-property-changed-rects' 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 - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i -e K6_BROWSER_HEADLESS=false -e K6_BROWSER_ARGS='show-property-changed-rects' grafana/k6:master-with-browser run - <script.js
```

windows ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```windows
set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_ARGS='show-property-changed-rects' " && k6 run script.js
```

windows-powershell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```windows-powershell
$env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_ARGS='show-property-changed-rects' ; k6 run script.js
```

### Browser arguments

The following table highlights commonly useful arguments you can pass via the `K6_BROWSER_ARGS` environment variable. Most tests run without extra arguments, because the browser module already uses sensible [defaults](#default-arguments). Set these extra arguments only when you need to debug or adapt to your environment. For a complete list, refer to [Chromium command line switches](https://peter.sh/experiments/chromium-command-line-switches/).

> 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 - <script.js
```

windows ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```windows
set "K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080'" && k6 run script.js
```

windows-powershell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```windows-powershell
$env:K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' ; k6 run script.js
```