Specialised Clients

## What the old import does now In k6 v2, `k6/experimental/browser` is not a module you can load. k6 still keeps that path in its internal module table, and reading the source is what makes the behaviour obvious: the entry is not a module implementation at all, it is a **removed-module stub** whose only job is to throw the moment a VU instantiates it. The error text names the replacement and links the migration guide, so you get a sentence you can act on instead of a bare "module not found". That is a **script exception**, not a warning. It happens while the VU is being built, before any iteration runs, so the test produces no metrics and no partial results — it simply stops. There is no flag that re-enables the old path and no shim that forwards it to the new one. ## Why it throws instead of resolving quietly The browser module was experimental for a long time, and a large amount of published k6 material still shows the old path. A silent alias would have let those scripts keep running while the documentation, the metrics and the async API all moved on, so k6 chose the loud option: the removal is announced at the one moment a reader is guaranteed to see it. The same treatment was applied to the other experimental paths that graduated, each with its own message naming its own replacement. ## The replacement ```javascript import { browser } from 'k6/browser'; ``` `k6/browser` is a **stable** module in k6 v2 — no experimental prefix, no feature flag, no extension build. Three properties can be named in that import: - **`browser`** — the entry point for the browser k6 manages for you, exposing `newPage()`, `newContext()`, `context()`, `closeContext()`, `isConnected()` and `version()`. - **`chromium`** — a browser type whose `connectOverCDP()` attaches to a Chromium that is already running instead of launching one. - **`devices`** — the table of predefined device-emulation settings. ## Renaming the import is only half the migration The graduation that moved the module also converted most of its API to **asynchronous** calls: `browser.newPage()`, `page.goto()`, `page.close()` and nearly every page interaction return a promise now. Two consequences follow mechanically, and both are compile-or-hang failures rather than subtle ones: 1. The exported entry function has to be marked `async`, because `await` is illegal inside a plain `export default function () { … }`. 2. Values have to be awaited **before** you assert on them. The built-in `check()` exported by the `k6` module rejects an async predicate outright rather than quietly awaiting it, so a browser assertion either reads the value first with `await` and passes a plain boolean, or uses the async-aware `check` from the k6-utils jslib. | In a pre-graduation script | In k6 v2 | |---|---| | `import { browser } from 'k6/experimental/browser'` | `import { browser } from 'k6/browser'` | | `export default function () {` | `export default async function () {` | | `const page = browser.newPage()` | `const page = await browser.newPage()` | | `page.goto(url)` | `await page.goto(url)` | | `page.close()` | `await page.close()` | A script that changes the import but forgets the `await` does not throw — it gets a pending promise where it expected a `Page`, and then fails on the next line with a type error about a method that does not exist on a promise. That is the single most common symptom of a half-finished migration. ## What the rename does not touch Everything outside the import statement stays put: - The scenario still declares the browser by setting `type` to `'chromium'` inside that scenario's own `options.browser` block. - The run still emits the same `browser_*` metric family, including `browser_web_vital_lcp`, alongside the protocol-level metrics. - Page-level calls keep their names — only their return types changed from values to promises. ## Reading the failure The symptom is easy to recognise once you have seen it, and easy to misread if you have not: - The message is a **script exception**, so the run ends with no metrics and no summary worth reading. - It names `k6/browser` explicitly, which distinguishes it from a genuine resolution failure caused by a typo in the path. - It fires once per VU as each is built, so a run with many VUs can print it repeatedly before stopping. - No environment variable, CLI flag or compatibility mode brings the old path back. ## Finding it before CI does Because the failure happens at module instantiation, neither a syntax check nor a dry inspection of the script will surface it; you only see it when a VU is built. For a suite inherited from k6 v0.4x or v0.5x the cheapest first pass is to grep the whole repository for `k6/experimental/`, and for the browser module in particular the repair is mechanical: change the path to `k6/browser`, mark every exported browser entry function `async`, put `await` in front of each browser and page call, and re-check any assertion that used to be handed a value synchronously.