Use k6 browser testing when you need to check a real user-facing flow and collect browser metrics—not as a substitute for protocol-level load generation. Install k6 and a Chromium-based browser, create a browser scenario, interact with the page using asynchronous locators, assert an expected result, and close the page in a finally block. The guide below shows a runnable pattern and how to choose local, cloud, or hybrid testing.
What k6 browser testing is for
The k6 browser module automates a Chromium browser as part of a k6 test. It can verify that a user journey works and measure browser-visible behavior, including Web Vitals. That makes it useful when client-side rendering, interactivity, or the user experience matters alongside backend performance. Grafana’s browser testing documentation frames the relevant questions as whether a page loads, elements become interactive, or a loading indicator persists.
For most high-volume traffic generation, use protocol-level requests. A full browser does more work per virtual user (VU), so browser tests are best used to sample user experience or cover important UI flows. A hybrid test can combine substantial protocol traffic with a smaller browser workload.
Prerequisites and setup
- Install k6 and a Chromium-based browser; Grafana’s first-test example uses Chrome.
- Be comfortable reading basic JavaScript or TypeScript. A code editor is useful, but Grafana does not require a particular editor or specify computer hardware.
- Remember that k6 is not Node.js. Compatibility with npm packages can vary, so do not assume an arbitrary Node dependency will work in a k6 script.
To generate a starter browser script and run it, use:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11#1 Best Overall
k6 new --template browser browser-script.js
k6 run browser-script.jsThe browser API is asynchronous starting in k6 v0.52.0, so browser operations must use async and await. Consult the current k6 browser documentation for version-specific details because the latest documentation can change.
Write and run a basic browser test
This example opens a page, reads its H1, checks that the value is not empty, and closes the page even if navigation or the check fails. Replace the example URL and assertion with a page and expected outcome in your own test environment.
import { browser } from 'k6/browser';
import { check } from 'k6';
export const options = {
scenarios: {
ui: {
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://your-test-environment.example');
const heading = await page.locator('h1').textContent();
check(heading, {
'expected page is shown': (value) => value !== '',
});
} finally {
await page.close();
}
}Save the file as browser-script.js and run k6 run browser-script.js. The scenario needs an executor and options.browser.type set to 'chromium'. The checks: ['rate==1.0'] threshold is an example that requires all checks to pass; it is not a universal performance target. Set thresholds to match your own service objectives and test environment.
Turn the example into a user journey
Use locators for controls and content that can change as a page renders. For example, a flow can navigate to a page, fill a form, click a submit button, and verify a result. Choose assertions that represent success for a user, such as a confirmation message or a destination heading, rather than merely checking that the browser opened a URL.
Locators are preferable for dynamic pages and single-page applications; Grafana notes they can handle cases where frames navigate or SPA content changes. Prefer waiting for a meaningful element or state over inserting arbitrary sleeps. See the browser interaction guidance for locator and interaction details.
Always close the page
Put await page.close() in a finally block. Grafana says closing pages frees allocated resources and supports accurate Web Vital calculation. Leaving pages open can affect resource use and the reliability of measurements.
Rank #4
Choose browser, protocol, or hybrid testing
| Approach | What it answers | How to use it |
|---|---|---|
| Browser-level | Does a user-facing flow work, and what browser-visible metrics does it produce? | Navigate and interact through browser APIs. Use it for frontend behavior and client-heavy applications. |
| Protocol-level | How do backend endpoints behave under substantial request load? | Generate most traffic through protocol requests. |
| Hybrid | How does the application behave under backend load while a user flow is sampled? | Combine protocol traffic with a smaller browser workload. |
Grafana’s guidance recommends protocol requests for most generated traffic and fewer browser VUs for browser-level coverage. Browser tests complement load tests; they are not automatically the most efficient way to generate large volumes of traffic.
Run locally or in Grafana Cloud k6
Local execution
Run a script from the command line with k6 run browser-script.js. Local runs are useful for developing and debugging a flow before running a broader test. The required browser and runtime setup applies to the machine running k6.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteCloud execution and cost
Grafana Cloud k6 supports browser-test execution through its interface or CLI. Its current documentation states that browser VUs consume “10 times more VU hours” than protocol VUs. This is specific to Grafana Cloud k6 and does not describe local execution or other providers. Cloud configuration can include load-zone, test-name, and project settings; check the cloud execution documentation for current options.
The cloud results view includes browser-test information such as the 75th percentile of Web Vitals over time. The documentation’s example output includes FCP, LCP, CLS, INP, and TTFB, but those displayed values are illustrative—not benchmark targets. Establish thresholds using your own service objectives and comparable test conditions.
Interpret browser metrics and make runs more reliable
- Use Web Vitals to examine user-visible performance. FCP, LCP, CLS, INP, and TTFB describe different aspects of loading, stability, interaction, and response. Avoid treating a single sample value as a universal pass mark.
- Keep the test flow deterministic. Cookie banners can block clicks, and dynamic elements can make stale selectors unreliable. Handle consent state deliberately and locate elements by the current page state.
- Wait for conditions, not arbitrary time. Use a locator or relevant state wait when possible instead of a fixed delay that may be too short on a slow run and wasteful on a fast one.
- Control metric cardinality. Avoid creating time-series labels from unbounded or highly variable values; excessive cardinality can make results harder to manage.
- Use device presets as emulation. They approximate mobile-browser behavior; they are not measurements from a physical phone.
- Check environment-specific options. Browser customization through environment variables is unsupported for browser tests running in Grafana Cloud k6, according to the browser options documentation.
Troubleshooting common problems
| Symptom | Likely cause | What to do |
|---|---|---|
| The script fails on browser operations or does not await a result. | Browser calls are asynchronous in current k6 browser API usage. | Mark the default function async and use await for page creation, navigation, locator operations, and closing. |
| A click or text lookup fails intermittently on a dynamic page. | The element has not appeared, the page changed, or the selector became stale. | Use a locator and wait for a meaningful element or state; avoid relying on a fixed sleep when a state wait is available. |
| The flow cannot reach a control because a banner or popup covers it. | A consent banner, newsletter prompt, or other overlay is intercepting interaction. | Handle the overlay in the test flow or configure the test environment so the intended interaction is reachable. |
| Web Vital results look unreliable or resources accumulate. | Pages are not being closed on every execution path. | Close each page in a finally block. |
| A script works locally but a cloud browser option has no effect. | The option may rely on environment-variable browser customization, which is unsupported for Grafana Cloud k6 browser tests. | Check the cloud browser options documentation and use a supported configuration method. |
| Chrome fails to start in a Docker-based run. | The container’s browser sandbox configuration may be involved. | Grafana documents a master-with-browser image and warns that its Chrome no-sandbox launch should be used only with trustworthy websites. Review the documented hardened alternative before using that setup in a less-trusted environment: browser options and Docker guidance. |
Or skip the browser setup
If your immediate need is a website screenshot rather than an interactive k6 test, ScreenshotNeo offers a one-request screenshot API. For example, this cURL request saves a WebP shot of Stripe; see the ScreenshotNeo API documentation for parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server exposes screenshot, page-info, and PDF-capture tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots, and every feature is on every plan.
Recommended Free Tools
Sign up for ScreenshotNeo’s free 1,000 screenshots a month—no card required.
Further k6 learning
Grafana provides a first-test tutorial, a browser testing guide, and k6 examples. Its performance-testing learning resources offer additional learning paths. The workshop page invites readers to receive notice when a workshop is offered; it describes live participation, not an on-demand recording.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
