connectOverCDP(wsEndpoint)

Mon, 21 Sep 2026 15:16:28 +0000

connectOverCDP(wsEndpoint)

Attaches k6 to an existing Chromium-based browser over the Chrome DevTools Protocol (CDP), and returns a Browser you can use exactly like a k6-managed one.

Because you connect from inside the iteration, you can compute the WebSocket endpoint at runtime. For instance, you can request a browser session from your provider’s API in setup() and pass the endpoint to your iterations.

Note
connectOverCDP doesn’t need the browser scenario option. k6 doesn’t launch a browser, so there’s no browser type for it to resolve. The browser module options that apply to an existing browser, such as K6_BROWSER_TIMEOUT and K6_BROWSER_DEBUG, are still honored.

Parameter	Type	Default	Description
wsEndpoint	string	-	Required. The WebSocket endpoint of the browser’s CDP interface, for example `ws://localhost:9222/devtools/browser/<BROWSER_ID>`. Must use the `ws` or `wss` scheme.

Returns

Type	Description
`Promise<Browser>`	A Promise that fulfills with a Browser object. Unlike the k6-managed `browser`, it also exposes `close()`.

Connection lifecycle

k6 manages the connection for you and closes it at the end of the iteration, the same way it does for a browser it launched itself. Call browser.close() when you want to release it earlier.

Closing the connection doesn’t stop the browser itself. You own its lifecycle, so it keeps running.

Examples

Connect to a local browser

Start Chrome with the --remote-debugging-port flag, then read its WebSocket endpoint from http://localhost:9222/json/version (the webSocketDebuggerUrl field) and pass it to k6 as an environment variable:

import { chromium } from 'k6/browser';

export default async function () {
  const browser = await chromium.connectOverCDP(__ENV.CDP_WS_URL);
  const page = await browser.newPage();

  try {
    await page.goto('https://quickpizza.grafana.com/');
    console.log(`title: ${await page.title()}`);
  } finally {
    await page.close();
    await browser.close();
  }
}

Then, run the test with this command:

CDP_WS_URL=ws://localhost:9222/devtools/browser/<BROWSER_ID> k6 run script.js

Connect to a browser provider

When a third-party provider creates the browser session, request the endpoint once in setup() and share it with every iteration:

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();
  }
}

browser module API - The API a connected browser exposes
browser.close() - Release the connection before the iteration ends
browser.isConnected - Check whether the CDP connection is still active
Running browser tests - Run tests with a browser that k6 launches

Chromium on Grafana Labs

connectOverCDP(wsEndpoint)

connectOverCDP(wsEndpoint)

Returns

Connection lifecycle

Examples

Connect to a local browser

Connect to a browser provider

Related