[Claimed #2010] fix: respect connectTimeoutMs when waiting for first top-level page

Merged
GI
7mo ago
+8-1

Mirrored from external contributor PR #2010 after approval by @pirate.

Original author: @octo-patch
Original PR: https://github.com/browserbase/stagehand/pull/2010
Approved source head SHA: fd9ed12d2499c022b45ba30703c75082dc743a78

@octo-patch, please continue any follow-up discussion on this mirrored PR. When the external PR gets new commits, this same internal PR will be marked stale until the latest external commit is approved and refreshed here.

Original description

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.