appium_lib_core 5.0.0 → 6.3.0

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

@@ -29,7 +29,6 @@ module Appium
       class Driver < ::Selenium::WebDriver::Driver
         include ::Selenium::WebDriver::DriverExtensions::UploadsFiles
         include ::Selenium::WebDriver::DriverExtensions::HasSessionId
-        include ::Selenium::WebDriver::DriverExtensions::HasRemoteStatus
         include ::Selenium::WebDriver::DriverExtensions::HasWebStorage
 
         include ::Appium::Core::Base::Rotatable
@@ -41,36 +40,54 @@ module Appium
 
         include ::Appium::Core::Waitable
 
-        private
-
         # 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(bridge: nil, listener: nil, **opts)
+          original_opts = opts.dup
+
           # For ::Appium::Core::Waitable
           @wait_timeout = opts.delete(:wait_timeout)
           @wait_interval = opts.delete(:wait_interval)
 
-          # For logging.
-          # TODO: Remove when appium core no longer uses this in this bridge.
-          @automation_name = opts.delete(:automation_name)
+          # Selenium WebDriver attributes
+          @devtools = nil
+          @bidi = nil
 
-          super
+          # 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
 
+        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)
 
-          bridge.create_session(capabilities)
+          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
 
@@ -181,6 +198,31 @@ module Appium
 
         ### Methods for Appium
 
+        # Perform 'key' actions for W3C module.
+        # Generate +key+ pointer action here and users can use this via +driver.key_action+
+        # - https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/W3CActionBuilder.html
+        # - https://seleniumhq.github.io/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
+
         # Lock the device
         # @return [String]
         #
@@ -542,12 +584,6 @@ module Appium
         #   @driver.launch_app
         #
         def launch_app
-          # TODO: Define only in Windows module when ruby_lib_core removes this method
-          if @automation_name != :windows
-            ::Appium::Logger.warn(
-              '[DEPRECATION] launch_app is deprecated. Please use activate_app instead.'
-            )
-          end
           @bridge.launch_app
         end
 
@@ -559,12 +595,6 @@ module Appium
         #   @driver.close_app
         #
         def close_app
-          # TODO: Define only in Windows module when ruby_lib_core removes this method
-          if @automation_name != :windows
-            ::Appium::Logger.warn(
-              '[DEPRECATION] close_app is deprecated. Please use terminate_app instead.'
-            )
-          end
           @bridge.close_app
         end
 
@@ -609,7 +639,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.
@@ -623,26 +655,26 @@ 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)
+          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
@@ -924,8 +956,6 @@ module Appium
         #   #           "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",
@@ -933,8 +963,6 @@ module Appium
         #   #      "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,
@@ -1021,7 +1049,7 @@ 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}
@@ -1043,14 +1071,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 [Array<Selenium::WebDriver::Element>]
+        # @return [Array<::Appium::Core::Element>]
         #
         # @example
         #

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

@@ -21,11 +21,11 @@ module Appium
       module HasLocation
         # Get the location of the device.
         #
-        # @return [::Selenium::WebDriver::Location]
+        # @return [::Appium::Location]
         #
         # @example
         #
-        #   driver.location #=> ::Selenium::WebDriver::Location.new(10, 10, 10)
+        #   driver.location #=> ::Appium::Location.new(10, 10, 10)
         #
         def location
           @bridge.location
@@ -33,15 +33,15 @@ module Appium
 
         # Set the location of the device.
         #
-        # @param [::Selenium::WebDriver::Location] location Set the location.
+        # @param [::Appium::Location] location Set the location.
         #
         # @example
         #
-        #   driver.location = ::Selenium::WebDriver::Location.new(10, 10, 10)
+        #   driver.location = ::Appium::Location.new(10, 10, 10)
         #
         def location=(location)
-          unless location.is_a?(::Selenium::WebDriver::Location)
-            raise TypeError, "expected #{::Selenium::WebDriver::Location}, got #{location.inspect}:#{location.class}"
+          unless location.is_a?(::Appium::Location)
+            raise TypeError, "expected #{::Appium::Location}, got #{location.inspect}:#{location.class}"
           end
 
           @bridge.set_location location.latitude, location.longitude, location.altitude
@@ -56,17 +56,17 @@ module Appium
         #                               in meters/second @since Appium 1.21.0 and in knots for emulators @since Appium 1.22.0.
         # @param [String, Number] satellites Sets the count of geo satellites being tracked in range 1..12 @since Appium 1.22.0.
         #                                    This number is respected on Emulators.
-        # @param [::Selenium::WebDriver::Location]
+        # @param [::Appium::Location]
         #
         # @example
         #
-        #   driver.location = ::Selenium::WebDriver::Location.new(10, 10, 10)
+        #   driver.location = ::Appium::Location.new(10, 10, 10)
         #
         def set_location(latitude, longitude, altitude, speed: nil, satellites: nil)
           if speed.nil? && satellites.nil?
-            self.location = ::Selenium::WebDriver::Location.new(Float(latitude), Float(longitude), Float(altitude))
+            self.location = ::Appium::Location.new(Float(latitude), Float(longitude), Float(altitude))
           else
-            loc = ::Selenium::WebDriver::Location.new(Float(latitude), Float(longitude), Float(altitude))
+            loc = ::Appium::Location.new(Float(latitude), Float(longitude), Float(altitude))
 
             speed = Float(speed) unless speed.nil?
             satellites = Integer(satellites) unless satellites.nil?

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

@@ -37,7 +37,7 @@ module Appium
           attr_reader :additional_headers
 
           # override
-          def initialize(open_timeout: nil, read_timeout: nil) # rubocop:disable Lint/MissingSuper
+          def initialize(open_timeout: nil, read_timeout: nil)
             @open_timeout = open_timeout
             @read_timeout = read_timeout
             @additional_headers = {}

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

@@ -20,12 +20,18 @@ module Appium
       #
 
       module Rotatable
-        ORIENTATIONS = %i[landscape portrait].freeze
+        ORIENTATIONS = %i[
+          landscape
+          portrait
+          uia_device_orientation_landscaperight
+          uia_device_orientation_portrait_upsidedown
+        ].freeze
 
         #
         # Change the screen orientation
         #
-        # @param [:landscape, :portrait] orientation
+        # @param [:landscape, :portrait,
+        #         :uia_device_orientation_landscaperight, :uia_device_orientation_portrait_upsidedown] orientation
         #
         #
         def rotation=(orientation)
@@ -36,11 +42,13 @@ module Appium
           bridge.screen_orientation = orientation.to_s.upcase
         end
         alias rotate rotation=
+        alias orientation= rotation=
 
         #
         # Get the current screen orientation
         #
-        # @return [:landscape, :portrait] orientation
+        # @return [:landscape, :portrait,
+        #          :uia_device_orientation_landscaperight, :uia_device_orientation_portrait_upsidedown] orientation
         #
         # @api public
         #

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

@@ -28,7 +28,6 @@ module Appium
           data_matcher:         '-android datamatcher', # Available in Espresso
           view_matcher:         '-android viewmatcher', # Available in Espresso
           # iOS
-          uiautomation:         '-ios uiautomation',
           predicate:            '-ios predicate string',
           class_chain:          '-ios class chain',
           # Windows with windows prefix
@@ -48,7 +47,7 @@ module Appium
         #
         # == Find with image
         # 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 {https://github.com/appium/appium-base-driver/blob/master/lib/basedriver/device-settings.js#L6 here}
         #

data/lib/appium_lib_core/common/command.rb

@@ -70,11 +70,15 @@ module Appium
         find_elements: [:post, 'session/:session_id/elements'],
         find_child_element: [:post, 'session/:session_id/element/:id/element'],
         find_child_elements: [:post, 'session/:session_id/element/:id/elements'],
+        find_shadow_child_element: [:post, 'session/:session_id/shadow/:id/element'],
+        find_shadow_child_elements: [:post, 'session/:session_id/shadow/:id/elements'],
         get_active_element: [:get, 'session/:session_id/element/active'],
         is_element_selected: [:get, 'session/:session_id/element/:id/selected'],
         get_element_attribute: [:get, 'session/:session_id/element/:id/attribute/:name'],
         get_element_property: [:get, 'session/:session_id/element/:id/property/:name'],
         get_element_css_value: [:get, 'session/:session_id/element/:id/css/:property_name'],
+        get_element_aria_role: [:get, 'session/:session_id/element/:id/computedrole'],
+        get_element_aria_label: [:get, 'session/:session_id/element/:id/computedlabel'],
         get_element_text: [:get, 'session/:session_id/element/:id/text'],
         get_element_tag_name: [:get, 'session/:session_id/element/:id/name'],
         get_element_rect: [:get, 'session/:session_id/element/:id/rect'],
@@ -171,8 +175,6 @@ module Appium
         ime_deactivate: [:post, 'session/:session_id/ime/deactivate'],
         ime_activate_engine: [:post, 'session/:session_id/ime/activate'],
 
-        send_keys_to_active_element: [:post, 'session/:session_id/keys'],
-
         ### Logs
         get_available_log_types: [:get, 'session/:session_id/log/types'],
         get_log: [:post, 'session/:session_id/log'],

data/lib/appium_lib_core/common/device/app_management.rb

@@ -18,10 +18,16 @@ module Appium
       module Device
         module AppManagement
           def launch_app
+            ::Appium::Logger.warn(
+              '[DEPRECATION] launch_app is deprecated. Please use activate_app instead.'
+            )
             execute :launch_app
           end
 
           def close_app
+            ::Appium::Logger.warn(
+              '[DEPRECATION] close_app is deprecated. Please use terminate_app instead.'
+            )
             execute :close_app
           end
 
@@ -39,21 +45,9 @@ module Appium
             raise NotImplementedError
           end
 
-          def install_app(path,
-                          replace: nil,
-                          timeout: nil,
-                          allow_test_packages: nil,
-                          use_sdcard: nil,
-                          grant_permissions: nil)
+          def install_app(path, options = {})
             args = { appPath: path }
-
-            args[:options] = {} if options?(replace, timeout, allow_test_packages, use_sdcard, grant_permissions)
-
-            args[:options][:replace] = replace unless replace.nil?
-            args[:options][:timeout] = timeout unless timeout.nil?
-            args[:options][:allowTestPackages] = allow_test_packages unless allow_test_packages.nil?
-            args[:options][:useSdcard] = use_sdcard unless use_sdcard.nil?
-            args[:options][:grantPermissions] = grant_permissions unless grant_permissions.nil?
+            args[:options] = options unless options.empty?
 
             execute :install_app, {}, args
           end

data/lib/appium_lib_core/common/device/value.rb

@@ -41,9 +41,7 @@ module Appium
             # Keep .split(//) for backward compatibility for now
             text = keys.join
 
-            # FIXME: further work for W3C. Over appium 1.15.0 or later
-            # { value: text.split(//), text: text }
-            { value: text.chars }
+            { text: text }
           end
         end # module Value
       end # module Device

data/lib/appium_lib_core/common/error.rb

@@ -17,10 +17,6 @@ module Appium
     module Error
       class CoreError < StandardError; end
 
-      # Capability related errors
-      class NoCapabilityError < CoreError; end
-      class CapabilityStructureError < CoreError; end
-
       # Appium related errors
       class NotSupportedAppiumServer < CoreError; end
       class NoSuchElementError < CoreError; end