appium_lib_core 4.1.0 → 7.4.0

data/lib/appium_lib_core/driver.rb

@@ -15,6 +15,9 @@
 require 'uri'
 
 module Appium
+  # The struct for 'location'
+  Location = Struct.new(:latitude, :longitude, :altitude)
+
   module Core
     module Android
       autoload :Uiautomator1, 'appium_lib_core/android'
@@ -23,33 +26,30 @@ module Appium
     end
 
     module Ios
-      autoload :Uiautomation, 'appium_lib_core/ios'
       autoload :Xcuitest, 'appium_lib_core/ios_xcuitest'
     end
 
+    autoload :Mac2, 'appium_lib_core/mac2'
+
     autoload :Windows, 'appium_lib_core/windows'
 
     # This options affects only client side as <code>:appium_lib</code> key.<br>
     # Read {::Appium::Core::Driver} about each attribute
     class Options
-      attr_reader :custom_url, :default_wait, :export_session, :export_session_path,
+      attr_reader :custom_url, :default_wait,
                   :port, :wait_timeout, :wait_interval, :listener,
                   :direct_connect, :enable_idempotency_header
 
       def initialize(appium_lib_opts)
         @custom_url = appium_lib_opts.fetch :server_url, nil
-        @default_wait = appium_lib_opts.fetch :wait, Driver::DEFAULT_IMPLICIT_WAIT
+        @default_wait = appium_lib_opts.fetch :wait, nil
         @enable_idempotency_header = appium_lib_opts.fetch :enable_idempotency_header, true
 
-        # bump current session id into a particular file
-        @export_session = appium_lib_opts.fetch :export_session, false
-        @export_session_path = appium_lib_opts.fetch :export_session_path, default_tmp_appium_lib_session
-
-        @direct_connect = appium_lib_opts.fetch :direct_connect, false
+        @direct_connect = appium_lib_opts.fetch :direct_connect, true
 
         @port = appium_lib_opts.fetch :port, Driver::DEFAULT_APPIUM_PORT
 
-        # timeout and interval used in ::Appium::Comm.wait/wait_true
+        # timeout and interval used in ::Appium::Commn.wait/wait_true
         @wait_timeout  = appium_lib_opts.fetch :wait_timeout, ::Appium::Core::Wait::DEFAULT_TIMEOUT
         @wait_interval = appium_lib_opts.fetch :wait_interval, ::Appium::Core::Wait::DEFAULT_INTERVAL
 
@@ -74,6 +74,13 @@ module Appium
         path: 'directConnectPath'
       }.freeze
 
+      W3C_KEYS = {
+        protocol: 'appium:directConnectProtocol',
+        host: 'appium:directConnectHost',
+        port: 'appium:directConnectPort',
+        path: 'appium:directConnectPath'
+      }.freeze
+
       # @return [string] Returns a protocol such as http/https
       attr_reader :protocol
 
@@ -87,10 +94,10 @@ module Appium
       attr_reader :path
 
       def initialize(capabilities)
-        @protocol = capabilities[KEYS[:protocol]]
-        @host = capabilities[KEYS[:host]]
-        @port = capabilities[KEYS[:port]]
-        @path = capabilities[KEYS[:path]]
+        @protocol = capabilities[W3C_KEYS[:protocol]] || capabilities[KEYS[:protocol]]
+        @host = capabilities[W3C_KEYS[:host]] || capabilities[KEYS[:host]]
+        @port = capabilities[W3C_KEYS[:port]] || capabilities[KEYS[:port]]
+        @path = capabilities[W3C_KEYS[:path]] || capabilities[KEYS[:path]]
       end
     end
 
@@ -126,18 +133,10 @@ module Appium
       # @return [String]
       attr_reader :custom_url
 
-      # Export session id to textfile in /tmp for 3rd party tools. False by default.
-      # @return [Boolean]
-      attr_reader :export_session
-      # @return [String] By default, session id is exported in '/tmp/appium_lib_session'
-      attr_reader :export_session_path
-
       # Default wait time for elements to appear in Appium server side.
-      # Defaults to {::Appium::Core::Driver::DEFAULT_IMPLICIT_WAIT}.<br>
       # Provide <code>{ appium_lib: { wait: 30 } }</code> to {::Appium::Core.for}
       # @return [Integer]
       attr_reader :default_wait
-      DEFAULT_IMPLICIT_WAIT = 0
 
       # Appium's server port. 4723 is by default. Defaults to {::Appium::Core::Driver::DEFAULT_APPIUM_PORT}.<br>
       # Provide <code>{ appium_lib: { port: 8080 } }</code> to {::Appium::Core.for}.
@@ -175,7 +174,8 @@ module Appium
       # - <code>directConnectPort</code>
       # - <code>directConnectPath</code>
       #
-      # Ignore them if this parameter is <code>false</code>. Defaults to false.
+      # ignore them if this parameter is <code>false</code>. Defaults to true.
+      # These keys can have <code>appium:</code> prefix.
       #
       # @return [Bool]
       attr_reader :direct_connect
@@ -185,8 +185,6 @@ module Appium
       # @option opts [Hash] :caps Appium capabilities.
       # @option opts [Hash] :capabilities The same as :caps.
       #                                   This param is for compatibility with Selenium WebDriver format
-      # @option opts [Hash] :desired_capabilities The same as :caps.
-      #                                           This param is for compatibility with Selenium WebDriver format
       # @option opts [Appium::Core::Options] :appium_lib Capabilities affect only ruby client
       # @option opts [String] :url The same as :custom_url in :appium_lib.
       #                            This param is for compatibility with Selenium WebDriver format
@@ -197,10 +195,8 @@ module Appium
       #
       #     # format 1
       #     @core = Appium::Core.for caps: {...}, appium_lib: {...}
-      #     # format 2. 'capabilities:' or 'desired_capabilities:' is also available instead of 'caps:'.
+      #     # format 2. 'capabilities:' is also available instead of 'caps:'.
       #     @core = Appium::Core.for url: "http://127.0.0.1:8080/wd/hub", capabilities: {...}, appium_lib: {...}
-      #     # format 3. 'appium_lib: {...}' can be blank
-      #     @core = Appium::Core.for url: "http://127.0.0.1:8080/wd/hub", desired_capabilities: {...}
       #
       #
       #     require 'rubygems'
@@ -216,7 +212,6 @@ module Appium
       #                app: '/path/to/MyiOS.app'
       #              },
       #              appium_lib: {
-      #                export_session: false,
       #                port: 8080,
       #                wait: 0,
       #                wait_timeout: 20,
@@ -228,7 +223,7 @@ module Appium
       #     @core.start_driver # Connect to 'http://127.0.0.1:8080/wd/hub' because of 'port: 8080'
       #
       #     # Start iOS driver with .zip file over HTTP
-      #     #  'desired_capabilities:' or 'capabilities:' is also available instead of 'caps:'. Either is fine.
+      #     # 'capabilities:' is also available instead of 'caps:'. Either is fine.
       #     opts = {
       #              capabilities: {
       #                platformName: :ios,
@@ -239,7 +234,6 @@ module Appium
       #              },
       #              appium_lib: {
       #                server_url: 'http://custom-host:8080/wd/hub.com',
-      #                export_session: false,
       #                wait: 0,
       #                wait_timeout: 20,
       #                wait_interval: 0.3,
@@ -252,7 +246,7 @@ module Appium
       #     # Start iOS driver as another format. 'url' is available like below
       #     opts = {
       #              url: "http://custom-host:8080/wd/hub.com",
-      #              desired_capabilities: {
+      #              capabilities: {
       #                platformName: :ios,
       #                platformVersion: '11.0',
       #                deviceName: 'iPhone Simulator',
@@ -260,7 +254,6 @@ module Appium
       #                app: '/path/to/MyiOS.app'
       #              },
       #              appium_lib: {
-      #                export_session: false,
       #                wait: 0,
       #                wait_timeout: 20,
       #                wait_interval: 0.3,
@@ -270,8 +263,58 @@ module Appium
       #     @core = Appium::Core.for(opts) # create a core driver with 'opts' and extend methods into 'self'
       #     @core.start_driver # start driver with 'url'. Connect to 'http://custom-host:8080/wd/hub.com'
       #
+      #     # With a custom listener
+      #     class CustomListener < ::Selenium::WebDriver::Support::AbstractEventListener
+      #       // something
+      #     end
+      #     capabilities: {
+      #       platformName: :ios,
+      #       platformVersion: '11.0',
+      #       deviceName: 'iPhone Simulator',
+      #       automationName: 'XCUITest',
+      #       app: '/path/to/MyiOS.app'
+      #     },
+      #     appium_lib: {
+      #       listener: CustomListener.new,
+      #     }
+      #     @core = Appium::Core.for capabilities: capabilities, appium_lib: appium_lib
+      #     @core.start_driver
+      #
       def self.for(opts = {})
-        new(opts)
+        new.setup_for_new_session(opts)
+      end
+
+      # Attach to an existing session. The main usage of this method is to attach to
+      # an existing session for debugging. The generated driver instance has the capabilities which
+      # has the given automationName and platformName only since the W3C WebDriver spec does not provide
+      # an endpoint to get running session's capabilities.
+      #
+      #
+      # @param [String] The session id to attach to.
+      # @param [String] url The WebDriver URL to attach to with the session_id.
+      # @param [String] automation_name The platform name to keep in the dummy capabilities
+      # @param [String] platform_name The automation name to keep in the dummy capabilities
+      # @return [Selenium::WebDriver] A new driver instance with the given session id.
+      #
+      # @example
+      #
+      #   new_driver = ::Appium::Core::Driver.attach_to(
+      #     driver.session_id,  # The 'driver' has an existing session id
+      #     url: 'http://127.0.0.1:4723/wd/hub', automation_name: 'UiAutomator2', platform_name: 'Android'
+      #   )
+      #   new_driver.page_source # for example
+      #
+      def self.attach_to(
+        session_id, url: nil, automation_name: nil, platform_name: nil,
+        http_client_ops: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 }
+      )
+        new.attach_to(
+          session_id,
+          automation_name: automation_name,
+          platform_name: platform_name,
+          url: url,
+          http_client_ops: http_client_ops
+        )
       end
 
       private
@@ -282,17 +325,25 @@ module Appium
         @delegate_target
       end
 
-      public
-
       # @private
-      def initialize(opts = {})
+      def initialize
         @delegate_target = self # for testing purpose
         @automation_name = nil # initialise before 'set_automation_name'
+      end
 
-        opts = Appium.symbolize_keys opts
-        validate_keys(opts)
+      public
+
+      # @private
+      # Set up for a new session
+      def setup_for_new_session(opts = {})
+        @custom_url = opts.delete :url # to set the custom url as :url
+
+        # TODO: Remove when we implement Options
+        # The symbolize_keys is to keep compatiility for the legacy code, which allows capabilities to give 'string' as the key.
+        # The toplevel `caps`, `capabilities` and `appium_lib` are expected to be symbol.
+        # FIXME: First, please try to remove `nested: true` to `nested: false`.
+        opts = Appium.symbolize_keys(opts, nested: true)
 
-        @custom_url = opts.delete :url
         @caps = get_caps(opts)
 
         set_appium_lib_specific_values(get_appium_lib_opts(opts))
@@ -301,8 +352,7 @@ module Appium
         set_automation_name
 
         extend_for(device: @device, automation_name: @automation_name)
-
-        self # rubocop:disable Lint/Void
+        self
       end
 
       # Creates a new global driver and quits the old one if it exists.
@@ -313,7 +363,7 @@ module Appium
       # @option http_client_ops [Hash] :http_client Custom HTTP Client
       # @option http_client_ops [Hash] :open_timeout Custom open timeout for http client.
       # @option http_client_ops [Hash] :read_timeout Custom read timeout for http client.
-      # @return [Selenium::WebDriver] the new global driver
+      # @return [Selenium::WebDriver] A new driver instance
       #
       # @example
       #
@@ -324,7 +374,7 @@ module Appium
       #
       #     # Start iOS driver
       #     opts = {
-      #              caps: {
+      #              capabilities: {
       #                platformName: :ios,
       #                platformVersion: '11.0',
       #                deviceName: 'iPhone Simulator',
@@ -365,19 +415,17 @@ module Appium
         end
 
         begin
-          # included https://github.com/SeleniumHQ/selenium/blob/43f8b3f66e7e01124eff6a5805269ee441f65707/rb/lib/selenium/webdriver/remote/driver.rb#L29
-          @driver = ::Appium::Core::Base::Driver.new(http_client: @http_client,
-                                                     desired_capabilities: @caps,
+          @driver = ::Appium::Core::Base::Driver.new(listener: @listener,
+                                                     http_client: @http_client,
+                                                     capabilities: @caps, # ::Appium::Core::Base::Capabilities
                                                      url: @custom_url,
-                                                     listener: @listener)
+                                                     wait_timeout: @wait_timeout,
+                                                     wait_interval: @wait_interval)
 
           if @direct_connect
             d_c = DirectConnections.new(@driver.capabilities)
             @driver.update_sending_request_to(protocol: d_c.protocol, host: d_c.host, port: d_c.port, path: d_c.path)
           end
-
-          # export session
-          write_session_id(@driver.session_id, @export_session_path) if @export_session
         rescue Errno::ECONNREFUSED
           raise "ERROR: Unable to connect to Appium. Is the server running on #{@custom_url}?"
         end
@@ -387,6 +435,8 @@ module Appium
           @http_client.additional_headers.delete Appium::Core::Base::Http::RequestHeaders::KEYS[:idempotency]
         end
 
+        # TODO: this method can be removed after releasing Appium 2.0, and after a while
+        # since Appium 2.0 reuqires 'automationName'. This method won't help anymore then.
         # If "automationName" is set only server side, this method set "automationName" attribute into @automation_name.
         # Since @automation_name is set only client side before start_driver is called.
         set_automation_name_if_nil
@@ -396,20 +446,53 @@ module Appium
         @driver
       end
 
-      private
+      # @private
+      # Attach to an existing session
+      def attach_to(session_id, url: nil, automation_name: nil, platform_name: nil,
+                    http_client_ops: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 })
 
-      def get_http_client(http_client: nil, open_timeout: nil, read_timeout: nil)
-        client = http_client || Appium::Core::Base::Http::Default.new
+        raise ::Appium::Core::Error::ArgumentError, 'The :url must not be nil' if url.nil?
+        raise ::Appium::Core::Error::ArgumentError, 'The :automation_name must not be nil' if automation_name.nil?
+        raise ::Appium::Core::Error::ArgumentError, 'The :platform_name must not be nil' if platform_name.nil?
+
+        @custom_url = url
+
+        # use lowercase internally
+        @automation_name = convert_downcase(automation_name)
+        @device = convert_downcase(platform_name)
+
+        extend_for(device: @device, automation_name: @automation_name)
 
-        # open_timeout and read_timeout are explicit wait.
-        client.open_timeout = open_timeout if open_timeout
-        client.read_timeout = read_timeout if read_timeout
+        @http_client = get_http_client http_client: http_client_ops.delete(:http_client),
+                                       open_timeout: http_client_ops.delete(:open_timeout),
+                                       read_timeout: http_client_ops.delete(:read_timeout)
+
+        # Note that 'enable_idempotency_header' works only a new session reqeust. The attach_to method skips
+        # the new session request, this it does not needed.
+
+        begin
+          # included https://github.com/SeleniumHQ/selenium/blob/43f8b3f66e7e01124eff6a5805269ee441f65707/rb/lib/selenium/webdriver/remote/driver.rb#L29
+          @driver = ::Appium::Core::Base::Driver.new(http_client: @http_client,
+                                                     url: @custom_url,
+                                                     listener: @listener,
+                                                     existing_session_id: session_id,
+                                                     automation_name: automation_name,
+                                                     platform_name: platform_name)
+        rescue Errno::ECONNREFUSED
+          raise "ERROR: Unable to connect to Appium. Is the server running on #{@custom_url}?"
+        end
 
-        client
+        @driver
+      end
+
+      def get_http_client(http_client: nil, open_timeout: nil, read_timeout: nil)
+        http_client || Appium::Core::Base::Http::Default.new(open_timeout: open_timeout, read_timeout: read_timeout)
       end
 
       # Ignore setting default wait if the target driver has no implementation
       def set_implicit_wait_by_default(wait)
+        return if @default_wait.nil?
+
         @driver.manage.timeouts.implicit_wait = wait
       rescue ::Selenium::WebDriver::Error::UnknownError => e
         unless e.message.include?('The operation requested is not yet implemented')
@@ -420,9 +503,7 @@ module Appium
         {}
       end
 
-      public
-
-      # Quits the driver
+      # [Deprecated] Quits the driver. This method is the same as @driver.quit
       # @return [void]
       #
       # @example
@@ -430,12 +511,14 @@ module Appium
       #   @core.quit_driver
       #
       def quit_driver
+        ::Appium::Logger.warn('[DEPRECATION] quit_driver will be removed. Please use @driver.quit instead.')
         @driver.quit
       rescue # rubocop:disable Style/RescueStandardError
         nil
       end
 
-      # Returns the server's version info
+      # Returns the server's version info. This method calls +driver.remote_status+ internally
+      #
       # @return [Hash]
       #
       # @example
@@ -449,58 +532,43 @@ module Appium
       #         }
       #     }
       #
-      # Returns blank hash for Selenium Grid since 'remote_status' gets 500 error
+      # Returns blank hash in a case +driver.remote_status+ got an error
+      # such as Selenium Grid. It returns 500 error against 'remote_status'.
       #
       # @example
       #
       #   @core.appium_server_version #=> {}
       #
       def appium_server_version
-        @driver.remote_status
-      rescue Selenium::WebDriver::Error::ServerError => e
-        raise ::Appium::Core::Error::ServerError unless e.message.include?('status code 500')
+        return {} if @driver.nil?
 
-        # driver.remote_status returns 500 error for using selenium grid
+        @driver.remote_status
+      rescue StandardError
+        # Ignore error case in a case the target appium server
+        # does not support `/status` API.
         {}
       end
 
-      # Return the platform version as an array of integers
-      # @return [Array<Integer>]
-      #
-      # @example
-      #
-      #     @core.platform_version #=> [10,1,1]
-      #
-      def platform_version
-        p_version = @driver.capabilities['platformVersion'] || @driver.session_capabilities['platformVersion']
-        p_version.split('.').map(&:to_i)
-      end
+      private
 
-      # Takes a png screenshot and saves to the target path.
-      #
-      # @param png_save_path [String] the full path to save the png
-      # @return [File]
-      #
-      # @example
-      #
-      #   @core.screenshot '/tmp/hi.png' #=> nil
-      #   # same as '@driver.save_screenshot png_save_path'
-      #
-      def screenshot(png_save_path)
-        ::Appium::Logger.warn '[DEPRECATION] screenshot will be removed. Please use driver.save_screenshot instead.'
-        @driver.save_screenshot png_save_path
+      def convert_to_symbol(value)
+        if value.nil?
+          value
+        else
+          value.to_sym
+        end
       end
 
-      private
-
       # @private
       def extend_for(device:, automation_name:) # rubocop:disable Metrics/CyclomaticComplexity
         extend Appium::Core
         extend Appium::Core::Device
 
-        case device
+        sym_automation_name = convert_to_symbol(automation_name)
+
+        case convert_to_symbol(device)
         when :android
-          case automation_name
+          case sym_automation_name
           when :espresso
             ::Appium::Core::Android::Espresso::Bridge.for self
           when :uiautomator2
@@ -511,28 +579,26 @@ module Appium
             ::Appium::Core::Android::Uiautomator1::Bridge.for self
           end
         when :ios, :tvos
-          case automation_name
+          case sym_automation_name
           when :safari
             ::Appium::Logger.debug('SafariDriver for iOS')
-          when :xcuitest
+          else # XCUITest
             ::Appium::Core::Ios::Xcuitest::Bridge.for self
-          else # default and UIAutomation
-            ::Appium::Core::Ios::Uiautomation::Bridge.for self
           end
         when :mac
-          case automation_name
+          case sym_automation_name
           when :safari
             ::Appium::Logger.debug('SafariDriver for macOS')
           when :gecko
             ::Appium::Logger.debug('Gecko Driver for macOS')
           when :mac2
-            ::Appium::Logger.debug('macOS XCUITest')
+            ::Appium::Core::Mac2::Bridge.for self
           else
             # no Mac specific extentions
             ::Appium::Logger.debug('macOS Native')
           end
         when :windows
-          case automation_name
+          case sym_automation_name
           when :gecko
             ::Appium::Logger.debug('Gecko Driver for Windows')
           else
@@ -542,7 +608,7 @@ module Appium
           # https://github.com/Samsung/appium-tizen-driver
           ::Appium::Logger.debug('tizen')
         else
-          case automation_name
+          case sym_automation_name
           when :youiengine
             # https://github.com/YOU-i-Labs/appium-youiengine-driver
             ::Appium::Logger.debug('YouiEngine')
@@ -559,36 +625,9 @@ module Appium
         self
       end
 
-      # @private
-      def validate_keys(opts)
-        flatten_ops = flatten_hash_keys(opts)
-
-        # FIXME: Remove 'desired_capabilities' in the next major Selenium update
-        unless opts.member?(:caps) || opts.member?(:capabilities) || opts.member?(:desired_capabilities)
-          raise Error::NoCapabilityError
-        end
-
-        if !opts.member?(:appium_lib) && flatten_ops.member?(:appium_lib)
-          raise Error::CapabilityStructureError, 'Please check the value of appium_lib in the capability'
-        end
-
-        true
-      end
-
-      # @private
-      def flatten_hash_keys(hash, flatten_keys_result = [])
-        hash.each do |key, value|
-          flatten_keys_result << key
-          flatten_hash_keys(value, flatten_keys_result) if value.is_a?(Hash)
-        end
-
-        flatten_keys_result
-      end
-
       # @private
       def get_caps(opts)
-        # FIXME: Remove 'desired_capabilities' in the next major Selenium update
-        Core::Base::Capabilities.create_capabilities(opts[:caps] || opts[:capabilities] || opts[:desired_capabilities] || {})
+        Core::Base::Capabilities.new(opts[:caps] || opts[:capabilities] || {})
       end
 
       # @private
@@ -601,6 +640,7 @@ module Appium
       # The path can be local, HTTP/S, Windows Share and other path like 'sauce-storage:'.
       # Use @caps[:app] without modifications if the path isn't HTTP/S or local path.
       def set_app_path
+        # FIXME: maybe `:app` should check `app` as well.
         return unless @caps && @caps[:app] && !@caps[:app].empty?
         return if @caps[:app] =~ URI::DEFAULT_PARSER.make_regexp
 
@@ -623,9 +663,6 @@ module Appium
 
         @default_wait = opts.default_wait
 
-        @export_session = opts.export_session
-        @export_session_path = opts.export_session_path
-
         @port = opts.port
 
         @wait_timeout  = opts.wait_timeout
@@ -639,18 +676,24 @@ module Appium
       # @private
       def set_appium_device
         # https://code.google.com/p/selenium/source/browse/spec-draft.md?repo=mobile
-        @device = @caps[:platformName]
+        # TODO: check if the Appium.symbolize_keys(opts, nested: false) enoug with this
+        @device = @caps[:platformName] || @caps['platformName']
         return @device unless @device
 
-        @device = @device.is_a?(Symbol) ? @device.downcase : @device.downcase.strip.intern
+        @device = convert_downcase @device
       end
 
       # @private
       def set_automation_name
-        @automation_name = @caps[:automationName] if @caps[:automationName]
-        @automation_name = if @automation_name
-                             @automation_name.is_a?(Symbol) ? @automation_name.downcase : @automation_name.downcase.strip.intern
-                           end
+        # TODO: check if the Appium.symbolize_keys(opts, nested: false) enoug with this
+        candidate = @caps[:automationName] || @caps['automationName']
+        @automation_name = candidate if candidate
+        @automation_name = convert_downcase @automation_name if @automation_name
+      end
+
+      # @private
+      def convert_downcase(value)
+        value.is_a?(Symbol) ? value.downcase : value.downcase.strip.intern
       end
 
       # @private
@@ -661,15 +704,6 @@ module Appium
                              @driver.capabilities['automationName'].downcase.strip.intern
                            end
       end
-
-      # @private
-      def write_session_id(session_id, export_path = '/tmp/appium_lib_session')
-        export_path = export_path.tr('/', '\\') if ::Appium::Core::Base.platform.windows?
-        File.write(export_path, session_id)
-      rescue IOError => e
-        ::Appium::Logger.warn e
-        nil
-      end
     end # class Driver
   end # module Core
 end # module Appium