fix: respect connectTimeoutMs when waiting for first top-level page
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: 30000in
localBrowserLaunchOptionsand 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 tomax(localBrowserLaunchOptions.connectTimeoutMs, getFirstTopLevelPageTimeoutMs())for the first page.- Keeps
STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MSand CI defaults unchanged; no API changes.