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.

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 detail page or with GET /v1/fleets/<fleetId>/token.
• A local @playwright/test whose minor version matches a fleet-supported minor — see Match your Playwright version first.

For the protocol-agnostic version of this page (endpoint shapes, credential positions, and how a fleet’s protocols relate), see Connect a client.

Connect with one project per engine

Playwright connects per browser engine, so give the fleet one project each for chromium, firefox, and msedge. The token goes 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 — npx playwright test — and it executes against the fleet.

Tip

Prefer 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 exact same ?token= slot.

Match your Playwright version

Playwright’s connect() pins the client and server to the same major.minor. A mismatch fails fast rather than misbehaving silently — this is the single most common fleet support issue, so check it first.

• MaxoPerf supports the last four Playwright minors. The current set is returned as supportedPlaywrightVersions in the fleet create response and on the fleet detail page (for example ["1.59", "1.58", "1.57", "1.56"]).

• Your local @playwright/test minor must equal one of those. Patch versions within a supported minor are fine.

• If your version isn’t supported, the connection is rejected with an HTTP 428 whose body lists the currently 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)

When you can’t match a Playwright minor — or you’re on Puppeteer, or an older Playwright — connect to Chromium over the Chrome DevTools Protocol. CDP is version-agnostic, so there’s no lockstep to manage:

// 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 — there is no CDP endpoint for firefox. For firefox, use the per-engine Playwright URL and a supported minor.

What you’ll capture

Playwright sessions always record video, visible as live tiles on the fleet’s run in the console. Because Playwright speaks its own wire protocol (not WebDriver), fleets don’t produce a step timeline for Playwright sessions; console and HAR are best-effort via CDP on chromium and msedge, and video-only on firefox. See the full capability matrix.

Troubleshooting

• Connection closes immediately / HTTP 428 — your @playwright/test minor isn’t supported. Read the returned supportedPlaywrightVersions and pin to one, or switch to CDP.
• 401 Unauthorized — the token is missing, 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 it was deleted). Create a new one.
• No step timeline — expected for Playwright; steps come from the WebDriver path. Use Selenium if you need steps.