[fix]: close parity gaps across SDKs for local browser launching

Merged
SE
3mo ago
+1348-161

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_PATH then platform candidates
    • Chrome Canary, Stable, Beta, & Chromium on macOS
    • Canary & Stable across the standard Windows roots
    • the shared Chrome & Chromium executable order on Linux
  • 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/version response with a non-empty webSocketDebuggerUrl before 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 /T then /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.