Choose the right Playwright connection for a remote browser

A worker reaches the browser host, opens a socket, and still cannot create the clean session the test expects. Another job attaches successfully but inherits somebody else's tabs and cookies. Both failures start with an endpoint choice, not with the locator that eventually times out.

The names look similar because both calls return a Browser. The contract behind that object is different. One connection speaks Playwright's protocol to a browser process launched as a Playwright server. The other speaks Chrome DevTools Protocol, usually called CDP, to a Chromium browser that may have been started by another tool or a person. Treating those endpoints as interchangeable produces confusing handshake errors, missing capabilities, and shared-state failures that appear much later in the run.

Know which protocol is on the other end

Start with ownership. If your test platform launches the browser specifically for Playwright workers, browserType.connect() is the normal choice. The server is created with browserType.launchServer(), and BrowserServer.wsEndpoint() supplies the WebSocket URL. The client and server use Playwright's own protocol. They must run matching Playwright major and minor versions. A 1.62.1 client can work with a 1.62.x server, but a 1.61 client and a 1.62 server are outside the documented compatibility contract.

That native connection is available on chromium, firefox, and webkit. It is the route to choose when a grid, container, or browser host is part of your test infrastructure and you control both ends. A newly launched browser has no contexts. Each worker can call browser.newContext(), get isolated cookies and cache, and close that context when its test finishes. Playwright also describes CDP attachment as significantly lower fidelity than this native connection, an important warning when the suite depends on advanced functionality.

An existing Chrome or Chromium process presents a different interface. Starting it with a remote debugging endpoint makes CDP available. chromium.connectOverCDP() accepts either an HTTP URL such as http://127.0.0.1:9222 or the browser WebSocket URL reported by Chrome. Only Chromium-based browsers support this path. Firefox remote debugging is not a substitute, and passing a CDP address to firefox.connect() does not turn it into a cross-browser protocol.

CDP exposes the browser as it already exists. The default profile context appears at browser.contexts()[0]; its pages are returned by context.pages(). Those pages may include a login tab, an extension page, a blank startup tab, or a screen another automation client opened. The default context cannot be closed through BrowserContext.close(). That is not an incidental limitation. It tells you the attaching client is a guest in a session with a lifecycle outside the test.

The endpoint shape gives an early clue, but it is not a safe protocol detector by itself. A native endpoint is normally a ws:// or wss:// URL returned by wsEndpoint(). A CDP endpoint can be HTTP or WebSocket, and its WebSocket path commonly contains /devtools/browser/. A vendor proxy can hide those familiar shapes. Store the protocol type as explicit configuration rather than writing a helper that guesses from the URL.

Use separate variables, for example PW_BROWSER_WS_ENDPOINT and CHROME_CDP_URL. A single BROWSER_ENDPOINT invites someone to copy the address from the wrong dashboard. It also makes incident logs ambiguous. When a connection fails before any page exists, the endpoint kind is often the only evidence that separates a deployment error from an incompatible browser.

The practical decision is compact:

An HTTP 200 from a host health check proves almost nothing about this table. It does not prove a Playwright WebSocket is listening, that Chrome exposes /json/version, that authentication headers are accepted, or that the browser version matches the client package. Check the protocol service itself.

Use connect when the browser is a Playwright service

The first worked example separates the browser owner from the test worker. It uses two small TypeScript programs because that is the topology connect() is designed for. Install the same playwright version on both machines. Run the server program on the browser host, copy the printed endpoint through your secret or service-discovery mechanism, then run the client with that value.

The server keeps ownership of the process. It binds only to loopback in this local example. Binding a real server to a network interface requires network controls because anybody who obtains its endpoint can control the browser and, through browser capabilities, may affect the host.

// browser-server.ts
import { chromium } from 'playwright';

const server = await chromium.launchServer({
  headless: true,
  host: '127.0.0.1',
  port: 0,
});

console.log(`PW_BROWSER_WS_ENDPOINT=${server.wsEndpoint()}`);

let stopping = false;
async function stop(): Promise<void> {
  if (stopping) return;
  stopping = true;
  await server.close();
}

process.once('SIGINT', () => void stop());
process.once('SIGTERM', () => void stop());
await new Promise<void>(resolve => server.once('close', resolve));

The worker creates and closes its own context. The data URL keeps the example independent of a public website. Tracing starts on that owned context and stops before the context closes, which makes remote-connect-trace.zip complete and readable.

// remote-worker.ts
import { strict as assert } from 'node:assert';
import { chromium } from 'playwright';

const endpoint = process.env.PW_BROWSER_WS_ENDPOINT;
if (!endpoint) throw new Error('PW_BROWSER_WS_ENDPOINT is required');

const browser = await chromium.connect(endpoint, { timeout: 15_000 });
const context = await browser.newContext({
  locale: 'en-GB',
  viewport: { width: 1280, height: 720 },
});

await context.tracing.start({ screenshots: true, snapshots: true });
try {
  const page = await context.newPage();
  await page.goto(
    'data:text/html,<title>Remote checkout</title><h1>Order confirmed</h1>',
  );
  assert.equal(await page.title(), 'Remote checkout');
  assert.equal(await page.getByRole('heading').textContent(), 'Order confirmed');
  console.log({
    connected: browser.isConnected(),
    browserType: browser.browserType().name(),
    browserVersion: browser.version(),
    visibleContexts: browser.contexts().length,
  });
} finally {
  try {
    await context.tracing.stop({ path: 'remote-connect-trace.zip' });
  } finally {
    await context.close();
    await browser.close();
  }
}

Run the programs with a TypeScript runner already present in your project, or compile them with your existing TypeScript setup. The useful output looks like this:

PW_BROWSER_WS_ENDPOINT=ws://127.0.0.1:53421/7a2b...redacted
{
  connected: true,
  browserType: 'chromium',
  browserVersion: '140.0.7339.16',
  visibleContexts: 1
}

Do not publish the full endpoint in CI artifacts. launchServer() uses an unguessable WebSocket path by default for a reason. Redact the path while retaining the scheme, host alias, port, protocol label, Playwright package version, and run ID. That is enough for most triage without leaving a browser-control credential in a report.

There is a network near-miss that regularly gets blamed on connect(). Suppose the browser runs in a container, the test code runs on the developer laptop, and the application under test listens on the laptop at http://127.0.0.1:4173. The connection succeeds because the laptop can reach the browser server. Navigation fails because 127.0.0.1 inside the remote browser points back to the container, not the laptop.

The evidence is specific. browser.isConnected() is true. browser.newContext() succeeds. The trace contains page.goto() and shows a network error for the application URL. A protocol mismatch would fail before the context or trace action exists. Fix the network route in the environment when possible. For a controlled Playwright server, the documented connect() option exposeNetwork can expose selected client-side hosts to the remote browser. exposeNetwork: '<loopback>' is useful for local development, while a narrow staging hostname pattern is safer in shared infrastructure. Exposing * is convenient but broadens what the remote browser can reach through the connecting client.

That fix has a cost. The worker now participates in browser networking, and connectivity depends on the worker remaining alive. Requests can take a less representative path than production traffic. A routable test deployment is usually the better CI design; exposeNetwork is best treated as a deliberate bridge, not a universal cure for container DNS.

Use connectOverCDP when Chrome already owns the session

A QA engineer often reaches for CDP while investigating a bug that appears only after a long manual setup, with a corporate login, or in a Chrome build launched by another system. Reusing that browser can save twenty minutes of reproduction work. It is also the wrong default for a clean regression suite unless the state sharing is part of the test.

Launch a dedicated automation profile, never your everyday Chrome profile. Current Chrome policy also requires a non-default user data directory for remote debugging in common setups. On macOS, a local command can look like this:

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/qa-cdp-profile \
  about:blank

The second worked example verifies the discovery endpoint before attaching. That small probe prevents a reverse proxy's login page or an unrelated service on port 9222 from being mistaken for Chrome. It records the browser and protocol versions, attaches, lists existing tabs, and creates one page that it owns. The script closes only that page, then disconnects. It does not close or clear tabs that existed before attachment.

// inspect-existing-chrome.ts
import { strict as assert } from 'node:assert';
import { chromium } from 'playwright';

const cdpUrl = new URL(
  process.env.CHROME_CDP_URL ?? 'http://127.0.0.1:9222',
);
assert.ok(
  cdpUrl.protocol === 'http:' || cdpUrl.protocol === 'https:',
  'This discovery example requires an HTTP CDP endpoint',
);
const discoveryUrl = new URL('/json/version', cdpUrl).toString();
const response = await fetch(discoveryUrl);

assert.equal(
  response.ok,
  true,
  `CDP discovery failed: ${response.status} ${response.statusText}`,
);

const metadata = (await response.json()) as {
  Browser?: string;
  'Protocol-Version'?: string;
  webSocketDebuggerUrl?: string;
};

assert.ok(metadata.Browser, 'CDP response has no Browser field');
assert.ok(metadata['Protocol-Version'], 'CDP response has no Protocol-Version');
assert.ok(metadata.webSocketDebuggerUrl, 'CDP response has no browser websocket');

console.log({
  browser: metadata.Browser,
  protocolVersion: metadata['Protocol-Version'],
  websocketPath: new URL(metadata.webSocketDebuggerUrl).pathname,
});

const browser = await chromium.connectOverCDP(cdpUrl.toString(), {
  timeout: 15_000,
});
const defaultContext = browser.contexts()[0];
assert.ok(defaultContext, 'Chrome did not expose its default context');

const pagesBefore = defaultContext.pages();
console.log('existing page URLs', pagesBefore.map(page => page.url()));

const ownedPage = await defaultContext.newPage();
try {
  await ownedPage.goto('data:text/html,<title>CDP audit</title><h1>Attached</h1>');
  assert.equal(await ownedPage.title(), 'CDP audit');
  assert.equal(await ownedPage.getByRole('heading').textContent(), 'Attached');
} finally {
  await ownedPage.close();
  await browser.close();
}

A typical /json/version response contains data in this shape:

{
  "Browser": "Chrome/140.0.7339.16",
  "Protocol-Version": "1.3",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/4f5b..."
}

Those fields prove that the HTTP service is a browser-level CDP target. They do not prove that a specific tab exists or that its login is valid. Tab targets are available separately from /json/list, while Playwright gives you the attached pages through defaultContext.pages(). Do not select pages()[0] and assume it is the application. Startup order changes, extensions add targets, and a user can open another tab. Match a page by an expected URL or create a page you clearly own.

Attaching to a browser is not the same as obtaining a test fixture. The existing default context retains cookies, service workers, permissions, cache, and site storage. A passing checkout test might be borrowing authentication from yesterday. A failure might be caused by an extension or an expired session that no clean CI context would contain. Record whether the test uses existing state, a newly created context, or imported storageState. Those are three different preconditions.

If the real requirement is simply “start authenticated,” a normal Playwright context loaded from a reviewed storage-state file is easier to reproduce than CDP attachment. CDP is justified when the browser process itself matters: an enterprise-managed build, a profile prepared by an external tool, a live troubleshooting session, or a Chrome-only capability accessed through a CDP session. Convenience alone is weak justification for accepting persistent shared state.

Prove whether the transport or the test failed

Connection incidents are easiest to diagnose by locating the last object Playwright successfully created. The handshake occurs before a Browser exists. Context setup occurs before a Page exists. Navigation and assertions happen after both. A screenshot cannot explain a handshake that never produced a page, and extending the locator timeout cannot repair a protocol mismatch.

Capture a short connection record before the call:

connection_kind=playwright
endpoint_scheme=wss
endpoint_host=browser-grid.internal
client_playwright=1.62.1
run_id=784219

For CDP, add the sanitized /json/version fields:

connection_kind=cdp
endpoint_scheme=http
endpoint_host=chrome-host.internal
browser=Chrome/140.0.7339.16
cdp_protocol=1.3
existing_contexts=1
existing_pages=3
run_id=784219

Never log authorization headers, query tokens, full unguessable WebSocket paths, cookies, local storage, or page URLs that contain secrets. Diagnostics are useful only if the team can retain them safely.

Four signatures account for most mix-ups:

1. The call fails before returning a Browser. Check endpoint kind, reachability, authentication, TLS, and version compatibility. A native client sent to a CDP socket often reports a WebSocket or protocol error. A CDP client sent to a Playwright endpoint cannot obtain Chrome's /json/version contract. The important fact is the failed operation name, such as browserType.connect or browserType.connectOverCDP, plus the endpoint classification.
2. The Browser exists, but the target application cannot load. Inspect the trace network panel and the browser host's DNS route. This is commonly the remote-loopback problem, a proxy difference, or a certificate issue. The transport is already healthy.
3. The page loads, but state is surprising. Compare browser.contexts().length, context.pages(), cookie names, and the chosen context. Existing pages or cookies in the CDP default context are evidence of inherited state, not a flaky login locator.
4. The run stops halfway through with a closed-page message. Correlate the browser process logs, server lifecycle, and browser.isConnected(). A platform reaping an idle browser, another owner shutting down the server, or a worker calling cleanup too broadly can all surface as “Target page, context or browser has been closed.” That message describes the final symptom, not the owner that initiated closure.

Run a failing Playwright Test case with verbose API logging when the ordinary report stops at a vague helper:

DEBUG=pw:api npx playwright test tests/remote-browser.spec.ts --workers=1

The pw:api log shows the order of Playwright calls. It can establish whether connect, newContext, newPage, or goto was last. Redact the endpoint before attaching logs to a ticket. A single worker removes concurrent cleanup while diagnosing; it is evidence, not a permanent fix.

Tracing becomes valuable only after a context is available. With Playwright Test, enable a trace for the reproduction and inspect it through the HTML report or npx playwright show-trace path/to/trace.zip. In the action list, find the first failing call. If page.goto() appears with failed network requests, the browser connection worked. If the trace contains an assertion against the wrong account, inspect the storage snapshot and context choice. If no trace archive was written because connection failed before context creation, look at the handshake record and service logs instead.

The closest near-miss is a browser executable mismatch. The endpoint and protocol may be correct, yet an untested Chrome release or custom launch arguments can change behavior. CDP attachment does not make every Chrome build equivalent to Playwright's bundled Chromium. Record Browser from /json/version and browser.version() from the connected object. Compare the failing host with a known-good host before changing the API. If both use CDP but only the enterprise build fails, the connection method is probably not the discriminating variable.

Another near-miss is account contamination. A test that lands on /login after CDP attachment may look like a dropped connection because the next locator times out. Check the page URL, response status, and cookie presence. A live Browser with an expired cookie is an authentication failure. Reconnecting to the same profile merely restores the same expired state.

Move an existing suite without creating shared state

Do not replace every call in one commit and wait for CI to explain the behavioral differences. Inventory the suite first. For each current connection helper, record who launches the browser, which protocol endpoint it returns, whether the test expects existing profile state, which browser families run, and who owns cleanup. A helper named getRemoteBrowser() often conceals several incompatible uses.

Introduce a typed, explicit boundary rather than an automatic fallback. A fallback from connect() to connectOverCDP() makes an invalid Playwright endpoint look temporarily healthy while silently changing isolation. The reverse fallback is equally misleading. Configuration should reject an unknown kind before touching the network.

type RemoteBrowserConfig =
  | { kind: 'playwright'; endpoint: string }
  | { kind: 'cdp'; endpoint: string };

Keep the actual calls visible in separate functions even if they share logging. This lets reviewers see when a Chrome-only path enters a cross-browser project. It also gives metrics a stable label. Count connection failures, context-creation failures, navigation failures, and unexpected disconnects separately.

Begin rollout with a small canary that exercises one page, one context, and explicit cleanup. For a Playwright server path, assert that a new connection begins with the context count your service promises, then create a context and close it. For CDP, record the default-context page count but do not assert that it is zero unless the browser launcher guarantees a fresh profile. A test of a shared investigative browser should expect variation and select only the target it owns.

The third worked example exposes the most dangerous migration bug: two clients attach to the same CDP default context and therefore see the same cookie jar. Run it only against a disposable Chrome profile. It creates a uniquely named cookie, proves the second client can observe it, and removes that cookie in cleanup.

// cdp-shared-state.spec.ts
import { randomUUID } from 'node:crypto';
import { test, expect, chromium } from '@playwright/test';

test('two CDP clients share the existing default context', async () => {
  const endpoint = process.env.CHROME_CDP_URL;
  test.skip(!endpoint, 'CHROME_CDP_URL is required');

  const firstBrowser = await chromium.connectOverCDP(endpoint!);
  const secondBrowser = await chromium.connectOverCDP(endpoint!);
  const firstContext = firstBrowser.contexts()[0];
  const secondContext = secondBrowser.contexts()[0];
  if (!firstContext || !secondContext) {
    await firstBrowser.close();
    await secondBrowser.close();
    throw new Error('Chrome did not expose its default context');
  }

  const cookieName = `qa-owner-${randomUUID()}`;
  try {
    await firstContext.addCookies([
      {
        name: cookieName,
        value: 'worker-one',
        url: 'https://example.com',
      },
    ]);

    const seenBySecondClient = await secondContext.cookies('https://example.com');
    expect(seenBySecondClient).toContainEqual(
      expect.objectContaining({ name: cookieName, value: 'worker-one' }),
    );
  } finally {
    await firstContext.clearCookies({ name: cookieName });
    await firstBrowser.close();
    await secondBrowser.close();
  }
});

That passing test is evidence of a hazard, not a pattern to copy. If two real workers write the same session cookie, permission, local storage key, or application record, ordering determines the result. Retries make it worse because a retry begins after the first attempt has already mutated the profile.

Repair parallel tests by creating a new BrowserContext for each test and closing it in finally, if CDP fidelity is sufficient and the connected browser supports the operations the suite needs. Better still, use the Playwright Test fixtures or a native Playwright browser service when isolation is the primary goal. Keep CDP default-context tests in a serial project with a dedicated profile when their purpose is explicitly to validate that persistent profile.

During migration, run the old and new paths against the same small read-only scenario, but do not run destructive business actions twice. Compare browser build, final URL, response status, console errors, screenshots, and context count. A difference in login state is expected if one path reused a profile and the other created a clean context. Decide which precondition is correct instead of forcing the new path to mimic accidental state.

Roll out by project or tag. Keep retry counts at their normal value, but review the first attempt rather than accepting a retry as proof. Monitor browser-server startup time, connection latency, unexpected disconnects, context cleanup, and artifact completion. Once a path is stable, delete the ambiguous environment variable and old helper. Leaving both active indefinitely turns a controlled migration into a permanent branch nobody understands.

Ownership belongs in the fixture contract. A test-created context is closed by the test fixture. A connected client closes its own contexts before disconnecting. The browser server is stopped by the service or global process that launched it. A CDP client attached to somebody else's session closes only the pages it created and disconnects. Without those rules, one worker's successful cleanup becomes another worker's mid-test failure.

Accept the costs, and know when neither option fits

Native Playwright connections buy fidelity and isolation at the price of operational discipline. The browser host and clients must keep compatible Playwright versions. Upgrading a monorepo package without upgrading the container image can stop every worker at the handshake. Running servers consumes browser-host memory even while workers reconnect. Endpoint distribution, authentication, TLS termination, and network policy become infrastructure responsibilities. Clean contexts also repeat login and setup unless you use reviewed storage state, which adds seconds to each test or requires a shared authentication preparation step.

CDP attachment buys access to a browser you did not launch through Playwright. The cost is a narrower browser choice, lower protocol fidelity, dependence on Chrome's launch configuration, and a default context with a history. Persistent profiles grow caches and databases over time. Shared tabs make selection fragile. Security exposure is serious because a reachable remote debugging endpoint can control the browser. Place it behind loopback, a trusted tunnel, or strong network controls, and use a dedicated profile with no personal data.

Creating a fresh context after CDP attachment improves storage isolation, but it does not transform the transport into Playwright's native protocol. It also does not validate Firefox or WebKit. If your release claim is cross-browser behavior, a Chrome CDP run can be a diagnostic supplement, never the only gate.

Avoid connectOverCDP() when the actual requirement is “make login faster.” Save authenticated state and load it into isolated Playwright contexts instead. Do not use it to automate a developer's everyday Chrome profile. Current browser restrictions aside, that profile may contain passwords, extensions, customer sessions, and unrelated tabs. A failed cleanup or incorrect selector can cause real damage.

Skip connect() when there is no Playwright browser server. Selenium Grid, a raw Chrome debugging port, and a vendor's proprietary WebSocket are not automatically valid endpoints. Use the interface the provider documents. If a cloud vendor explicitly offers a Playwright-compatible endpoint, pin the supported client version and test its contract as infrastructure.

Neither remote option is worthwhile for most ordinary CI suites when the runner can launch a local browser reliably. Local browserType.launch() or the built-in Playwright Test fixtures remove a network hop, endpoint secret, server lifecycle, and version split. Remote browsers earn their complexity when they provide something real: a supported OS unavailable to the runner, centrally managed browser capacity, access to a protected network, a special browser build, or a live session that must be inspected.

A debugging session also may not need full automation. If the goal is to observe a request or inspect storage once, Chrome DevTools could be clearer and safer than attaching a script to a valuable profile. If the goal is deterministic regression coverage, reproduce the state in an isolated context instead of preserving the accident that made the bug visible.