fix: respect connectTimeoutMs when waiting for first top-level page

Closed
OC
7mo ago
+8-1

Fixes #1287

Problem

On slow machines, Chrome may still be setting up the first tab by the time
the CDP WebSocket handshake completes. V3Context.create() previously
waited a fixed 5 seconds (DEFAULT_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS) for
the first top-level page to register, regardless of any user-supplied
timeout, causing a TimeoutError: waitForFirstTopLevelPage (no top-level Page) timed out after 5000ms on slow hardware.

Solution

Take the maximum of localBrowserLaunchOptions.connectTimeoutMs and the
existing env-var / CI-derived default. This means users who already bump
connectTimeoutMs to accommodate a slow environment automatically get the
same patience when waiting for the initial page—no new API surface needed.

// Before
await ctx.ensureFirstTopLevelPage(getFirstTopLevelPageTimeoutMs());

// After
const firstPageTimeoutMs = Math.max(
  opts?.localBrowserLaunchOptions?.connectTimeoutMs ?? 0,
  getFirstTopLevelPageTimeoutMs(),
);
await ctx.ensureFirstTopLevelPage(firstPageTimeoutMs);

Existing escape hatches (STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS env
var, CI auto-bump to 30 s) are unchanged—this change only applies a
floor when the user has explicitly set a higher connectTimeoutMs.

Testing

  • Existing unit and integration tests continue to pass (no change to default behaviour).
  • Users on slow machines / WSL2 can now set connectTimeoutMs: 30000 in
    localBrowserLaunchOptions and the first-page wait will scale with it.

Summary by cubic

Respect connectTimeoutMs when waiting for the first top‑level page to avoid startup timeouts on slow machines. Fixes #1287.

  • Bug Fixes
    • V3Context.create() now waits up to max(localBrowserLaunchOptions.connectTimeoutMs, getFirstTopLevelPageTimeoutMs()) for the first page.
    • Keeps STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS and CI defaults unchanged; no API changes.