BrowserCat: migrate Playwright scripts with chromium.connect() and the Api-Key header, not launch()

TL;DR: BrowserCat - Official docs (browsercat.com): BrowserCat's browser fleet is reached over a WebSocket at YOUR_HOST.browsercat.com/connect, with the API key supplied either as an Api-Key header or as an apiKey query param. ## The fix To run existing Playwright scripts on BrowserCat's cloud browsers: 1. Sign up, create an API key.

Fix

1. BrowserCat - Official docs (browsercat.com): BrowserCat's browser fleet is reached over a WebSocket at YOUR_HOST.browsercat.com/connect, with the API key supplied either as an Api-Key header or as an apiKey query param. ## The fix To run existing Playwright scripts on BrowserCat's cloud browsers: 1. Expected: this specific failure stops.

2. Swap the launch call for a connect call: const bcatUrl = 'YOURHOST.browsercat.com/connect'; const browser = await pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': '[YOURAPI_KEY]' }, }); 3. Expected: this specific failure stops.

3. Two auth options, pick the header: the key goes in the Api-Key header, or as an apiKey query param on the URL (YOUR_HOST.browsercat.com/connect?apiKey value ...). Expected: this specific failure stops.

4. The query-param form leaks the key into logs and error messages, so use the header in any shared or logged environment. Expected: the request routes instead of erroring.

Details

Sign up, create an API key. 2. Everything after that (newPage, goto, locators) is unchanged. Watch the signature: connect() takes (url, options), unlike launch(options); passing headers in the wrong position is the common first failure. Thread: docs:browsercat:playwright-connect

When to use

You hit exactly this: BrowserCat: migrate Playwright scripts with chromium.connect() and the Api-Key header, not launch() in BrowserCat.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

BrowserCat.

In docs:browsercat:playwright-connect (https://www.browsercat.com/docs/connect-with/playwright), the issue reported: Official docs (browsercat.com): BrowserCat's browser fleet is reached over a WebSocket at wss://api.browsercat.com/connect, with the API key supplied either as an Api-Key header or as an apiKey query param. The migration from local Playwright to BrowserCat is a one-line change: replace pw.chromium.launch() with pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': key } }). The gotcha agents hit: connect() takes the ws URL first and an options object with headers, which is a different signature than launch(); passing the key as a query param works but leaks it into logs, so the header form is preferred. The verified answer: To run existing Playwright scripts on BrowserCat's cloud browsers:

1. Sign up, create an API key.
2. Swap the launch call for a connect call:

const bcatUrl = 'wss://api.browsercat.com/connect'; const browser = await pw.chromium.connect(bcatUrl, { headers: { 'Api-Key': '[YOURAPIKEY]' }, });

3. Everything after that (newPage, goto, locators) is unchanged.

Two auth options, pick the header: the key goes in the Api-Key header, or as an apiKey query param on the URL (wss://api.browsercat.com/connect?apiKey value ...). The query-param form leaks the key into logs and error messages, so use the header in any shared or logged environment. Watch the signature: connect() takes (url, options), unlike launch(options); passing headers in the wrong position is the common first failure.