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
--enable
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.
--diagnose
safaridriver
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 |