appium_lib_core 4.1.0 → 9.0.0

data/lib/appium_lib_core/common/base/driver.rb

@@ -13,8 +13,15 @@
 # limitations under the License.
 
 require 'base64'
+require_relative 'device_ime'
+require_relative 'driver_settings'
 require_relative 'search_context'
 require_relative 'screenshot'
+require_relative 'rotable'
+require_relative 'remote_status'
+require_relative 'has_location'
+require_relative 'has_network_connection'
+require_relative '../wait'
 
 module Appium
   module Core
@@ -22,42 +29,75 @@ module Appium
       class Driver < ::Selenium::WebDriver::Driver
         include ::Selenium::WebDriver::DriverExtensions::UploadsFiles
         include ::Selenium::WebDriver::DriverExtensions::HasSessionId
-        include ::Selenium::WebDriver::DriverExtensions::Rotatable
-        include ::Selenium::WebDriver::DriverExtensions::HasRemoteStatus
         include ::Selenium::WebDriver::DriverExtensions::HasWebStorage
 
+        include ::Appium::Core::Base::Rotatable
         include ::Appium::Core::Base::SearchContext
-        include ::Appium::Core::Base::TakeScreenshot
+        include ::Appium::Core::Base::TakesScreenshot
+        include ::Appium::Core::Base::HasRemoteStatus
+        include ::Appium::Core::Base::HasLocation
+        include ::Appium::Core::Base::HasNetworkConnection
+
+        include ::Appium::Core::Waitable
 
         # Private API.
         # Do not use this for general use. Used by flutter driver to get bridge for creating a new element
         attr_reader :bridge
 
-        def initialize(opts = {})
-          listener = opts.delete(:listener)
-          @bridge = ::Appium::Core::Base::Bridge.handshake(**opts)
-          if @bridge.dialect == :oss # MJSONWP
-            extend ::Selenium::WebDriver::DriverExtensions::HasTouchScreen
-            extend ::Selenium::WebDriver::DriverExtensions::HasLocation
-            extend ::Selenium::WebDriver::DriverExtensions::HasNetworkConnection
-          elsif @bridge.dialect == :w3c
-            # TODO: Only for Appium. Ideally, we'd like to remove the below like selenium-webdriver
-            extend ::Selenium::WebDriver::DriverExtensions::HasTouchScreen
-            extend ::Selenium::WebDriver::DriverExtensions::HasLocation
-            extend ::Selenium::WebDriver::DriverExtensions::HasNetworkConnection
-          end
-          super(@bridge, listener: listener)
+        # override
+        def initialize(bridge: nil, listener: nil, **opts) # rubocop:disable Lint/MissingSuper
+          original_opts = opts.dup
+
+          # For ::Appium::Core::Waitable
+          @wait_timeout = opts.delete(:wait_timeout)
+          @wait_interval = opts.delete(:wait_interval)
+
+          # Selenium WebDriver attributes
+          @devtools = nil
+          @bidi = nil
+
+          # in the selenium webdriver as well
+          bridge ||= create_bridge(**opts)
+          add_extensions(bridge.browser)
+          @bridge = listener ? ::Appium::Support::EventFiringBridge.new(bridge, listener, **original_opts) : bridge
         end
 
-        # Get the dialect value
-        # @return [:oss|:w3c]
-        def dialect
-          @bridge.dialect
+        private
+
+        # Create a proper bridge instance.
+        #
+        # @return [::Appium::Core::Base::Bridge]
+        #
+        def create_bridge(**opts)
+          # for a new session request
+          capabilities = opts.delete(:capabilities)
+          bridge_opts = { http_client: opts.delete(:http_client), url: opts.delete(:url) }
+
+          # for attaching to an existing session
+          session_id = opts.delete(:existing_session_id)
+          automation_name = opts.delete(:automation_name)
+          platform_name = opts.delete(:platform_name)
+
+          raise ::Appium::Core::Error::ArgumentError, "Unable to create a driver with parameters: #{opts}" unless opts.empty?
+
+          bridge = ::Appium::Core::Base::Bridge.new(**bridge_opts)
+
+          if session_id.nil?
+            bridge.create_session(capabilities)
+          else
+            # attach to the existing session id
+            bridge.attach_to(session_id, platform_name, automation_name)
+          end
+
+          bridge
         end
 
+        public
+
         # Update +server_url+ and HTTP clients following this arguments, protocol, host, port and path.
         # After this method, +@bridge.http+ will be a new instance following them instead of +server_url+ which is
         # set before creating session.
+        # If +@bridge.http+ did not have +update_sending_request_to+ method, this method returns immediately.
         #
         # @example
         #
@@ -66,14 +106,125 @@ module Appium
         #     driver.manage.timeouts.implicit_wait = 10 # @bridge.http is for 'https://example2.com:9000/wd/hub/'
         #
         def update_sending_request_to(protocol:, host:, port:, path:)
-          @bridge.http.update_sending_request_to(scheme: protocol,
-                                                 host: host,
-                                                 port: port,
-                                                 path: path)
+          unless @bridge.http&.class&.method_defined? :update_sending_request_to
+            ::Appium::Logger.warn "#{@bridge.http&.class} has no 'update_sending_request_to'. " \
+                                  'It keeps current connection target.'
+            return
+          end
+
+          @bridge.http&.update_sending_request_to(scheme: protocol,
+                                                  host: host,
+                                                  port: port,
+                                                  path: path)
+        end
+
+        AVAILABLE_METHODS = [
+          :get, :head, :post, :put, :delete,
+          :connect, :options, :trace, :patch
+        ].freeze
+        # Define a new custom method to the driver so that you can define your own method for
+        # drivers/plugins in Appium 2.0. Appium 2.0 and its custom drivers/plugins allow you
+        # to define custom commands that are not part of W3C spec.
+        #
+        # @param [Symbol] method HTTP request method as https://www.w3.org/TR/webdriver/#endpoints
+        # @param [string] url The url to URL template as https://www.w3.org/TR/webdriver/#endpoints.
+        #                     +:session_id+ is the placeholder of 'session id'.
+        #                     Other place holders can be specified with +:+ prefix like +:id+.
+        #                     Then, the +:id+ will be replaced with a given value as the seconds argument of +execute+
+        # @param [Symbol] name The name of method that is called as the driver instance method.
+        # @param [Proc] block The block to involve as the method.
+        #                     Please define a method that has the same +name+ with arguments you want.
+        #                     The method must has +execute+ method. tHe +execute+ is calls the +url+
+        #                     with the given parameters.
+        #                     The first argument should be +name+ as symbol.
+        #                     The second argument should be hash. If keys in the hash matches +:+ prefix
+        #                     string in the given url, the matched string in the given url will be
+        #                     values in the hash.
+        #                     The third argument should be hash. The hash will be the request body.
+        #                     Please read examples below for more details.
+        # @raise [ArgumentError] If the given +method+ is invalid value.
+        #
+        # @example
+        #
+        #   @driver.add_command(
+        #     method: :get,
+        #     url: 'session/:session_id/path/to/custom/url',
+        #     name: :test_command
+        #   )
+        #   # Send a GET request to 'session/<session id>/path/to/custom/url'
+        #   @driver.test_command
+        #
+        #
+        #   @driver.add_command(
+        #     method: :post,
+        #     url: 'session/:session_id/path/to/custom/url',
+        #     name: :test_command
+        #   ) do
+        #     def test_command(argument)
+        #       execute(:test_command, {}, { dummy: argument })
+        #     end
+        #   end
+        #   # Send a POST request to 'session/<session id>/path/to/custom/url'
+        #   # with body "{ dummy: 1 }" as JSON object. "1" is the argument.
+        #   # ':session_id' in the given 'url' is replaced with current 'session id'.
+        #   @driver.test_command(1)
+        #
+        #
+        #   @driver.add_command(
+        #     method: :post,
+        #     url: 'session/:session_id/element/:id/custom/action',
+        #     name: :test_action_command
+        #   ) do
+        #     def test_action_command(element_id, action)
+        #       execute(:test_action_command, {id: element_id}, { dummy_action: action })
+        #     end
+        #   end
+        #   # Send a POST request to 'session/<session id>/element/<element id>/custom/action'
+        #   # with body "{ dummy_action: #{action} }" as JSON object. "action" is the seconds argument.
+        #   # ':session_id' in the given url is replaced with current 'session id'.
+        #   # ':id' in the given url is replaced with the given 'element_id'.
+        #   e = @driver.find_element :accessibility_id, 'an element'
+        #   @driver.test_action_command(e.id, 'action')
+        #
+        def add_command(method:, url:, name:, &block)
+          unless AVAILABLE_METHODS.include? method
+            raise ::Appium::Core::Error::ArgumentError, "Available method is either #{AVAILABLE_METHODS}"
+          end
+
+          # TODO: Remove this logger before Appium 2.0 release
+          ::Appium::Logger.info '[Experimental] this method is experimental for Appium 2.0. This interface may change.'
+
+          @bridge.add_command method: method, url: url, name: name, &block
         end
 
         ### Methods for Appium
 
+        # Perform 'key' actions for W3C module.
+        # Generate +key+ pointer action here and users can use this via +driver.key_action+
+        # - https://www.selenium.dev/selenium/docs/api/rb/Selenium/WebDriver/ActionBuilder.html
+        # - https://www.selenium.dev/selenium/docs/api/rb/Selenium/WebDriver/KeyActions.html
+        #
+        # The pointer type is 'key' by default in the Appium Ruby client.
+        # +driver.action+ in Appium Ruby client has 'pointer' action by default.
+        # This method is a shortcut to set 'key' type.
+        # Hense this method is equal to +driver.action(devices: [::Selenium::WebDriver::Interactions.key('keyboard')])+
+        # as below example.
+        #
+        # @example
+        #
+        #     element = @driver.find_element(:id, "some id")
+        #     @driver.key_action.send_key('hiあ').perform # The 'send_key' is a part of 'KeyActions'
+        #     # is equal to:
+        #     # @driver.action(devices: [::Selenium::WebDriver::Interactions.key('keyboard')]).send_keys('hiあ').perform
+        #
+        def key_action(async: false)
+          @bridge.action(
+            async: async,
+            devices: [::Selenium::WebDriver::Interactions.key('keyboard')]
+          )
+        end
+
+        # @deprecated Use 'mobile: lock' extension instead.
         # Lock the device
         # @return [String]
         #
@@ -84,9 +235,11 @@ module Appium
         #                   #   Block other commands during locking the device.
         #
         def lock(duration = nil)
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: lock' extension instead"
           @bridge.lock(duration)
         end
 
+        # @deprecated Use 'mobile: isLocked' extension instead.
         # Check current device status is weather locked or not
         #
         # @example
@@ -95,10 +248,12 @@ module Appium
         #   @driver.locked?
         #
         def locked?
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: isLocked' extension instead"
           @bridge.device_locked?
         end
         alias device_locked? locked?
 
+        # @deprecated Use 'mobile: unlock' extension instead.
         # Unlock the device
         #
         # @example
@@ -106,9 +261,11 @@ module Appium
         #   @driver.unlock
         #
         def unlock
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: unlock' extension instead"
           @bridge.unlock
         end
 
+        # @deprecated Use 'mobile: hideKeyboard' extension instead.
         # Hide the onscreen keyboard
         # @param [String] close_key The name of the key which closes the keyboard.
         #   Defaults to 'Done' for iOS(except for XCUITest).
@@ -123,9 +280,11 @@ module Appium
         #   @driver.hide_keyboard(nil, :tapOutside) # Close a keyboard with tapping out side of keyboard
         #
         def hide_keyboard(close_key = nil, strategy = nil)
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: hideKeyboard' extension instead"
           @bridge.hide_keyboard close_key, strategy
         end
 
+        # @deprecated Use 'mobile: isKeyboardShown' extension instead.
         # Get whether keyboard is displayed or not.
         # @return [Boolean] Return true if keyboard is shown. Return false if keyboard is hidden.
         #
@@ -134,42 +293,11 @@ module Appium
         #   @driver.keyboard_shown?   # true
         #
         def keyboard_shown?
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: isKeyboardShown' extension instead"
           @bridge.is_keyboard_shown
         end
         alias is_keyboard_shown keyboard_shown?
 
-        # [DEPRECATION]
-        # Send keys for a current active element
-        # @param [String] key Input text
-        #
-        # @example
-        #
-        #   @driver.send_keys 'happy testing!'
-        #
-        def send_keys(*key)
-          ::Appium::Logger.warn(
-            '[DEPRECATION] Driver#send_keys is deprecated in W3C spec. Use driver.action.<command>.perform instead'
-          )
-          @bridge.send_keys_to_active_element(key)
-        end
-        alias type send_keys
-
-        class DriverSettings
-          # @private this class is private
-          def initialize(bridge)
-            @bridge = bridge
-          end
-
-          def get
-            @bridge.get_settings
-          end
-
-          def update(settings)
-            @bridge.update_settings(settings)
-          end
-        end
-        private_constant :DriverSettings
-
         # Returns an instance of DriverSettings to call get/update.
         #
         # @example
@@ -178,7 +306,7 @@ module Appium
         #   @driver.settings.update('allowInvisibleElements': true)
         #
         def settings
-          @driver_settings ||= DriverSettings.new(@bridge) # rubocop:disable Naming/MemoizedInstanceVariableName
+          @settings ||= DriverSettings.new(@bridge)
         end
 
         # Get appium Settings for current test session.
@@ -200,8 +328,8 @@ module Appium
         #
         # @example
         #
-        #   @driver.update_settings('allowInvisibleElements': true)
-        #   @driver.settings.update('allowInvisibleElements': true)
+        #   @driver.update_settings({ 'allowInvisibleElements': true })
+        #   @driver.settings.update({ 'allowInvisibleElements': true })
         #   @driver.settings = { 'allowInvisibleElements': true }
         #
         def settings=(value)
@@ -209,36 +337,11 @@ module Appium
         end
         alias update_settings settings=
 
-        class DeviceIME
-          # @private this class is private
-          def initialize(bridge)
-            @bridge = bridge
-          end
-
-          def activate(ime_name)
-            @bridge.ime_activate(ime_name)
-          end
-
-          def available_engines
-            @bridge.ime_available_engines
-          end
-
-          def active_engine
-            @bridge.ime_active_engine
-          end
-
-          def activated?
-            @bridge.ime_activated
-          end
-
-          def deactivate
-            @bridge.ime_deactivate
-          end
-        end
-        private_constant :DeviceIME
-
+        # @deprecated Use 'mobile: shell' extension instead.
         # Returns an instance of DeviceIME
         #
+        # @return [Appium::Core::Base::Driver::DeviceIME]
+        #
         # @example
         #
         #   @driver.ime.activate engine: 'com.android.inputmethod.latin/.LatinIME'
@@ -248,9 +351,11 @@ module Appium
         #   @driver.ime.deactivate #=> Deactivate current IME engine
         #
         def ime
-          @device_ime ||= DeviceIME.new(@bridge) # rubocop:disable Naming/MemoizedInstanceVariableName
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: shell' extension instead"
+          @ime ||= DeviceIME.new(@bridge)
         end
 
+        # @deprecated Use 'mobile: shell' extension instead.
         # Android only. Make an engine that is available active.
         #
         # @param [String] ime_name The IME owning the activity [required]
@@ -264,6 +369,7 @@ module Appium
           ime.activate(ime_name)
         end
 
+        # @deprecated Use 'mobile: shell' extension instead.
         # Android only. List all available input engines on the machine.
         #
         # @example
@@ -275,6 +381,7 @@ module Appium
           ime.available_engines
         end
 
+        # @deprecated Use 'mobile: shell' extension instead.
         # Android only. Get the name of the active IME engine.
         #
         # @example
@@ -286,9 +393,12 @@ module Appium
           ime.active_engine
         end
 
+        # @deprecated Use 'mobile: shell' extension instead.
         # @!method ime_activated
         #   Android only. Indicates whether IME input is active at the moment (not if it is available).
         #
+        # @return [Boolean]
+        #
         # @example
         #
         #   @driver.ime_activated #=> True if IME is activated
@@ -298,6 +408,7 @@ module Appium
           ime.activated?
         end
 
+        # @deprecated Use 'mobile: shell' extension instead.
         # Android only. De-activates the currently-active IME engine.
         #
         # @example
@@ -323,16 +434,6 @@ module Appium
           block_given? ? @bridge.within_context(context, &block) : @bridge.within_context(context)
         end
 
-        # Change to the default context. This is equivalent to +set_context nil+.
-        #
-        # @example
-        #
-        #   @driver.switch_to_default_context
-        #
-        def switch_to_default_context
-          @bridge.switch_to_default_context
-        end
-
         # @return [String] The context currently being used.
         #
         # @example
@@ -361,47 +462,15 @@ module Appium
         #   @driver.set_context "NATIVE_APP"
         #   @driver.context = "NATIVE_APP"
         #
-        def context=(context = null)
+        def context=(context = nil)
           @bridge.set_context(context)
         end
         alias set_context context=
 
-        # Set the value to element directly
-        #
-        # @example
-        #
-        #   @driver.set_immediate_value element, 'hello'
-        #
-        def set_immediate_value(element, *value)
-          ::Appium::Logger.warn '[DEPRECATION] driver#set_immediate_value(element, *value) is deprecated. ' \
-            'Use Element#immediate_value(*value) instead'
-          @bridge.set_immediate_value(element, *value)
-        end
-
-        # Replace the value to element directly
-        #
-        # @example
-        #
-        #   @driver.replace_value element, 'hello'
-        #
-        def replace_value(element, *value)
-          ::Appium::Logger.warn '[DEPRECATION] driver#replace_value(element, *value) is deprecated. ' \
-            'Use Element#replace_value(*value) instead'
-          @bridge.replace_value(element, *value)
-        end
-
         # Place a file in a specific location on the device.
-        # On iOS, the server should have ifuse libraries installed and configured properly for this feature to work on
-        # real devices.
         # On Android, the application under test should be built with debuggable flag enabled in order to get access to
         # its container on the internal file system.
         #
-        # {https://github.com/libimobiledevice/ifuse iFuse GitHub page6}
-        #
-        # {https://github.com/osxfuse/osxfuse/wiki/FAQ osxFuse FAQ}
-        #
-        # {https://developer.android.com/studio/debug 'Debug Your App' developer article}
-        #
         # @param [String] path Either an absolute path OR, for iOS devices, a path relative to the app, as described.
         #                      If the path starts with application id prefix, then the file will be pushed to the root of
         #                      the corresponding application container.
@@ -415,21 +484,14 @@ module Appium
         #   @driver.push_file "/sdcard/Pictures", file # Push a file binary to /sdcard/Pictures path in Android
         #
         def push_file(path, filedata)
+          # TODO: use 'mobile: pushFile' internally
           @bridge.push_file(path, filedata)
         end
 
-        # Pull a file from the simulator/device.
-        # On iOS the server should have ifuse
-        # libraries installed and configured properly for this feature to work on real devices.
+        # Pull a file from the remote device.
         # On Android the application under test should be built with debuggable flag enabled in order to get access
         # to its container on the internal file system.
         #
-        # {https://github.com/libimobiledevice/ifuse iFuse GitHub page6}
-        #
-        # {https://github.com/osxfuse/osxfuse/wiki/FAQ osxFuse FAQ}
-        #
-        # {https://developer.android.com/studio/debug 'Debug Your App' developer article}
-        #
         # @param [String] path Either an absolute path OR, for iOS devices, a path relative to the app, as described.
         #                      If the path starts with application id prefix, then the file will be pulled from the root
         #                      of the corresponding application container.
@@ -438,7 +500,6 @@ module Appium
         #                      Only pulling files from application containers is supported for iOS Simulator.
         #                      Provide the remote path in format
         #                      <code>@bundle.identifier:container_type/relative_path_in_container</code>
-        #                      (Make sure this in ifuse doc)
         #
         # @return [Base64-decoded] Base64 decoded data
         #
@@ -452,21 +513,14 @@ module Appium
         #   File.open('proper_filename', 'wb') { |f| f<< decoded_file }
         #
         def pull_file(path)
+          # TODO: use 'mobile: pullFile' internally
           @bridge.pull_file(path)
         end
 
-        # Pull a folder content from the simulator/device.
-        # On iOS the server should have ifuse libraries installed and configured properly for this feature to work
-        # on real devices.
+        # Pull a folder content from the remote device.
         # On Android the application under test should be built with debuggable flag enabled in order to get access to
         # its container on the internal file system.
         #
-        # {https://github.com/libimobiledevice/ifuse iFuse GitHub page6}
-        #
-        # {https://github.com/osxfuse/osxfuse/wiki/FAQ osxFuse FAQ}
-        #
-        # {https://developer.android.com/studio/debug 'Debug Your App' developer article}
-        #
         # @param [String] path Absolute path to the folder.
         #                      If the path starts with <em>@applicationId/</em> prefix, then the folder will be pulled
         #                      from the root of the corresponding application container.
@@ -475,7 +529,6 @@ module Appium
         #                      Only pulling files from application containers is supported for iOS Simulator.
         #                      Provide the remote path in format
         #                      <code>@bundle.identifier:container_type/relative_path_in_container</code>
-        #                      (Make sure this in ifuse doc)
         #
         # @return [Base64-decoded] Base64 decoded data which is zip archived
         #
@@ -486,22 +539,11 @@ module Appium
         #   File.open('proper_filename', 'wb') { |f| f<< decoded_file }
         #
         def pull_folder(path)
+          # TODO: use 'mobile: pullFolder' internally
           @bridge.pull_folder(path)
         end
 
-        # Send keyevent on the device.(Only for Selendroid)
-        # http://developer.android.com/reference/android/view/KeyEvent.html
-        # @param [integer] key The key to press.
-        # @param [String] metastate The state the metakeys should be in when pressing the key.
-        #
-        # @example
-        #
-        #   @driver.keyevent 82
-        #
-        def keyevent(key, metastate = nil)
-          @bridge.keyevent(key, metastate)
-        end
-
+        # @deprecated Use 'mobile: pressKey' extension instead.
         # Press keycode on the device.
         # http://developer.android.com/reference/android/view/KeyEvent.html
         # @param [Integer] key The key to press. The values which have +KEYCODE_+ prefix in http://developer.android.com/reference/android/view/KeyEvent.html
@@ -521,9 +563,11 @@ module Appium
         #   @driver.press_keycode 66, metastate: [1], flags: [32]
         #
         def press_keycode(key, metastate: [], flags: [])
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: pressKey' extension instead"
           @bridge.press_keycode(key, metastate: metastate, flags: flags)
         end
 
+        # @deprecated Use 'mobile: pressKey' extension instead.
         # Long press keycode on the device.
         # http://developer.android.com/reference/android/view/KeyEvent.html
         # @param [Integer] key The key to long press. The values which have +KEYCODE_+ prefix in http://developer.android.com/reference/android/view/KeyEvent.html
@@ -543,39 +587,11 @@ module Appium
         #   @driver.long_press_keycode 66, metastate: [1], flags: [32, 8192]
         #
         def long_press_keycode(key, metastate: [], flags: [])
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: pressKey' extension instead"
           @bridge.long_press_keycode(key, metastate: metastate, flags: flags)
         end
 
-        # Start the simulator and application configured with desired capabilities
-        #
-        # @example
-        #
-        #   @driver.launch_app
-        #
-        def launch_app
-          @bridge.launch_app
-        end
-
-        # Close an app on device
-        #
-        # @example
-        #
-        #   @driver.close_app
-        #
-        def close_app
-          @bridge.close_app
-        end
-
-        # Reset the device, relaunching the application.
-        #
-        # @example
-        #
-        #   @driver.reset
-        #
-        def reset
-          @bridge.reset
-        end
-
+        # @deprecated Use 'mobile: getAppStrings' extension instead.
         # Return the hash of all localization strings.
         # @return [Hash]
         #
@@ -584,9 +600,11 @@ module Appium
         #   @driver.app_strings #=> "TransitionsTitle"=>"Transitions", "WebTitle"=>"Web"
         #
         def app_strings(language = nil)
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: getAppStrings' extension instead"
           @bridge.app_strings(language)
         end
 
+        # @deprecated Use 'mobile: backgroundApp' extension instead.
         # Backgrounds the app for a set number of seconds.
         # This is a blocking application
         # @param [Integer] duration How many seconds to background the app for.
@@ -602,7 +620,9 @@ module Appium
           @bridge.background_app(duration)
         end
 
-        # Install the given app onto the device
+        # Install the given app onto the device.
+        # Each options can be snake-case or camel-case. Snake-cases will be converted to camel-case
+        # as options value.
         #
         # @param [String] path The absolute local path or remote http URL to an .ipa or .apk file,
         #                      or a .zip containing one of these.
@@ -616,26 +636,27 @@ module Appium
         # @param [Boolean] grant_permissions Only for Android. whether to automatically grant application permissions
         #                                    on Android 6+ after the installation completes. +false+ by default
         #
+        # Other parameters such as https://github.com/appium/appium-xcuitest-driver#mobile-installapp also can be set.
+        # Then, arguments in snake case will be camel case as its request parameters.
+        #
         # @example
         #
         #   @driver.install_app("/path/to/test.apk")
         #   @driver.install_app("/path/to/test.apk", replace: true, timeout: 20000, allow_test_packages: true,
         #                       use_sdcard: false, grant_permissions: false)
+        #   @driver.install_app("/path/to/test.ipa", timeoutMs: 20000)
         #
-        def install_app(path,
-                        replace: nil,
-                        timeout: nil,
-                        allow_test_packages: nil,
-                        use_sdcard: nil,
-                        grant_permissions: nil)
-          @bridge.install_app(path,
-                              replace: replace,
-                              timeout: timeout,
-                              allow_test_packages: allow_test_packages,
-                              use_sdcard: use_sdcard,
-                              grant_permissions: grant_permissions)
+        def install_app(path, **options)
+          # TODO: use mobile command in the background?
+          options = options.transform_keys { |key| key.to_s.gsub(/_./) { |v| v[1].upcase } } unless options.nil?
+          @bridge.install_app(path, options)
         end
 
+        # def capitalize(s)
+        #   chars =
+        #   chars[1:].map(&:capitalize).join
+        # end
+
         # @param [Strong] app_id BundleId for iOS or package name for Android
         # @param [Boolean] keep_data Only for Android. Whether to keep application data and caches after it is uninstalled.
         #                             +false+ by default
@@ -647,6 +668,7 @@ module Appium
         #   @driver.remove_app("io.appium.bundle", keep_data: false, timeout, 10000)
         #
         def remove_app(app_id, keep_data: nil, timeout: nil)
+          # TODO: use mobile command in the background?
           @bridge.remove_app(app_id, keep_data: keep_data, timeout: timeout)
         end
 
@@ -658,6 +680,7 @@ module Appium
         #   @driver.app_installed?("io.appium.bundle")
         #
         def app_installed?(app_id)
+          # TODO: use mobile command in the background?
           @bridge.app_installed?(app_id)
         end
 
@@ -669,6 +692,7 @@ module Appium
         #   @driver.activate_app("io.appium.bundle") #=> {}
         #
         def activate_app(app_id)
+          # TODO: use mobile command in the background?
           @bridge.activate_app(app_id)
         end
 
@@ -685,6 +709,7 @@ module Appium
         #   @driver.terminate_app("io.appium.bundle", timeout: 500)
         #
         def terminate_app(app_id, timeout: nil)
+          # TODO: use mobile command in the background?
           @bridge.terminate_app(app_id, timeout: timeout)
         end
 
@@ -708,6 +733,7 @@ module Appium
         #      @driver.query_app_state("io.appium.bundle") #=> :not_running
         #
         def app_state(app_id)
+          # TODO: use mobile command in the background?
           @bridge.app_state(app_id)
         end
         alias query_app_state app_state
@@ -747,6 +773,7 @@ module Appium
           @bridge.stop_and_save_recording_screen(file_path)
         end
 
+        # @deprecated Use 'mobile: shake' extension instead.
         # Cause the device to shake
         #
         # @example
@@ -754,9 +781,11 @@ module Appium
         #   @driver.shake
         #
         def shake
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: shake' extension instead"
           @bridge.shake
         end
 
+        # @deprecated Use 'mobile: getDeviceTime' extension instead.
         # Get the time on the device
         #
         # @param [String] format The set of format specifiers. Read https://momentjs.com/docs/ to get
@@ -770,18 +799,10 @@ module Appium
         #   @driver.device_time "YYYY-MM-DD" #=> "2018-06-12"
         #
         def device_time(format = nil)
+          ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: getDeviceTime' extension instead"
           @bridge.device_time(format)
         end
 
-        # touch actions
-        def touch_actions(actions)
-          @bridge.touch_actions(actions)
-        end
-
-        def multi_touch(actions)
-          @bridge.multi_touch(actions)
-        end
-
         #
         # Send multiple W3C action chains to server. Use +@driver.action+ for single action chain.
         #
@@ -790,7 +811,7 @@ module Appium
         #
         # @example: Zoom
         #
-        #    f1 = @driver.action.add_pointer_input(:touch, 'finger1')
+        #    f1 = ::Selenium::WebDriver::Interactions.pointer(:touch, name: 'finger1')
         #    f1.create_pointer_move(duration: 1, x: 200, y: 500,
         #                           origin: ::Selenium::WebDriver::Interactions::PointerMove::VIEWPORT)
         #    f1.create_pointer_down(:left)
@@ -798,7 +819,7 @@ module Appium
         #                           origin: ::Selenium::WebDriver::Interactions::PointerMove::VIEWPORT)
         #    f1.create_pointer_up(:left)
         #
-        #    f2 = @driver.action.add_pointer_input(:touch, 'finger2')
+        #    f2 = ::Selenium::WebDriver::Interactions.pointer(:touch, name: 'finger2')
         #    f2.create_pointer_move(duration: 1, x: 200, y: 500,
         #                           origin: ::Selenium::WebDriver::Interactions::PointerMove::VIEWPORT)
         #    f2.create_pointer_down(:left)
@@ -809,7 +830,11 @@ module Appium
         #    @driver.perform_actions [f1, f2] #=> 'nil' if the action succeed
         #
         def perform_actions(data)
-          raise ArgumentError, "'#{data}' must be Array" unless data.is_a? Array
+          raise ::Appium::Core::Error::ArgumentError, "'#{data}' must be Array" unless data.is_a? Array
+
+          # NOTE: 'add_input' in Selenium Ruby implementation has additional 'pause'.
+          # This implementation is to avoid the additional pause.
+          # https://github.com/SeleniumHQ/selenium/blob/64447d4b03f6986337d1ca8d8b6476653570bcc1/rb/lib/selenium/webdriver/common/action_builder.rb#L207
 
           @bridge.send_actions data.map(&:encode).compact
           data.each(&:clear_actions)
@@ -853,7 +878,7 @@ module Appium
         end
 
         # Get the device window's logs.
-        # @return [String]
+        # @return [Appium::Core::Logs]
         #
         # @example
         #
@@ -876,107 +901,6 @@ module Appium
           @bridge.get_timeouts
         end
 
-        # Retrieve the capabilities of the specified session.
-        # It's almost same as +@driver.capabilities+ but you can get more details.
-        #
-        # @return [Selenium::WebDriver::Remote::Capabilities]
-        #
-        # @example
-        #   @driver.session_capabilities
-        #
-        #   #=> uiautomator2
-        #   # <Selenium::WebDriver::Remote::W3C::Capabilities:0x007fa38dae1360
-        #   # @capabilities=
-        #   #     {:proxy=>nil,
-        #   #      :browser_name=>nil,
-        #   #      :browser_version=>nil,
-        #   #      :platform_name=>"android",
-        #   #      :page_load_strategy=>nil,
-        #   #      :remote_session_id=>nil,
-        #   #      :accessibility_checks=>nil,
-        #   #      :profile=>nil,
-        #   #      :rotatable=>nil,
-        #   #      :device=>nil,
-        #   #      "platform"=>"LINUX",
-        #   #      "webStorageEnabled"=>false,
-        #   #      "takesScreenshot"=>true,
-        #   #      "javascriptEnabled"=>true,
-        #   #      "databaseEnabled"=>false,
-        #   #      "networkConnectionEnabled"=>true,
-        #   #      "locationContextEnabled"=>false,
-        #   #      "warnings"=>{},
-        #   #      "desired"=>
-        #   #          {"platformName"=>"android",
-        #   #           "automationName"=>"uiautomator2",
-        #   #           "app"=>"/path/to/app/api.apk.zip",
-        #   #           "platformVersion"=>"8.1.0",
-        #   #           "deviceName"=>"Android Emulator",
-        #   #           "appPackage"=>"io.appium.android.apis",
-        #   #           "appActivity"=>"io.appium.android.apis.ApiDemos",
-        #   #           "someCapability"=>"some_capability",
-        #   #           "unicodeKeyboard"=>true,
-        #   #           "resetKeyboard"=>true},
-        #   #      "automationName"=>"uiautomator2",
-        #   #      "app"=>"/path/to/app/api.apk.zip",
-        #   #      "platformVersion"=>"8.1.0",
-        #   #      "deviceName"=>"emulator-5554",
-        #   #      "appPackage"=>"io.appium.android.apis",
-        #   #      "appActivity"=>"io.appium.android.apis.ApiDemos",
-        #   #      "someCapability"=>"some_capability",
-        #   #      "unicodeKeyboard"=>true,
-        #   #      "resetKeyboard"=>true,
-        #   #      "deviceUDID"=>"emulator-5554",
-        #   #      "deviceScreenSize"=>"1080x1920",
-        #   #      "deviceScreenDensity"=>420,
-        #   #      "deviceModel"=>"Android SDK built for x86",
-        #   #      "deviceManufacturer"=>"Google",
-        #   #      "pixelRatio"=>2.625,
-        #   #      "statBarHeight"=>63,
-        #   #      "viewportRect"=>{"left"=>0, "top"=>63, "width"=>1080, "height"=>1731}}>
-        #   #
-        #   #=> XCUITest
-        #   # <Selenium::WebDriver::Remote::W3C::Capabilities:0x007fb15dc01370
-        #   # @capabilities=
-        #   #     {:proxy=>nil,
-        #   #      :browser_name=>"UICatalog",
-        #   #      :browser_version=>nil,
-        #   #      :platform_name=>"ios",
-        #   #      :page_load_strategy=>nil,
-        #   #      :remote_session_id=>nil,
-        #   #      :accessibility_checks=>nil,
-        #   #      :profile=>nil,
-        #   #      :rotatable=>nil,
-        #   #      :device=>"iphone",
-        #   #      "udid"=>"DED4DBAD-8E5E-4AD6-BDC4-E75CF9AD84D8",
-        #   #      "automationName"=>"XCUITest",
-        #   #      "app"=>"/path/to/app/UICatalog.app",
-        #   #      "platformVersion"=>"11.4",
-        #   #      "deviceName"=>"iPhone Simulator",
-        #   #      "useNewWDA"=>true,
-        #   #      "useJSONSource"=>true,
-        #   #      "someCapability"=>"some_capability",
-        #   #      "sdkVersion"=>"11.4",
-        #   #      "CFBundleIdentifier"=>"com.example.apple-samplecode.UICatalog",
-        #   #      "pixelRatio"=>2,
-        #   #      "statBarHeight"=>23.4375,
-        #   #      "viewportRect"=>{"left"=>0, "top"=>47, "width"=>750, "height"=>1287}}>
-        #
-        def session_capabilities
-          @bridge.session_capabilities
-        end
-
-        # Returns available sessions on the Appium server
-        #
-        # @return [[Hash]]
-        #
-        # @example
-        #
-        #   @driver.sessions #=> [{'id' => 'c363add8-a7ca-4455-b9e3-9ac4d69e95b3', 'capabilities' => { capabilities as Hash }}]
-        #
-        def sessions
-          @bridge.sessions
-        end
-
         # Image Comparison
         def match_images_features(first_image:,
                                   second_image:,
@@ -992,11 +916,14 @@ module Appium
                                         visualize: visualize)
         end
 
-        def find_image_occurrence(full_image:, partial_image:, visualize: false, threshold: nil)
+        def find_image_occurrence(full_image:, partial_image:, visualize: false, threshold: nil,
+                                  multiple: nil, match_neighbour_threshold: nil)
           @bridge.find_image_occurrence(full_image: full_image,
                                         partial_image: partial_image,
                                         visualize: visualize,
-                                        threshold: threshold)
+                                        threshold: threshold,
+                                        multiple: multiple,
+                                        match_neighbour_threshold: match_neighbour_threshold)
         end
 
         def get_images_similarity(first_image:, second_image:, visualize: false)
@@ -1009,14 +936,14 @@ module Appium
 
         # @since Appium 1.8.2
         # Return an element if current view has a partial image. The logic depends on template matching by OpenCV.
-        # {https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/image-comparison.md image-comparison}
+        # {https://github.com/appium/appium/blob/1.x/docs/en/writing-running-appium/image-comparison.md image-comparison}
         #
         # You can handle settings for the comparision following below.
         # {https://github.com/appium/appium-base-driver/blob/master/lib/basedriver/device-settings.js#L6 device-settings}
         #
         # @param [String] img_path A path to a partial image you'd like to find
         #
-        # @return [::Selenium::WebDriver::Element]
+        # @return [::Appium::Core::Element]
         #
         # @example
         #
@@ -1031,14 +958,14 @@ module Appium
 
         # @since Appium 1.8.2
         # Return elements if current view has a partial image. The logic depends on template matching by OpenCV.
-        # {https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/image-comparison.md image-comparison}
+        # {https://github.com/appium/appium/blob/1.x/docs/en/writing-running-appium/image-comparison.md image-comparison}
         #
         # You can handle settings for the comparision following below.
         # {https://github.com/appium/appium-base-driver/blob/master/lib/basedriver/device-settings.js#L6 device-settings}
         #
         # @param [String] img_path A path to a partial image you'd like to find
         #
-        # @return [::Selenium::WebDriver::Element]
+        # @return [Array<::Appium::Core::Element>]
         #
         # @example
         #
@@ -1086,14 +1013,14 @@ module Appium
           @bridge.execute_driver(script: script, type: type, timeout_ms: timeout_ms)
         end
 
-        # Convert vanilla element response to ::Selenium::WebDriver::Element
+        # Convert vanilla element response to ::Appium::Core::Element
         #
         # @param [Hash] id The id which can get as a response from server
-        # @return [::Selenium::WebDriver::Element]
+        # @return [::Appium::Core::Element]
         #
         # @example
         #     response = {"element-6066-11e4-a52e-4f735466cecf"=>"xxxx", "ELEMENT"=>"xxxx"}
-        #     ele = @driver.convert_to_element(response) #=> ::Selenium::WebDriver::Element
+        #     ele = @driver.convert_to_element(response) #=> ::Appium::Core::Element
         #     ele.rect #=> Can get the rect of the element
         #
         def convert_to_element(id)