k6/browser chromium.connectOverCDP() attaches to a running browser

Introduced 2026-08-10 · score 0.95

HOW TO USE IT

When a test needs to attach to an existing Chromium-based browser, pass its CDP WebSocket endpoint to `chromium.connectOverCDP()` inside the iteration and use the returned browser. k6 closes the connection at iteration end; call `browser.close()` to close it earlier.

import { chromium } from 'k6/browser';

export default async function () {
  const browser = await chromium.connectOverCDP('ws://localhost:9222/devtools/browser/<BROWSER_ID>');
  const page = await browser.newPage();
  try {
    await page.goto('https://quickpizza.grafana.com/');
  } finally {
    await page.close();
    await browser.close();
  }
}

import http from 'k6/http';
import { chromium } from 'k6/browser';

export function setup() {
  const res = http.post('https://provider.example/v1/sessions');
  return { wsURL: res.json().connectUrl };
}

export default async function (data) {
  const browser = await chromium.connectOverCDP(data.wsURL);
  const page = await browser.newPage();
  try {
    await page.goto('https://quickpizza.grafana.com/');
  } finally {
    await page.close();
    await browser.close();
  }
}

WHY THIS HELPS

When a browser test needs to attach to an existing Chromium-based browser, connect to its WebSocket endpoint and run the iteration against it.

REQUIREMENTS AND LIMITATIONS

Version: v2.2.0
wsEndpoint (required): String containing the browser's CDP WebSocket endpoint; documentation says it must use `ws` or `wss`.
browser.close(): Closes the connection early; k6 otherwise closes it at iteration end. Closing the connection does not stop the browser.
Prerequisite: An existing Chromium-based browser with a CDP WebSocket endpoint. For the local example, start Chrome with `--remote-debugging-port` and read `webSocketDebuggerUrl` from `http://localhost:9222/json/version`.
Prerequisite: The function connects within an iteration and does not require the `browser` scenario option.
Attaches to Chromium-based browsers over the Chrome DevTools Protocol.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card

Tools change faster than your agent’s training data.

Changes

k6/browser chromium.connectOverCDP() attaches to a running browser