safaridriver.txt

SAFARIDRIVER(1)           BSD General Commands Manual          SAFARIDRIVER(1)

NAME
     safaridriver -- Safari WebDriver REST API service

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

DESCRIPTION
     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 ver-
     sion 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 ses-
     sion.  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.

OPTIONS
   Command line options
     -p, --port <port>
              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.

     -h, --help
              Prints a usage message and exits.

     --version
              Prints version information and exits.

     --enable
              Applies configuration changes so that subsequent WebDriver sessions will run without fur-
              ther 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.

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

   Session Creation Capabilities
     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 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.

     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 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 Simula-
              tors").

     safari:deviceUDID
              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").

   Other Capabilities
     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.

     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 fol-
              lowing sub-keys, all of which are optional:

                    DisableInsecureMediaCapture
                    Normally, Safari refuses to allow media capture over insecure connections. This
                    capability suppresses that restriction for testing purposes. For example, it would
                    allow a test to exercise media capture code paths using a local test web server
                    that is not configured to use HTTPS.

                    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.

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

ERRORS
     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.

SESSION CREATION
     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 com-
     mand. 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 oth-
     erwise 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.

NOTES
     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 lan-
     guages. More information is available on the Selenium project website:

           https://www.seleniumhq.org/

SEE ALSO
     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/

STANDARDS
     safaridriver implements the W3C WebDriver specification:

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

DIAGNOSTICS
     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 diag-
     nostics for a particular session, diagnostic files additionally include the session identifier in
     file names.

Darwin                         November 2, 2019                         Darwin