Documentation Grafana Cloud Testing and synthetics Synthetic Monitoring Create checks Check types k6 browser check

k6 browser check

k6 browser checks run a k6 script using the browser module to control a headless browser. Browser checks monitor web performance and can be used to continuously monitor critical user journeys and workflows.

With k6 browser checks, you can:

• Perform interactions on a web page like navigation, tap/click, filling forms, and scrolling.
• Leverage a Playwright-inspired API for authoring tests.
• Simultaneously make requests at the protocol-level as well as in the browser, to simulate user behavior and rich interactive scenarios.
• Set the window size to test mobile, tablet, and desktop views.

How it works

Create a k6 browser check

You can write and execute a k6 script from the code editor in the Synthetics UI.

1. On the main menu, select Testing & synthetics and then Synthetics.
2. Click Create new check or Add new check.
3. Choose k6 browser as your check type.
4. Set the value for the required options.
5. Edit or copy your k6 script under Script.
6. Schedule or run the check.
   1. Click Save to schedule the check.
   2. Click Test to run the k6 script.

For development and debugging, you can write and execute the k6 script from your local machine using the k6 CLI and your IDE. After completing the k6 script, create a new browser check or update the script of an existing one.

The Synthetics script editor includes a few scripts with basic examples. To get started implementing your first k6 browser tests, refer to the Create a k6 browser check tutorial.

Options

The list of common options to all check types:

Additionally, k6 scripted checks have the following options:

Required k6 imports and options

In order to run a browser check, the script must:

• Import the browser module
• Include the browser type “chromium” in the k6 options block.

JavaScript Copy

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    ui: {
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

Supported k6 Options

k6 options can be used to configure a wide range of features when running the k6 script. In Synthetic Monitoring, k6 options can only be set in the script options object:

JavaScript Copy

export const options = {
  tags: { foo: 'bar' },
  userAgent: 'MyK6UserAgentString/1.0',
};

Several k6 options don’t apply in the context of Synthetic Monitoring. Here is the list of supported options:

Expand table

k6 Option	Description
batch	Max number of simultaneous connections of a http.batch() call
batch-per-host	Max number of simultaneous connections of a http.batch() call for a host
discardResponseBodies	Specify whether response bodies should be discarded
httpDebug	log all HTTP requests and responses
insecureSkipTLSVerify	A boolean specifying whether k6 should ignore TLS verifications for connections established from code
maxRedirects	The maximum number of HTTP redirects that k6 will follow
noConnectionReuse	A boolean specifying whether k6 should disable keep-alive connections
setupTimeout	Specify how long the setup() function is allow to run before it’s terminated
systemTags	Specify which System Tags will be in the collected metrics
tags	Specify tags that should be set test-wide across all metrics
teardownTimeout	Specify how long the teardown() function is allowed to run before it’s terminated
throw	A boolean specifying whether to throw errors on failed HTTP requests
tlsAuth	A list of TLS client certificate configuration objects
tlsCipherSuites	A list of cipher suites allowed to be used by in SSL/TLS interactions with a server
tlsVersion	String or object representing the only SSL/TLS version allowed
userAgent	A string specifying the User-Agent header when sending HTTP requests

Metrics

Synthetic checks store their results as Prometheus metrics, including the list of common metrics to all check types:

k6 metrics

Browser checks also collect the metrics produced by k6 and store them as Prometheus metrics.

k6 has two types of metrics:

• Built-in metrics: These are metrics collected by every k6 test, such as data received and total number of requests. In addition, browser checks collect Web Vitals metrics.
• Custom metrics: These are metrics that you can create in your test script to measure anything specific to your system or business logic. In Prometheus, they’re renamed to probe_K6_METRIC_NAME and mapped to Prometheus gauges.

k6 built-in metrics for browser checks are transformed in Synthetic Monitoring as follows:

Visualization

You can query all the produced check metrics with Grafana Explore, where you can create custom panels and add them to your dashboards.

Additionally, each check includes a dashboard displaying the results of the most relevant metrics. To learn more about the various visualization options, refer to Analyze results.

Compatibility

Load local files

For security reasons, probes can’t load local files. k6 APIs such as open, fs, and grpc.load (non-reflection) aren’t supported.

To import local modules or libraries, use a bundler to build your k6 script with its dependencies locally. However, note that bundled scripts have additional limitations for browser checks.

Limitations

Bundled or minified scripts

The Synthetic Monitoring UI validates scripts by checking for required imports and options. This validation fails with webpack-compiled, bundled, or minified scripts because the code structure is obfuscated.

To create browser checks with bundled scripts, use Terraform or the Synthetic Monitoring API.

Public probe memory

Browsers on public probes are allocated 1GB of RAM when running tests, which may be insufficient for large web pages. If a page is too large to load, the test execution fails and logs the message: Unexpected DevTools server error: Target has crashed.