To work with the browser module, make sure you are using the latest k6 version.
Properties
The table below lists the properties you can import from the browser module ('k6/browser').
Property
Description
browser
The browser module API is the entry point for all your tests. See the example and the 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 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 (CDP). It manages:
BrowserContext which is where you can set a variety of attributes to control the behavior of pages;
and Page which is where your rendered site is displayed.
Creates a new Page in a new BrowserContext and returns the page. Pages that have been opened ought to be closed using Page.close. Pages left open could potentially distort the results of Web Vital metrics.
Then, you can run the test with this command. Also, see the browser module options for customizing the browser module’s behavior using environment variables.
bash
$ k6 run script.js
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
C:\k6> k6 run script.js
windows-powershell
PS C:\k6> 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.
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 for a list of Chromium arguments. Note that arguments should not start with -- (see the command example below).
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 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 for more details.
The following command passes the browser options as environment variables to launch a headful browser with custom arguments.
bash
$ K6_BROWSER_HEADLESS=false K6_BROWSER_ARGS='show-property-changed-rects' k6 run script.js
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
C:\k6> set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_ARGS='show-property-changed-rects' " && k6 run script.js
windows-powershell
PS C:\k6> $env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_ARGS='show-property-changed-rects' ; k6 run script.js