appium_lib_core 4.1.0 → 5.5.0

data/lib/appium_lib_core/driver.rb

@@ -27,6 +27,8 @@ module Appium
       autoload :Xcuitest, 'appium_lib_core/ios_xcuitest'
     end
 
+    autoload :Mac2, 'appium_lib_core/mac2'
+
     autoload :Windows, 'appium_lib_core/windows'
 
     # This options affects only client side as <code>:appium_lib</code> key.<br>
@@ -38,18 +40,18 @@ module Appium
 
       def initialize(appium_lib_opts)
         @custom_url = appium_lib_opts.fetch :server_url, nil
-        @default_wait = appium_lib_opts.fetch :wait, Driver::DEFAULT_IMPLICIT_WAIT
+        @default_wait = appium_lib_opts.fetch :wait, nil
         @enable_idempotency_header = appium_lib_opts.fetch :enable_idempotency_header, true
 
         # bump current session id into a particular file
         @export_session = appium_lib_opts.fetch :export_session, false
         @export_session_path = appium_lib_opts.fetch :export_session_path, default_tmp_appium_lib_session
 
-        @direct_connect = appium_lib_opts.fetch :direct_connect, false
+        @direct_connect = appium_lib_opts.fetch :direct_connect, true
 
         @port = appium_lib_opts.fetch :port, Driver::DEFAULT_APPIUM_PORT
 
-        # timeout and interval used in ::Appium::Comm.wait/wait_true
+        # timeout and interval used in ::Appium::Commn.wait/wait_true
         @wait_timeout  = appium_lib_opts.fetch :wait_timeout, ::Appium::Core::Wait::DEFAULT_TIMEOUT
         @wait_interval = appium_lib_opts.fetch :wait_interval, ::Appium::Core::Wait::DEFAULT_INTERVAL
 
@@ -74,6 +76,13 @@ module Appium
         path: 'directConnectPath'
       }.freeze
 
+      W3C_KEYS = {
+        protocol: 'appium:directConnectProtocol',
+        host: 'appium:directConnectHost',
+        port: 'appium:directConnectPort',
+        path: 'appium:directConnectPath'
+      }.freeze
+
       # @return [string] Returns a protocol such as http/https
       attr_reader :protocol
 
@@ -87,10 +96,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
 
@@ -133,11 +142,9 @@ module Appium
       attr_reader :export_session_path
 
       # Default wait time for elements to appear in Appium server side.
-      # Defaults to {::Appium::Core::Driver::DEFAULT_IMPLICIT_WAIT}.<br>
       # Provide <code>{ appium_lib: { wait: 30 } }</code> to {::Appium::Core.for}
       # @return [Integer]
       attr_reader :default_wait
-      DEFAULT_IMPLICIT_WAIT = 0
 
       # Appium's server port. 4723 is by default. Defaults to {::Appium::Core::Driver::DEFAULT_APPIUM_PORT}.<br>
       # Provide <code>{ appium_lib: { port: 8080 } }</code> to {::Appium::Core.for}.
@@ -175,7 +182,8 @@ module Appium
       # - <code>directConnectPort</code>
       # - <code>directConnectPath</code>
       #
-      # Ignore them if this parameter is <code>false</code>. Defaults to false.
+      # ignore them if this parameter is <code>false</code>. Defaults to true.
+      # These keys can have <code>appium:</code> prefix.
       #
       # @return [Bool]
       attr_reader :direct_connect
@@ -185,8 +193,6 @@ module Appium
       # @option opts [Hash] :caps Appium capabilities.
       # @option opts [Hash] :capabilities The same as :caps.
       #                                   This param is for compatibility with Selenium WebDriver format
-      # @option opts [Hash] :desired_capabilities The same as :caps.
-      #                                           This param is for compatibility with Selenium WebDriver format
       # @option opts [Appium::Core::Options] :appium_lib Capabilities affect only ruby client
       # @option opts [String] :url The same as :custom_url in :appium_lib.
       #                            This param is for compatibility with Selenium WebDriver format
@@ -197,10 +203,8 @@ module Appium
       #
       #     # format 1
       #     @core = Appium::Core.for caps: {...}, appium_lib: {...}
-      #     # format 2. 'capabilities:' or 'desired_capabilities:' is also available instead of 'caps:'.
+      #     # format 2. 'capabilities:' is also available instead of 'caps:'.
       #     @core = Appium::Core.for url: "http://127.0.0.1:8080/wd/hub", capabilities: {...}, appium_lib: {...}
-      #     # format 3. 'appium_lib: {...}' can be blank
-      #     @core = Appium::Core.for url: "http://127.0.0.1:8080/wd/hub", desired_capabilities: {...}
       #
       #
       #     require 'rubygems'
@@ -228,7 +232,7 @@ module Appium
       #     @core.start_driver # Connect to 'http://127.0.0.1:8080/wd/hub' because of 'port: 8080'
       #
       #     # Start iOS driver with .zip file over HTTP
-      #     #  'desired_capabilities:' or 'capabilities:' is also available instead of 'caps:'. Either is fine.
+      #     # 'capabilities:' is also available instead of 'caps:'. Either is fine.
       #     opts = {
       #              capabilities: {
       #                platformName: :ios,
@@ -252,7 +256,7 @@ module Appium
       #     # Start iOS driver as another format. 'url' is available like below
       #     opts = {
       #              url: "http://custom-host:8080/wd/hub.com",
-      #              desired_capabilities: {
+      #              capabilities: {
       #                platformName: :ios,
       #                platformVersion: '11.0',
       #                deviceName: 'iPhone Simulator',
@@ -289,9 +293,6 @@ module Appium
         @delegate_target = self # for testing purpose
         @automation_name = nil # initialise before 'set_automation_name'
 
-        opts = Appium.symbolize_keys opts
-        validate_keys(opts)
-
         @custom_url = opts.delete :url
         @caps = get_caps(opts)
 
@@ -324,7 +325,7 @@ module Appium
       #
       #     # Start iOS driver
       #     opts = {
-      #              caps: {
+      #              capabilities: {
       #                platformName: :ios,
       #                platformVersion: '11.0',
       #                deviceName: 'iPhone Simulator',
@@ -365,11 +366,13 @@ module Appium
         end
 
         begin
-          # included https://github.com/SeleniumHQ/selenium/blob/43f8b3f66e7e01124eff6a5805269ee441f65707/rb/lib/selenium/webdriver/remote/driver.rb#L29
-          @driver = ::Appium::Core::Base::Driver.new(http_client: @http_client,
-                                                     desired_capabilities: @caps,
+          @driver = ::Appium::Core::Base::Driver.new(listener: @listener,
+                                                     http_client: @http_client,
+                                                     capabilities: @caps, # ::Appium::Core::Base::Capabilities
                                                      url: @custom_url,
-                                                     listener: @listener)
+                                                     wait_timeout: @wait_timeout,
+                                                     wait_interval: @wait_interval,
+                                                     automation_name: @automation_name)
 
           if @direct_connect
             d_c = DirectConnections.new(@driver.capabilities)
@@ -410,6 +413,8 @@ module Appium
 
       # Ignore setting default wait if the target driver has no implementation
       def set_implicit_wait_by_default(wait)
+        return if @default_wait.nil?
+
         @driver.manage.timeouts.implicit_wait = wait
       rescue ::Selenium::WebDriver::Error::UnknownError => e
         unless e.message.include?('The operation requested is not yet implemented')
@@ -435,7 +440,8 @@ module Appium
         nil
       end
 
-      # Returns the server's version info
+      # Returns the server's version info. This method calls +driver.remote_status+ internally
+      #
       # @return [Hash]
       #
       # @example
@@ -449,18 +455,20 @@ module Appium
       #         }
       #     }
       #
-      # Returns blank hash for Selenium Grid since 'remote_status' gets 500 error
+      # Returns blank hash in a case +driver.remote_status+ got an error
+      # such as Selenium Grid. It returns 500 error against 'remote_status'.
       #
       # @example
       #
       #   @core.appium_server_version #=> {}
       #
       def appium_server_version
-        @driver.remote_status
-      rescue Selenium::WebDriver::Error::ServerError => e
-        raise ::Appium::Core::Error::ServerError unless e.message.include?('status code 500')
+        return {} if @driver.nil?
 
-        # driver.remote_status returns 500 error for using selenium grid
+        @driver.remote_status
+      rescue StandardError
+        # Ignore error case in a case the target appium server
+        # does not support `/status` API.
         {}
       end
 
@@ -476,21 +484,6 @@ module Appium
         p_version.split('.').map(&:to_i)
       end
 
-      # Takes a png screenshot and saves to the target path.
-      #
-      # @param png_save_path [String] the full path to save the png
-      # @return [File]
-      #
-      # @example
-      #
-      #   @core.screenshot '/tmp/hi.png' #=> nil
-      #   # same as '@driver.save_screenshot png_save_path'
-      #
-      def screenshot(png_save_path)
-        ::Appium::Logger.warn '[DEPRECATION] screenshot will be removed. Please use driver.save_screenshot instead.'
-        @driver.save_screenshot png_save_path
-      end
-
       private
 
       # @private
@@ -526,7 +519,7 @@ module Appium
           when :gecko
             ::Appium::Logger.debug('Gecko Driver for macOS')
           when :mac2
-            ::Appium::Logger.debug('macOS XCUITest')
+            ::Appium::Core::Mac2::Bridge.for self
           else
             # no Mac specific extentions
             ::Appium::Logger.debug('macOS Native')
@@ -559,36 +552,9 @@ module Appium
         self
       end
 
-      # @private
-      def validate_keys(opts)
-        flatten_ops = flatten_hash_keys(opts)
-
-        # FIXME: Remove 'desired_capabilities' in the next major Selenium update
-        unless opts.member?(:caps) || opts.member?(:capabilities) || opts.member?(:desired_capabilities)
-          raise Error::NoCapabilityError
-        end
-
-        if !opts.member?(:appium_lib) && flatten_ops.member?(:appium_lib)
-          raise Error::CapabilityStructureError, 'Please check the value of appium_lib in the capability'
-        end
-
-        true
-      end
-
-      # @private
-      def flatten_hash_keys(hash, flatten_keys_result = [])
-        hash.each do |key, value|
-          flatten_keys_result << key
-          flatten_hash_keys(value, flatten_keys_result) if value.is_a?(Hash)
-        end
-
-        flatten_keys_result
-      end
-
       # @private
       def get_caps(opts)
-        # FIXME: Remove 'desired_capabilities' in the next major Selenium update
-        Core::Base::Capabilities.create_capabilities(opts[:caps] || opts[:capabilities] || opts[:desired_capabilities] || {})
+        Core::Base::Capabilities.new(opts[:caps] || opts[:capabilities] || {})
       end
 
       # @private

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.
       #
@@ -60,20 +68,20 @@ module Appium
       #
       # @example
       #
-      #   @driver.immediate_value 'hello'
+      #   element.immediate_value 'hello'
       #
       def immediate_value(*value)
-        @bridge.set_immediate_value(self, *value)
+        @bridge.set_immediate_value @id, *value
       end
 
       # Replace the value to element directly
       #
       # @example
       #
-      #   @driver.replace_value 'hello'
+      #   element.replace_value 'hello'
       #
       def replace_value(*value)
-        @bridge.replace_value(self, *value)
+        @bridge.replace_value @id, *value
       end
 
       # For use with location_rel.
@@ -99,7 +107,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/uiautomation/patch.rb

@@ -21,7 +21,7 @@ module Appium
         # will trigger as soon as the file is required. in contrast a method
         # will trigger only when invoked.
         def self.patch_webdriver_element
-          ::Selenium::WebDriver::Element.class_eval do
+          ::Appium::Core::Element.class_eval do
             # Cross platform way of entering text into a textfield
             def type(text, driver)
               driver.execute_script %(au.getElement('#{ref}').setValue('#{text}');)

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/mac2.rb

@@ -0,0 +1,17 @@
+# 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.
+
+# loaded in common/driver.rb
+require_relative 'mac2/device'
+require_relative 'mac2/bridge'

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 = '5.5.0' unless defined? ::Appium::Core::VERSION
+    DATE    = '2022-10-09' unless defined? ::Appium::Core::DATE
   end
 end

data/lib/appium_lib_core.rb

@@ -17,11 +17,8 @@ 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'
 
 module Appium
   # convert all keys (including nested) to symbols
@@ -30,7 +27,7 @@ module Appium
   # 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
+    raise ::Appium::Core::Error::ArgumentError, 'symbolize_keys requires a hash' unless hash.is_a? Hash
 
     hash.each_with_object({}) do |pair, acc|
       key = begin