SAFARIDRIVER(1) General Commands Manual SAFARIDRIVER(1)

safaridriverSafari WebDriver REST API service

safaridriver -p port [-h | --help] [--version] [--enable] [--diagnose]

The safaridriver utility is used to launch an HTTP server that implements the Selenium WebDriver REST API. When launched, safaridriver allows for automated testing of web content using the version of Safari that is installed with macOS.

safaridriver supports several capabilities that can customize an automation session's behavior for a particular testing purpose. Capabilities are provided as arguments when requesting a new session. The capabilities supported by safaridriver are listed in the OPTIONS section below. Unless noted below, the values of requested capability keys are not read and are assumed to be true if present, and false otherwise.

To use capabilities in your tests, please refer to the relevant 3rd-party documentation to learn how to request extra capabilities with the WebDriver client library that you are using.

, --portport
Specifies the port on which the HTTP server should listen for incoming connections. If the port is already in use or otherwise unavailable, safaridriver will exit immediately with a non-zero return code.
--help
Prints a usage message and exits.
Prints version information and exits.
Applies configuration changes so that subsequent WebDriver sessions will run without further authentication. This includes checking "Enable Remote Automation" in Safari's Develop menu. The user must authenticate via password for the changes to be applied.

When this option is specified, safaridriver exits immediately without starting up the REST API service. If the changes were successful or already applied, safaridriver exits 0; otherwise, safaridriver exits >0 and prints an error message to stderr.

Enables diagnostic logging for all sessions hosted by this safaridriver instance. See DIAGNOSTICS for more information.

browserName
safaridriver can only create WebDriver sessions for Safari. If the value of browserName is not equal to `Safari', session creation will fail.

Values of browserName are compared case-insensitively.

browserVersion
safaridriver will only create a session using hosts whose Safari version matches the value of browserVersion.

Browser version numbers are prefix-matched. For example, if the value of browserVersion is `12', this will allow hosts with a Safari version of `12.0.1' or `12.1`.

platformName
If the value of platformName is `mac' or `macOS', safaridriver will only create a session using the macOS host on which safaridriver is running.

If the value of platformName is `iOS', safaridriver will only create a session on a paired iOS device or simulator.

Values of platformName are compared case-insensitively.

safari:platformVersion
safaridriver will only create a session using hosts whose OS version matches the value of safari:platformVersion.

OS version numbers are prefix-matched. For example, if the value of safari:platformVersion is `12', this will allow hosts with an OS version of `12.0' or `12.1' but not `10.12'.

safari:platformBuildVersion
safaridriver will only create a session using hosts whose OS build version matches the value of . example of a macOS build version is `18E193'.

On macOS, the OS build version can be determined by running the sw_vers(1) utility.

safari:useSimulator
If the value of safari:useSimulator is true, safaridriver will only use iOS Simulator hosts.

If the value of safari:useSimulator is false, safaridriver will not use iOS Simulator hosts.

NOTE: An Xcode installation is required in order to run WebDriver tests on iOS Simulator hosts.

safari:deviceType
If the value of safari:deviceType is `iPhone', safaridriver will only create a session using an iPhone device or iPhone simulator.

If the value of safari:deviceType is `iPad', safaridriver will only create a session using an iPad device or iPad simulator.

Values of safari:deviceType are compared case-insensitively.

safari:deviceName
safaridriver will only create a session using hosts whose device name matches the value of . Device names are compared case-insensitively.

NOTE: Device names for connected devices are shown in iTunes. If Xcode is installed, device names for connected devices are available via the output of instruments(1) and in the Devices and Simulators window (accessed in Xcode via "Window > Devices and Simulators").

safari:deviceUDID
safaridriver will only create a session using hosts whose device UDID matches the value of . Device UDIDs are compared case-insensitively.

NOTE: If Xcode is installed, UDIDs for connected devices are available via the output of instruments(1) and in the Devices and Simulators window (accessed in Xcode via "Window > Devices and Simulators").

acceptInsecureCerts
This capability instructs Safari to complete all network requests regardless of the trustworthiness of an SSL/TLS certificate, including trusting expired certificates, certificates that do not match the host, and certificates without a trusted root.
safari:automaticInspection
This capability instructs Safari to preload the Web Inspector and JavaScript debugger in the background prior to returning a newly-created window. To pause the test's execution in JavaScript and bring up Web Inspector's Debugger tab, you can simply evaluate a debugger; statement in the test page.
safari:automaticProfiling
This capability instructs Safari to preload the Web Inspector and start a Timeline recording in the background prior to returning a newly-created window. To view the recording, open the Web Inspector through Safari's Develop menu.
safari:diagnose
This capability requests that diagnostics be enabled for the session. See DIAGNOSTICS for more information.
webauthn:virtualAuthenticators
This capability instructs Safari to allow use of the Virtual Authenticator WebDriver commands. https://www.w3.org/TR/webauthn-2/#sctn-automation-webdriver-capability
webkit:WebRTC
This capability allows a test to temporarily change Safari's policies for WebRTC and Media Capture. The value of the webkit:WebRTC capability is a dictionary with the following sub-keys, all of which are optional:
DisableInsecureMediaCapture
Normally, Safari refuses to allow media capture over insecure connections. This restriction is relaxed by default for WebDriver sessions for testing purposes (for example, a test web server not configured for HTTPS). When this capability is specified, Safari will revert to the normal behavior of preventing media capture over insecure connections.
DisableICECandidateFiltering
To protect a user's privacy, Safari normally filters out WebRTC ICE candidates that correspond to internal network addresses when capture devices are not in use. This capability suppresses ICE candidate filtering so that both internal and external network addresses are always sent as ICE candidates.

The safaridriver utility exits 0 on success, and >0 if an error occurs.

When a REST API command fails, safaridriver includes a detailed error message in the response. If you use a 3rd-party library on top of the REST API service, consult the library's documentation for how to access these error messages.

safaridriver can create WebDriver sessions using Safari on a macOS machine, a paired iOS device, or an iOS simulator. Capabilities listed in the Session Creation Capabilities subsection provide criteria that affect which hosts safaridriver will attempt to use when handling a New Session command. A host must match all criteria to be usable. If no hosts match all of the criteria, then the New Session command will fail. If multiple hosts match all of the criteria, the order in which safaridriver will use them is unspecified, except that booted simulators are used before unbooted simulators.

If a simulator host matches the criteria but is not booted, safaridriver will attempt to boot the simulator instance and wait for it to become usable. If Safari is not running on a host that otherwise matches the criteria, safaridriver will automatically launch Safari and wait for it to become usable. If a host's Safari instance is associated with an inactive WebDriver session, safaridriver will replace the old session unless the session was manually interrupted by the user or is being inspected by Web Inspector.

For security reasons, Safari does not permit live media capture during a WebDriver test session. Instead, mock capture devices and streams with well-known contents are provided for testing purposes. Some media capabilities are configurable for testing; see the extension capability webkit:WebRTC in the Other Capabilities subsection.

For security reasons, the HTTP server accepts connections from localhost only. The HTTP server can accept connections from multiple test clients. Safari on macOS and iOS can only host one WebDriver session at a time, so it is not recommended to run multiple safaridriver instances at the same time.

safaridriver is typically executed manually at the command line or automatically by a WebDriver client library. The Selenium project provides client libraries for most popular programming languages. More information is available on the Selenium project website:

https://www.seleniumhq.org/

A summary of which REST API endpoints safaridriver supports, as well as the Safari version in which each endpoint became available, can be found on the Apple Developer website:

https://developer.apple.com/

safaridriver implements the W3C WebDriver specification:

https://www.w3.org/TR/webdriver/

When filing a bug report against safaridriver, it is highly recommended that you capture and include diagnostics generated by safaridriver. This can be accomplished in several ways:

To diagnose a single session, pass the safari:diagnose capability when requesting a new session.

To diagnose all sessions from one safaridriver instance, use the --diagnose command line option.

To diagnose all sessions in all instances of safaridriver, set the DiagnosticsEnabled default in the com.apple.WebDriver domain to YES using defaults(1).

Diagnostic files are saved to ~/Library/Logs/com.apple.WebDriver/ and are uniquely named using the pid of safaridriver and a timestamp. When using the safari:diagnose capability to turn on diagnostics for a particular session, diagnostic files additionally include the session identifier in file names.

4/19/17 Darwin