Diagnostic Logs for Safari WebDriver Session Timeouts

This article provides a quick overview of the specific diagnostic logs you can capture when a WebDriver session times out while automating the Safari web browser. By collecting safaridriver diagnostic files, WebKit crash reports, macOS unified system logs, and client-side framework logs, you can quickly identify whether the timeout was caused by a browser hang, a driver bug, a network failure, or a system-level permission issue.

1. Safaridriver Diagnostic Logs

Apple’s built-in safaridriver utility has a native diagnostic mode that records all communication between the WebDriver client, the driver itself, and the Safari browser instance.

  • What it captures: Incoming REST API requests from your test framework, outgoing responses, and internal XPC communication between safaridriver and Safari.
  • How to enable it via Capabilities: Add the "safari:diagnose": true capability to your WebDriver session configuration.
  • How to enable it via CLI: If starting the driver manually, run safaridriver --diagnose in the terminal.
  • Where to find the logs: The logs are automatically saved to ~/Library/Logs/com.apple.WebDriver/. Each session generates a uniquely named log file containing timestamps and payload data leading up to the timeout.

2. Safari and WebKit Crash Reports

A WebDriver timeout frequently occurs because the underlying Safari browser or one of its rendering processes has crashed or frozen mid-execution, leaving safaridriver waiting indefinitely for a response.

  • What it captures: Stack traces, memory states, and thread activity at the exact moment a Safari process terminates unexpectedly.
  • Processes to look for: Look for logs related to Safari, safaridriver, com.apple.WebKit.WebContent, and com.apple.WebKit.Networking.
  • Where to find the logs: Navigate to ~/Library/Logs/DiagnosticReports/ (user-level crashes) and /Library/Logs/DiagnosticReports/ (system-level crashes). Look for .ips or .crash files whose timestamps match the exact time of your test timeout.

3. macOS Unified System Logs

macOS records extensive background activity using its Unified Logging system. If Safari hangs due to macOS security prompts, sandboxing issues, or XPC connection failures, standard WebDriver logs will not show the cause, but the system logs will.

  • What it captures: System-level errors, permission denials, and background process failures related to WebDriver and Safari.

  • How to capture it: Run the following command in the macOS Terminal immediately after a timeout occurs to extract the last 10 minutes of relevant logs:

    log show --predicate 'subsystem == "com.apple.WebDriver" OR process == "Safari" OR process == "safaridriver"' --last 10m > safari_timeout_system.log

4. WebDriver Client and Selenium Grid Logs

While safaridriver logs show the browser side of the timeout, your test runner (Selenium, WebdriverIO, Playwright, or Appium) records the client side.

  • What it captures: The exact HTTP request that was sent before the connection hung, socket timeout exceptions, and session termination errors.
  • How to enable it: Set your test framework's logging level to DEBUG or TRACE.
  • Selenium Grid: If you are running Safari on a remote macOS node via Selenium Grid, pass the --log-level FINE flag when starting the Grid Node to capture the precise moment the node loses contact with safaridriver.

5. macOS Sysdiagnose

For intermittent or severe timeouts where Safari completely locks up the macOS environment, you can trigger a full system diagnostic dump while the browser is actively hanging.

  • What it captures: Everything happening on the machine, including spindumps (which diagnose unresponsive, hanging applications), active network connections, memory pressure, and disk I/O.
  • How to capture it: Run sudo sysdiagnose in the terminal while the WebDriver session is actively timing out.
  • Where to find the logs: The output is saved as a compressed archive in /var/tmp/. Inside this archive, check the spindump.txt file to see what the Safari main thread was waiting on during the hang.