Playwright quickstart

Connect an existing Playwright suite to a fleet by pointing each project’s connectOptions at the fleet’s per-engine WebSocket URL. Nothing else in your suite changes.

Get started with browser fleets.

Before you start

• A running fleet with at least one chromium, firefox, or msedge browser. Create one from the console, the REST API, or an AI agent.
• The fleet’s connection token (mpft_…) or an account API key (mpak_…). Reveal the token on the fleet’s Connect tab or with GET /v1/fleets/<fleetId>/token.
• A local @playwright/test whose minor version matches a minor the fleet supports. Read Match your Playwright version first.

The fleet's Connect tab has everything this quickstart asks for: the fleet id, the WebSocket URL for each engine, and the supported Playwright minors to pin to.

Connect a client covers the same ground for every protocol: endpoint shapes, where credentials go, and how a fleet’s protocols relate.

Connect with one project per engine

Playwright connects to one browser engine at a time, so give the fleet one project each for chromium, firefox, and msedge. Put the token in the ?token= query parameter:

// playwright.config.ts — one project per fleet browser engine.
// Your local @playwright/test version MUST match a supported minor (see note above).
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { connectOptions: { wsEndpoint: 'wss://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/playwright/chromium?token=mpft_example_token' } },
    },
    {
      name: 'firefox',
      use: { connectOptions: { wsEndpoint: 'wss://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/playwright/firefox?token=mpft_example_token' } },
    },
    {
      name: 'msedge',
      use: { connectOptions: { wsEndpoint: 'wss://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/playwright/msedge?token=mpft_example_token' } },
    },
  ],
});

Replace flt-a1b2c3d4e5 with your fleet id and mpft_example_token with your token. Then run your suite as usual with npx playwright test. It runs against the fleet.

Tip

To keep the token out of the config file, read it from an environment variable and build the wsEndpoint string at load time. Any mpak_… account key with access to the fleet works in the same ?token= slot.

Match your Playwright version

Playwright’s connect() pins the client and server to the same major.minor. Keep your client on a minor the fleet supports.

• MaxoPerf supports a rolling set of Playwright minors: currently 1.59, 1.58, 1.57, 1.56 and 1.63. The set always includes the Playwright version installed on MaxoPerf runners. The fleet create response returns it as supportedPlaywrightVersions, and the fleet’s Connect tab shows it (for example ["1.59", "1.58", "1.57", "1.56", "1.63"]).

• Any patch version within a supported minor works.

• A client that sends no version header is matched by the minor in its User-Agent when that minor is supported. Otherwise it gets the default, 1.59.

• If you send a version explicitly, with an X-Playwright-Version header or a ?pwVersion= parameter, and it is not in the set, MaxoPerf rejects the connection with an HTTP 428 whose JSON body lists the supported minors. Pin your suite to one of them:

  npm install -D @playwright/test@1.59

Caution

Firefox and msedge over Playwright use MaxoPerf’s version-pinned bundles too. If you can’t move your suite onto a supported minor, use the CDP escape hatch for Chromium instead.

CDP escape hatch (version-agnostic)

If you can’t match a Playwright minor, or you use Puppeteer or an older Playwright, connect to Chromium over the Chrome DevTools Protocol. CDP works with any version, so there are no versions to keep in step:

// Version-agnostic Chromium escape hatch (Playwright or Puppeteer).
import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP('wss://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/cdp?token=mpft_example_token');
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

CDP is Chromium only. Firefox has no CDP endpoint. For firefox, use the per-engine Playwright URL and a supported minor.

Plain https, if you'd rather not copy a wss:// URL

The same CDP endpoint also answers over https://…/cdp — connectOverCDP discovers the WebSocket itself, so https://app.maxoperf.com/browser-fleets/flt-a1b2c3d4e5/cdp?token=mpft_example_token works exactly like the wss:// form above.

Name a session — Playwright and CDP alike — with an x-maxoperf-session-name header on the connect request, or a ?name= query parameter on the connect URL. Named sessions show up labeled on the fleet’s Sessions tab instead of a bare session id.

What you’ll capture

Playwright and CDP sessions capture the same four signals as every other fleet session: video (live tiles on the fleet’s run in the console), steps, console, and HAR. Playwright drives the browser over its own wire protocol, so MaxoPerf reports steps from what the page did instead of from WebDriver commands: navigation lifecycle plus the clicks, inputs and submits it observes in the page. The full capability matrix lists every combination.

Troubleshooting

• Connection closes immediately / HTTP 428: you sent an explicit Playwright version that the fleet doesn’t support. Read the returned supportedPlaywrightVersions and pin to one, or switch to CDP.
• 401 Unauthorized: the token is missing or wrong, or the fleet is not yours. Re-reveal it with GET /v1/fleets/<fleetId>/token.
• 410 Gone: the fleet has ended (its TTL elapsed, it went idle, or someone deleted it). Create a new one.
• No interaction steps, only auto:* ones: the fleet was created with stepCapture: false, or the page blocks the injected script (a strict CSP with no script-src allowance). You still get navigation lifecycle steps, video, console and HAR.