appium_lib_core 4.1.0 → 7.4.0

data/lib/appium_lib_core/{patch.rb → element.rb}

@@ -12,14 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# rubocop:disable Style/ClassAndModuleChildren
 module Appium
   module Core
     # Implement useful features for element.
     # Patch for Selenium Webdriver.
-    class Selenium::WebDriver::Element
-      # To extend Appium related SearchContext into ::Selenium::WebDriver::Element
+    class Element < ::Selenium::WebDriver::Element
       include ::Appium::Core::Base::SearchContext
+      include ::Appium::Core::Base::TakesScreenshot
+
+      # Retuns the element id.
+      #
+      # @return [String]
+      # @example
+      #   e = @driver.find_element :accessibility_id, 'something'
+      #   e.id
+      #
+      attr_reader :id
 
       # Returns the value of attributes like below. Read each platform to know more details.
       #
@@ -56,24 +64,33 @@ module Appium
       # Alias for type
       alias type send_keys
 
+      # @deprecated Use element send_keys instead.
       # Set the value to element directly
       #
       # @example
       #
-      #   @driver.immediate_value 'hello'
+      #   element.immediate_value 'hello'
       #
       def immediate_value(*value)
-        @bridge.set_immediate_value(self, *value)
+        ::Appium::Logger.warn(
+          '[DEPRECATION] element.immediate_value is deprecated. Please use element.send_keys instead.'
+        )
+        @bridge.set_immediate_value @id, *value
       end
 
+      # @deprecated Use element send_keys or 'mobile: replaceElementValue' for UIAutomator2 instead.
       # Replace the value to element directly
       #
       # @example
       #
-      #   @driver.replace_value 'hello'
+      #   element.replace_value 'hello'
       #
       def replace_value(*value)
-        @bridge.replace_value(self, *value)
+        ::Appium::Logger.warn(
+          '[DEPRECATION] element.replace_value is deprecated. Please use element.send_keys instead, ' \
+          'or "mobile: replaceElementValue" for UIAutomator2.'
+        )
+        @bridge.replace_value @id, *value
       end
 
       # For use with location_rel.
@@ -99,7 +116,56 @@ module Appium
         w = driver.window_size
         ::Selenium::WebDriver::Point.new "#{center_x} / #{w.width.to_f}", "#{center_y} / #{w.height.to_f}"
       end
-    end
+
+      # Return an element screenshot as base64
+      #
+      # @return String Base 64 encoded string
+      #
+      # @example
+      #
+      #     element.screenshot #=> "iVBORw0KGgoAAAANSUhEUgAABDgAAAB+CAIAAABOPDa6AAAAAX"
+      #
+      def screenshot
+        bridge.element_screenshot @id
+      end
+
+      # Return an element screenshot in the given format
+      #
+      # @param [:base64, :png] format
+      # @return String screenshot
+      #
+      # @example
+      #
+      #     element.screenshot_as :base64 #=> "iVBORw0KGgoAAAANSUhEUgAABDgAAAB+CAIAAABOPDa6AAAAAX"
+      #
+      def screenshot_as(format)
+        case format
+        when :base64
+          bridge.element_screenshot @id
+        when :png
+          bridge.element_screenshot(@id).unpack('m')[0]
+        else
+          raise Core::Error::UnsupportedOperationError, "unsupported format: #{format.inspect}"
+        end
+      end
+
+      # Save an element screenshot to the given path
+      #
+      # @param [String] png_path A path to save the screenshot
+      # @return [File] Path to the element screenshot.
+      #
+      # @example
+      #
+      #   element.save_screenshot("fine_name.png")
+      #
+      def save_screenshot(png_path)
+        extension = File.extname(png_path).downcase
+        if extension != '.png'
+          ::Appium::Logger.warn 'name used for saved screenshot does not match file type. ' \
+                                'It should end with .png extension'
+        end
+        File.open(png_path, 'wb') { |f| f << screenshot_as(:png) }
+      end
+    end # class Element
   end # module Core
 end # module Appium
-# rubocop:enable Style/ClassAndModuleChildren

data/lib/appium_lib_core/ios/xcuitest/device.rb

@@ -25,6 +25,7 @@ module Appium
 
           # rubocop:disable Layout/LineLength
 
+          # @deprecated Use 'mobile: hideKeyboard' extension instead.
           # @!method hide_keyboard(close_key = nil, strategy = nil)
           # Hide the onscreen keyboard
           # @param [String] close_key The name of the key which closes the keyboard.
@@ -38,6 +39,7 @@ module Appium
           #  @driver.hide_keyboard('Finished') # Close a keyboard with the 'Finished' button
           #
 
+          # @deprecated Use 'mobile: backgroundApp' extension instead.
           # @!method background_app(duration = 0)
           # Backgrounds the app for a set number of seconds.
           # This is a blocking application.

data/lib/appium_lib_core/{common/base/command.rb → mac2/bridge.rb}

@@ -14,11 +14,12 @@
 
 module Appium
   module Core
-    class Base
-      module Commands
-        OSS = ::Selenium::WebDriver::Remote::OSS::Bridge::COMMANDS.freeze
-        W3C = ::Selenium::WebDriver::Remote::W3C::Bridge::COMMANDS.freeze
-      end # module Commands
-    end # module Base
-  end # module Core
-end # module Appium
+    module Mac2
+      module Bridge
+        def self.for(target)
+          target.extend Appium::Core::Mac2::Device
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib_core/mac2/device/screen.rb

@@ -0,0 +1,48 @@
+# 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 Core
+    module Mac2
+      module Device
+        module Screen
+          def self.add_methods
+            ::Appium::Core::Device.add_endpoint_method(:start_recording_screen) do
+              def start_recording_screen(remote_path: nil, user: nil, pass: nil, method: 'PUT',
+                                         file_field_name: nil, form_fields: nil, headers: nil, force_restart: nil,
+                                         fps: nil, preset: nil, video_filter: nil, time_limit: nil,
+                                         enable_capture_clicks: nil, enable_cursor_capture: nil, device_id: nil)
+                option = ::Appium::Core::Base::Device::ScreenRecord.new(
+                  remote_path: remote_path, user: user, pass: pass, method: method,
+                  file_field_name: file_field_name, form_fields: form_fields, headers: headers,
+                  force_restart: force_restart
+                ).upload_option
+
+                option[:fps] = fps unless fps.nil?
+                option[:preset] = preset unless preset.nil?
+                option[:videoFilter] = video_filter unless video_filter.nil?
+                option[:captureClicks] = enable_capture_clicks unless enable_capture_clicks.nil?
+                option[:captureCursor] = enable_cursor_capture unless enable_cursor_capture.nil?
+                option[:deviceId] = device_id unless device_id.nil?
+                option[:timeLimit] = time_limit unless time_limit.nil?
+
+                execute(:start_recording_screen, {}, { options: option })
+              end
+            end
+          end
+        end # module Screen
+      end # module Device
+    end # module Mac2
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/mac2/device.rb

@@ -0,0 +1,92 @@
+# 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.
+
+require_relative 'device/screen'
+
+module Appium
+  module Core
+    module Mac2
+      module Device
+        extend Forwardable
+
+        # rubocop:disable Layout/LineLength
+
+        # @since Appium 1.20.0
+        # @!method start_recording_screen(remote_path: nil, user: nil, pass: nil, method: 'PUT', file_field_name: nil, form_fields: nil, headers: nil, force_restart: nil, fps: nil, preset: nil, video_filter: nil, enable_capture_clicks: nil, enable_cursor_capture: nil, device_id: nil)
+        #
+        # Record the display of devices running iOS Simulator since Xcode 9 or real devices since iOS 11
+        # (ffmpeg utility is required: 'brew install ffmpeg').
+        # We would recommend to play the video by VLC or Mplayer if you can not play the video with other video players.
+        #
+        # @param [String] remote_path The path to the remote location, where the resulting video should be uploaded.
+        #                             The following protocols are supported: http/https, ftp.
+        #                             Null or empty string value (the default setting) means the content of resulting
+        #                             file should be encoded as Base64 and passed as the endpount response value.
+        #                             An exception will be thrown if the generated media file is too big to
+        #                             fit into the available process memory.
+        #                             This option only has an effect if there is screen recording process in progreess
+        #                             and +forceRestart+ parameter is not set to +true+.
+        # @param [String] user The name of the user for the remote authentication.
+        # @param [String] pass The password for the remote authentication.
+        # @param [String] method The http multipart upload method name. The 'PUT' one is used by default.
+        # @param [String] file_field_name The name of the form field containing the binary payload in multipart/form-data
+        #                             requests since Appium 1.18.0. Defaults to 'file'.
+        # @param [Array<Hash, Array<String>>] form_fields The form fields mapping in multipart/form-data requests since Appium 1.18.0.
+        #                             If any entry has the same key in this mapping, then it is going to be ignored.
+        # @param [Hash] headers The additional headers in multipart/form-data requests since Appium 1.18.0.
+        # @param [Boolean] force_restart Whether to try to catch and upload/return the currently running screen recording
+        #                                (+false+, the default setting on server) or ignore the result of it
+        #                                and start a new recording immediately (+true+).
+        # @param [integer] fps The count of frames per second in the resulting video.
+        #                      Increasing fps value also increases the size of the resulting video file and the CPU usage.
+        #                      The default value is 15.
+        # @param [String] preset A preset is a collection of options that will provide a certain encoding speed to compression ratio.
+        #                        A slower preset will provide better compression (compression is quality per filesize).
+        #                        This means that, for example, if you target a certain file size or constant bit rate, you will
+        #                        achieve better quality with a slower preset. Read https://trac.ffmpeg.org/wiki/Encode/H.264
+        #                        for more details.
+        # @param [Boolean] enable_cursor_capture Whether to capture the click gestures while recording the screen. Disabled by default.
+        # @param [Boolean] enable_capture_clicks Recording time. 180 seconds is by default.
+        # @param [String] video_filter The video filter spec to apply for ffmpeg.
+        #                              See https://trac.ffmpeg.org/wiki/FilteringGuide for more details on the possible values.
+        #                              Example: Set it to +scale=ifnot(gte(iw\,1024)\,iw\,1024):-2+ in order to limit the video width
+        #                              to 1024px. The height will be adjusted automatically to match the actual screen aspect ratio.
+        # @param [integer] device_id Screen device index to use for the recording.
+        #                            The list of available devices could be retrieved using
+        #                            +ffmpeg -f avfoundation -list_devices true -i ""+ command.
+        #                            This option is mandatory and must be always provided.
+        # @param [String] time_limit The maximum recording time. The default value is 600 seconds (10 minutes).
+        #                            The minimum time resolution unit is one second.
+        #
+        # @example
+        #
+        #    @driver.start_recording_screen
+        #    @driver.start_recording_screen fps: 30, enable_cursor_capture: true
+        #
+
+        # rubocop:enable Layout/LineLength
+
+        ####
+        ## class << self
+        ####
+
+        class << self
+          def extended(_mod)
+            Screen.add_methods
+          end
+        end # class << self
+      end # module Device
+    end # module Mac2
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/{ios.rb → mac2.rb}

@@ -13,8 +13,5 @@
 # limitations under the License.
 
 # loaded in common/driver.rb
-require_relative 'ios/device'
-
-require_relative 'ios/uiautomation/patch'
-require_relative 'ios/uiautomation/device'
-require_relative 'ios/uiautomation/bridge'
+require_relative 'mac2/device'
+require_relative 'mac2/bridge'

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 = '4.1.0' unless defined? ::Appium::Core::VERSION
-    DATE    = '2020-12-25' unless defined? ::Appium::Core::DATE
+    VERSION = '7.4.0' unless defined? ::Appium::Core::VERSION
+    DATE    = '2024-01-23' unless defined? ::Appium::Core::DATE
   end
 end

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

@@ -0,0 +1,38 @@
+# 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 Core
+    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
+
+            ::Appium::Core::Device.add_endpoint_method(:close_app) do
+              def close_app
+                execute :close_app
+              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

@@ -17,23 +17,30 @@ require 'selenium-webdriver'
 require_relative 'appium_lib_core/version'
 require_relative 'appium_lib_core/common'
 require_relative 'appium_lib_core/driver'
-
 require_relative 'appium_lib_core/device'
-
-# Call patch after requiring other files
-require_relative 'appium_lib_core/patch'
+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)
-    raise ArgumentError, 'symbolize_keys requires a hash' unless hash.is_a? 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)
@@ -41,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