appium_lib_core 5.0.0 → 6.3.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,7 +26,6 @@ module Appium
     end
 
     module Ios
-      autoload :Uiautomation, 'appium_lib_core/ios'
       autoload :Xcuitest, 'appium_lib_core/ios_xcuitest'
     end
 
@@ -76,6 +78,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
 
@@ -89,10 +98,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
 
@@ -175,7 +184,8 @@ module Appium
       # - <code>directConnectPort</code>
       # - <code>directConnectPath</code>
       #
-      # Ignore them if this parameter is <code>false</code>. Defaults to true.
+      # 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
@@ -266,8 +276,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
@@ -278,17 +338,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
+
+      public
 
-        opts = Appium.symbolize_keys opts
-        validate_keys(opts)
+      # @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))
@@ -297,8 +365,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.
@@ -309,7 +376,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
       #
@@ -363,11 +430,10 @@ module Appium
         begin
           @driver = ::Appium::Core::Base::Driver.new(listener: @listener,
                                                      http_client: @http_client,
-                                                     capabilities: @caps, # ::Selenium::WebDriver::Remote::Capabilities
+                                                     capabilities: @caps, # ::Appium::Core::Base::Capabilities
                                                      url: @custom_url,
                                                      wait_timeout: @wait_timeout,
-                                                     wait_interval: @wait_interval,
-                                                     automation_name: @automation_name)
+                                                     wait_interval: @wait_interval)
 
           if @direct_connect
             d_c = DirectConnections.new(@driver.capabilities)
@@ -385,6 +451,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
@@ -394,7 +462,47 @@ 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 })
+
+        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)
+
+        @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)
+
+          # 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
+
+        @driver
+      end
 
       def get_http_client(http_client: nil, open_timeout: nil, read_timeout: nil)
         client = http_client || Appium::Core::Base::Http::Default.new
@@ -420,9 +528,7 @@ module Appium
         {}
       end
 
-      public
-
-      # Quits the driver
+      # [Deprecated] Quits the driver. This method is the same as @driver.quit
       # @return [void]
       #
       # @example
@@ -430,6 +536,7 @@ 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
@@ -475,20 +582,35 @@ module Appium
       #     @core.platform_version #=> [10,1,1]
       #
       def platform_version
+        ::Appium::Logger.warn(
+          '[DEPRECATION] platform_version method will be. ' \
+          'Please check the platformVersion via @driver.capabilities["platformVersion"] instead.'
+        )
+
         p_version = @driver.capabilities['platformVersion'] || @driver.session_capabilities['platformVersion']
         p_version.split('.').map(&:to_i)
       end
 
       private
 
+      def convert_to_symbol(value)
+        if value.nil?
+          value
+        else
+          value.to_sym
+        end
+      end
+
       # @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
@@ -499,16 +621,14 @@ 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
@@ -520,7 +640,7 @@ module Appium
             ::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
@@ -530,7 +650,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')
@@ -547,32 +667,9 @@ module Appium
         self
       end
 
-      # @private
-      def validate_keys(opts)
-        flatten_ops = flatten_hash_keys(opts)
-
-        raise Error::NoCapabilityError unless opts.member?(:caps) || opts.member?(:capabilities)
-
-        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)
-        Core::Base::Capabilities.create_capabilities(opts[:caps] || opts[:capabilities] || {})
+        Core::Base::Capabilities.new(opts[:caps] || opts[:capabilities] || {})
       end
 
       # @private
@@ -585,6 +682,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,18 +721,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
@@ -648,6 +752,10 @@ module Appium
 
       # @private
       def write_session_id(session_id, export_path = '/tmp/appium_lib_session')
+        ::Appium::Logger.warn(
+          '[DEPRECATION] export_session option will be removed. ' \
+          'Please save the session id by yourself with #session_id method like @driver.session_id.'
+        )
         export_path = export_path.tr('/', '\\') if ::Appium::Core::Base.platform.windows?
         File.write(export_path, session_id)
       rescue IOError => e

data/lib/appium_lib_core/support/event_firing_bridge.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Appium
+  module Support
+    class EventFiringBridge < ::Selenium::WebDriver::Support::EventFiringBridge
+      # This module inherits ::Selenium::WebDriver::Support::EventFiringBridge
+      # to provide customer listener availability.
+      # https://github.com/SeleniumHQ/selenium/blob/trunk/rb/lib/selenium/webdriver/support/event_firing_bridge.rb#L79
+
+      def initialize(delegate, listener, **opts)
+        @appium_options = opts
+        super delegate, listener
+      end
+
+      def find_element_by(how, what, parent = nil)
+        e = dispatch(:find, how, what, driver) do
+          @delegate.find_element_by how, what, parent
+        end
+
+        ::Appium::Core::Element.new self, e.ref.last
+      end
+
+      def find_elements_by(how, what, parent = nil)
+        es = dispatch(:find, how, what, driver) do
+          @delegate.find_elements_by(how, what, parent)
+        end
+
+        es.map { |e| ::Appium::Core::Element.new self, e.ref.last }
+      end
+
+      private
+
+      def create_element(ref)
+        ::Appium::Core::Element.new @delegate, ref
+      end
+
+      def driver
+        # To not gives the listener
+        @appium_options.delete(:listener)
+
+        @driver ||= ::Appium::Core::Base::Driver.new(bridge: self, listener: nil, **@appium_options)
+      end
+    end
+  end
+end

data/lib/appium_lib_core/version.rb

@@ -14,7 +14,7 @@
 
 module Appium
   module Core
-    VERSION = '5.0.0' unless defined? ::Appium::Core::VERSION
-    DATE    = '2021-11-05' unless defined? ::Appium::Core::DATE
+    VERSION = '6.3.0' unless defined? ::Appium::Core::VERSION
+    DATE    = '2023-03-14' unless defined? ::Appium::Core::DATE
   end
 end

data/lib/appium_lib_core/{ios/uiautomation/bridge.rb → windows/device/app_management.rb}

@@ -14,17 +14,25 @@
 
 module Appium
   module Core
-    module Ios
-      module Uiautomation
-        module Bridge
-          def self.for(target)
-            target.extend Appium::Core::Ios::Device
+    module Windows
+      module Device
+        module AppManagement
+          # override
+          def self.add_methods
+            ::Appium::Core::Device.add_endpoint_method(:launch_app) do
+              def launch_app
+                execute :launch_app
+              end
+            end
 
-            Core::Ios::Uiautomation.patch_webdriver_element
-            Core::Ios::Uiautomation::Device.add_methods
+            ::Appium::Core::Device.add_endpoint_method(:close_app) do
+              def close_app
+                execute :close_app
+              end
+            end
           end
-        end
-      end
-    end
-  end
-end
+        end # module AppManagement
+      end # module Device
+    end # module Windows
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/windows/device.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require_relative 'device/screen'
+require_relative 'device/app_management'
 
 module Appium
   module Core
@@ -78,6 +79,7 @@ module Appium
         class << self
           def extended(_mod)
             Screen.add_methods
+            AppManagement.add_methods
           end
         end # class << self
       end # module Device

data/lib/appium_lib_core.rb

@@ -19,18 +19,28 @@ require_relative 'appium_lib_core/common'
 require_relative 'appium_lib_core/driver'
 require_relative 'appium_lib_core/device'
 require_relative 'appium_lib_core/element'
+require_relative 'appium_lib_core/support/event_firing_bridge'
 
 module Appium
-  # convert all keys (including nested) to symbols
+  # @private
+  #
+  # convert the top level keys to symbols.
   #
-  # based on deep_symbolize_keys & deep_transform_keys from rails
-  # https://github.com/rails/docrails/blob/a3b1105ada3da64acfa3843b164b14b734456a50/activesupport/lib/active_support/core_ext/hash/keys.rb#L84
   # @param [Hash] hash Hash value to make symbolise
-  def self.symbolize_keys(hash)
+  def self.symbolize_keys(hash, nested: false, enable_deprecation_msg: true)
+    # FIXME: As https://github.com/appium/ruby_lib/issues/945, we must remove this implicit string to symbol.
+    # But appium_lib_core's some capability handling expect to be symbol, so we should test to remove
+    # the mehotds which expect the symbol first.
     raise ::Appium::Core::Error::ArgumentError, 'symbolize_keys requires a hash' unless hash.is_a? Hash
 
     hash.each_with_object({}) do |pair, acc|
       key = begin
+        if enable_deprecation_msg && !(pair[0].is_a? Symbol)
+          ::Appium::Logger.warn("[Deprecation] The key '#{pair[0]}' must be a symbol while currently it " \
+                                "is #{pair[0].class.name}. Please define the key as a Symbol. " \
+                                'Converting it to Symbol for now.')
+        end
+
         pair[0].to_sym
       rescue StandardError => e
         ::Appium::Logger.warn(e.message)
@@ -38,7 +48,11 @@ module Appium
       end
 
       value = pair[1]
-      acc[key] = value.is_a?(Hash) ? symbolize_keys(value) : value
+      acc[key] = if nested
+                   value.is_a?(Hash) ? symbolize_keys(value, nested: false, enable_deprecation_msg: false) : value
+                 else
+                   value
+                 end
     end
   end