| SAFARIDRIVER(1) | General Commands Manual | SAFARIDRIVER(1) |
safaridriver —
Safari 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.
-p,
--port
⟨port⟩safaridriver will exit immediately with a non-zero
return code.-h,
--help--version--enableWhen 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.
--diagnosesafaridriver instance. See
DIAGNOSTICS for more
information.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.
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`.
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.
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'.
safaridriver will only create a session using
hosts whose OS build version matches the value of
safari:platformBuildVersion.
example of a macOS build version is `18E193'.
On macOS, the OS build version can be determined by running the sw_vers(1) utility.
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.
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.
safaridriver will only create a session using
hosts whose device name matches the value of
safari:deviceName.
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").
safaridriver will only create a session using
hosts whose device UDID matches the value of
safari:deviceUDID.
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").
debugger; statement in the test page.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:
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:
safaridriver implements the W3C WebDriver
specification:
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 |