Documentationbreadcrumb arrow Grafana k6breadcrumb arrow Using k6 browserbreadcrumb arrow Browser options
Open source

Browser options

To enable browser testing, add the browser configuration within the options property of the Scenario options.

JavaScript 
export const options = {
  scenarios: {
    foo: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

Script options

OptionDescription
type(required)Name of the browser running the test. Options include 'chromium'.

Environment variable options

You can customize the behavior of the browser module by passing environment variables.

Note

Customizing browser options via environment variables is unsupported when running browser tests in Grafana Cloud k6.

Environment VariableDescription
K6_BROWSER_ARGSExtra command line arguments to include when launching browser process. See the browser arguments for usage and common arguments.
K6_BROWSER_DEBUGAll CDP messages and internal fine grained logs will be logged if set to true.
K6_BROWSER_EXECUTABLE_PATHOverride search for browser executable in favor of specified absolute path.
K6_BROWSER_HEADLESSShow browser GUI or not. true by default.
K6_BROWSER_IGNORE_DEFAULT_ARGSIgnore any of the default arguments included when launching a browser process.
K6_BROWSER_TIMEOUTDefault timeout for initializing the connection to the browser instance. '30s' if not set.
K6_BROWSER_TRACES_METADATASets 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 
set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_ARGS='show-property-changed-rects' " && k6 run script.js
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. 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.

Note

Arguments should not start with -- when passing them to K6_BROWSER_ARGS.

ArgumentTypeDescription
disable-web-securitybooleanDisables 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-errorsbooleanIgnores TLS certificate errors. Useful when testing against hosts with self-signed or otherwise invalid certificates.
no-sandboxbooleanDisables the Chromium sandbox. Needed when running as root inside Docker, CI, or Kubernetes. Only use with trustworthy targets.
proxy-serverstringRoutes 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 
K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' k6 run script.js
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 
set "K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080'" && k6 run script.js
windows-powershell 
$env:K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' ; k6 run script.js

Default arguments

List of default arguments included when launching the browser process. You can pass one or more of the arguments to the K6_BROWSER_IGNORE_DEFAULT_ARGS environment variable when starting a test for the ones you want to ignore.

Note

The starting ‘–’ have been omitted from the argument names in these lists.

ArgumentValueDescription
disable-background-networkingtrueDisables several subsystems which run network requests in the background. This is used during network performance testing to avoid measurement noise.
enable-featuresNetworkService,
NetworkServiceInProcess		Comma-separated list of feature names to enable.
disable-background-timer-throttlingtrueDisables task throttling of timer tasks from background pages.
disable-backgrounding-occluded-windowstrueDisables backgrounding renders for occluded windows. Done for tests to avoid nondeterministic behavior.
disable-breakpadtrueDisables the crash reporting.
disable-component-extensions
-with-background-pages		trueDisables default component extensions with background pages. Useful for performance tests where these pages may interfere with results.
disable-default-appstrueDisables the installation of default apps on the first run. This is used during automated testing.
disable-dev-shm-usagetrueThe /dev/shm partition is too small in certain VM environments, causing Chrome to fail or crash. This flag provides a work-around for this issue (a temporary directory will always be used to create anonymous shared memory files).
disable-extensionstrueDisables extensions.
disable-featuresImprovedCookieControls,
LazyFrameLoading,
GlobalMediaControls,
DestroyProfileOnBrowserClose,
MediaRouter,
AcceptCHFrame		Comma-separated list of feature names to disable.
disable-hang-monitortrueSuppresses hang monitor dialogs in renderer processes. This may allow slow unload handlers on a page to prevent the tab from closing, but the Task Manager can be used to terminate the offending process in this case.
disable-ipc-flooding-protectiontrueDisables the IPC flooding protection. It is activated by default. Some javascript functions can be used to flood the browser process with IPC. This protection limits the rate at which they can be used.
disable-popup-blockingtrueDisables pop-up blocking.
disable-prompt-on-reposttrueUsually, when the user attempts to navigate to a page that was the result of a post request, the browser prompts to make sure that’s the intention of the user. This switch may be used to disable that check during automated testing.
disable-renderer-backgroundingtruePrevents renderer process backgrounding when set.
force-color-profilesrgbForces all monitors to be treated as though they have the specified color profile. Accepted values are “srgb” and “generic-rgb” (currently used by Mac layout tests) and “color-spin-gamma24” (used by layout tests).
metrics-recording-onlytrueEnables the recording of metrics reports but disables reporting. This executes all the code that a normal client would use for reporting, except the report is dropped rather than sent to the server. This is useful for finding issues in the metrics code during UI and performance tests.
no-first-runtrueSkips the “First Run” tasks, whether or not it’s the first run, and the “What’s New” page. This does not drop the “First Run” sentinel and thus doesn’t prevent “First Run” from occurring the next time Chromium is launched without this flag. It also does not update the last “What’s New” milestone, so it does not prevent “What’s New” from occurring the next time Chromium is launched without this flag.
enable-automationtrueEnables indication that the browser is controlled by automation.
password-storebasicSpecifies which encryption storage backend to use. The possible values are kwallet, kwallet5, gnome, gnome-keyring, gnome-libsecret, and basic. Any other value will lead to Chromium detecting the best backend automatically.
use-mock-keychaintrueUses mock keychain on Mac to prevent the blocking permissions dialog about: “Chrome wants to use your confidential information stored in your keychain.”
no-service-autoruntrueDisables the service process from adding itself as an autorun process. This does not delete existing autorun registrations, it just prevents the service from registering a new one.
no-startup-windowtrueDoes not automatically open a browser window on startup (used when launching Chrome for the purpose of hosting background apps).
no-default-browser-checktrueDisables the default browser check. Useful for UI/browser tests where we want to avoid having the default browser info-bar displayed.
headlesstrue/falseRun in headless mode, i.e., without a UI or display server dependencies. Set by K6_BROWSER_HEADLESS environment variable (default true).
window-size800,600Sets the initial window size. Provided as string in the format “800,600”.

Additionally, the following arguments are set in headless mode (when K6_BROWSER_HEADLESS is true, which is the default option):

ArgumentValueDescription
hide-scrollbarstruePrevents creating scrollbars for web content. Useful for taking consistent screenshots.
mute-audiotrueMutes audio sent to the audio device so it is not audible during automated testing.
blink-settingsprimaryHoverType=2,availableHoverTypes=2,
primaryPointerType=4,availablePointerTypes=4		Sets blink settings. Format is <name>[=<value>],<name>[=<value>],… The names are declared in settings.json5 from chromium project. For boolean type, use “true”, “false”, or omit ‘=<value>’ part to set to true. For enum type, use the int value of the enum value.