[fix]: close parity gaps across SDKs for local browser launching
Merged
SE
3mo ago+1348+1348+0123456789012345678901234567890123456789-161-161-012345678901234567890123456789
why
this PR addresses parity gaps in local launch behaviour:
- the TypeScript and Go SDKs already waited for a newly launched Chrome process to expose a usable CDP endpoint, detected early process exit, & cleaned up owned resources when launch failed.
- the Python SDK returned immediately after spawning Chrome & had narrower executable discovery, profile setup, cancellation, & process-tree shutdown behavior
Go & Python also accepted an explicit debugging port without first proving it was available. that could let launch continue toward a browser endpoint the SDK did not own
what changed
- added a default Chrome flag fixture & made all three SDK test suites compare their local flag lists against it
- added cross SDK contract coverage for launch argument ordering,
about:blank, viewport behavior, & profile ownership - refactored the Python local launcher into focused validation, executable discovery, profile, readiness, & shutdown helpers
- aligned Python Chrome discovery with TypeScript & Go:
- explicit executable then
CHROME_PATHthen platform candidates - Chrome Canary, Stable, Beta, & Chromium on macOS
- Canary & Stable across the standard Windows roots
- the shared Chrome & Chromium executable order on Linux
- explicit executable then
- validate Python launch options & explicit executables before creating a profile or spawning Chrome
- create caller-provided Python profile directories recursively while preserving caller ownership
- wait for a successful
/json/versionresponse with a non-emptywebSocketDebuggerUrlbefore a Python launch resolves - race Python readiness against browser exit & initialization cancellation, then terminate the owned process & remove its temporary profile when launch does not complete
- added explicit loopback port availability checks to the Python & Go launchers before profile creation or process spawn
- return a focused occupied-port error instead of adopting or continuing toward an existing browser, while preserving other socket failures
- aligned Python shutdown with the TypeScript & Go launchers:
- automatically disable the Chromium sandbox for Linux root
- terminate Unix process groups with graceful then forced signals
- terminate Windows process trees with
taskkill /Tthen/F - share one close task across concurrent callers
- continue profile cleanup after shutdown failures & preserve combined errors
test plan
- Verify all three SDKs use the same static default Chrome flags, argument ordering, starting URL, viewport behavior, & profile ownership contract.
- Verify Python option validation, explicit executable precedence,
CHROME_PATH, complete platform discovery order, unsupported platforms, & caller profile creation. - Verify Python waits for a valid CDP version response, rejects malformed readiness responses, detects early browser exit, & cleans up after spawn failure or cancellation.
- Verify Python & Go automatic port selection, occupied explicit-port rejection before resource creation, & preservation of non-occupancy socket errors.
- Verify Python Linux-root sandbox behavior, Unix graceful & forced process-group termination, Windows tree termination, already-exited processes, concurrent close, & combined cleanup errors
Summary by cubic
Closes local browser-launching parity gaps across the Python, Go, and TypeScript SDKs. Python previously returned after spawning Chrome and could leave failed launches behind; it now waits for a usable CDP endpoint, while Python and Go reject occupied debugging ports and all SDKs treat empty profile paths as omitted.
Bug Fixes
- Python validates launch options, executable paths, and explicit ports before creating profiles or spawning Chrome; explicit ports must be between 1 and 65535.
- Python Chrome discovery now follows the same precedence and platform candidate order as Go and TypeScript.
- Caller-owned Python profiles are created recursively and preserved, while SDK-owned temporary profiles are removed after failures, cancellation, or close.
- Python disables the Chromium sandbox for Linux root and shuts down process groups or Windows process trees with graceful-then-forced termination.
- Concurrent Python closes share one cleanup task, and shutdown continues profile cleanup while reporting combined errors.
- Go checks loopback port availability before profile creation and preserves non-occupancy socket errors.
Tests
- Shared fixtures and cross-SDK contract tests cover default flags, argument ordering, startup URL, viewport behavior, port handling, and profile ownership.