Heuristic:MarketSquare Robotframework browser MacOS Sonoma Startup Delay
| Knowledge Sources | |
|---|---|
| Domains | Troubleshooting, Platform_Compatibility |
| Last Updated | 2026-02-12 04:00 GMT |
Overview
Platform-specific workaround that adds a 1-second delay after Playwright process startup on macOS to prevent process hangs on macOS Sonoma.
Description
On macOS, particularly with macOS Sonoma, the Playwright Node.js process can hang if the Python side connects to the gRPC channel too quickly after the process starts. The Browser library works around this by inserting a `time.sleep(1)` call after the server startup completes when running on Darwin. This tribal knowledge was discovered through debugging production failures specific to macOS Sonoma.
Usage
This heuristic is relevant when debugging startup failures on macOS or when porting the library to new macOS versions. If you see the Playwright process hanging during startup on macOS, this delay is the known mitigation. The workaround is already implemented in the library code.
The Insight (Rule of Thumb)
- Action: Add a 1-second sleep after the Playwright gRPC server starts on macOS (Darwin platform).
- Value: `time.sleep(1)` after `wait_until_server_up()` completes.
- Trade-off: Adds 1 second to library initialization time on macOS only. No impact on Linux or Windows.
Reasoning
macOS Sonoma introduced changes to process scheduling and IPC handling that can cause the Playwright Node.js process to hang when the gRPC connection is established too quickly after process creation. The 1-second delay allows the Node.js process to fully initialize its event loop and gRPC server before accepting connections. The comment in the code explicitly references "macOS Sonoma and hanging process" as the reason for this workaround.
Code Evidence
From `Browser/playwright.py:72-79`:
@cached_property
def _playwright_process(self) -> Popen | None:
process = self.start_playwright()
atexit.register(self.close)
self.wait_until_server_up()
if platform.system() == "Darwin":
time.sleep(1) # To overcome problem with macOS Sonoma and hanging process
return process