Skip to content
MaxoPerf MaxoPerf docs

Bind a browser fleet to a test

Use a browser fleet dependency when a script needs real Chrome, Firefox or Edge sessions that MaxoPerf hosts. The run starts the fleet, passes its endpoints to the script, and stops it afterwards. Leave it out for an API test, or when a browser test already covers the journey. See Browser fleets for how a fleet works on its own.

Bind a fleet

Section titled “Bind a fleet”
  1. Create a fleet, or reuse one. See Browser fleets. It can be stopped; the run starts it.
  2. Open the test, go to Dependencies and click Add dependency.
  3. Select the Browser fleet kind and pick the fleet under Choose a browser fleet.
  4. Type an Env var name, for example EU. The hint shows the WebDriver variable.
  5. Click Add.

A fleet and a test must live in the same workspace. The API answers 404 when they do not. There is no auto-start switch for fleets: a bound fleet is always started by the run.

The four variables

Section titled “The four variables”

A fleet bound as EU injects:

MAXOPERF_FLEET_EU_WEBDRIVER_URL
MAXOPERF_FLEET_EU_PLAYWRIGHT_URL
MAXOPERF_FLEET_EU_CDP_URL
MAXOPERF_FLEET_EU_TOKEN

The WebDriver URL is the endpoint a Selenium script uses, ending in /wd/hub. It carries no credentials. The Playwright URL is the WebSocket endpoint for Chromium, ending in /playwright/chromium, and it carries no token. The CDP URL is the fleet’s /cdp WebSocket endpoint, also without a token, and it works with Chromium only. The token is the fleet’s connection token.

Connect from the runner

Section titled “Connect from the runner”

The script runs on a MaxoPerf runner, so the client library is the runner’s, not yours.

Selenium. Open a webdriver.Remote on MAXOPERF_FLEET_EU_WEBDRIVER_URL. The WebDriver endpoint takes the fleet id as the user name and the token as the password, in the URL. The injected URL has neither, so the script adds them:

from urllib.parse import quote, urlsplit


url = urlsplit(os.environ["MAXOPERF_FLEET_EU_WEBDRIVER_URL"])
fleet_id = url.path.split("/")[2]
token = quote(os.environ["MAXOPERF_FLEET_EU_TOKEN"], safe="")
command_executor = url._replace(netloc=f"{fleet_id}:{token}@{url.netloc}").geturl()

The Selenium quickstart shows the same URL in Python, Java and JavaScript.

Playwright over CDP. MAXOPERF_FLEET_EU_CDP_URL carries no token, so send the token as a Bearer header. Chromium only:

const browser = await chromium.connectOverCDP(process.env.MAXOPERF_FLEET_EU_CDP_URL!, {
  headers: { Authorization: `Bearer ${process.env.MAXOPERF_FLEET_EU_TOKEN}` },
  timeout: 60_000,
});

The first connection to a fleet starts Chrome on the runner and is slower than later ones. In testing from a machine near the runner it took 7.1 seconds cold and 3.5 seconds warm, and it can take longer from a distant runner. Set a generous connect timeout, such as 60 seconds.

Playwright over the Playwright URL. MAXOPERF_FLEET_EU_PLAYWRIGHT_URL is for chromium.connect with a Playwright client of a minor the fleet supports. A client that sends no version header is matched by the minor in its User-Agent. The Playwright quickstart lists the supported minors.

Where the browser evidence is

Section titled “Where the browser evidence is”

A script that drives a fleet opens its browsers on the fleet, not on the runner. Its video, steps, HAR and console are on the fleet’s Sessions tab, not in the run’s own Video, HAR and Console tabs. The run page shows a notice while a fleet is bound. It links to the fleet’s Sessions filtered to the time window of the run. The notice says the fleet is bound, not that the script connected. In the REST API, GET /v1/fleets/{fleetId}/sessions takes startedFrom and startedTo (ISO 8601) and returns the filtered total in the X-Total-Count header.

What the run does

Section titled “What the run does”
Fleet state when the run startsWhat the run does
RunningThe lease is ready at once.
Queued, allocating, starting or stoppingThe run waits.
Created, stopped or failedThe run starts the fleet and waits for it to run.

If the fleet enters an error state after the run started it, the run fails instead of starting it again. When the run ends, MaxoPerf stops the fleet if this run started it. A fleet you had already started keeps running. The run’s row links to Open sessions, which lists the browser sessions the script opened.

A fleet has a lifetime (TTL, 120 minutes by default) that restarts each time the fleet starts. Metering runs while the fleet runs. See Billing and limits.

Next steps

Section titled “Next steps”