appium_lib 9.2.0 → 9.3.0

data/lib/appium_lib/device/touch_actions.rb

@@ -30,8 +30,11 @@ module Appium
     end
 
     # Move to the given co-ordinates.
-    # @option opts [integer] :x x co-ordinate to move to.
-    # @option opts [integer] :y y co-ordinate to move to.
+    #
+    # `move_to`'s `x` and `y` have two case. One is working as coordinate, the other is working as offset.
+    #
+    # @option opts [integer] :x x co-ordinate to move to if element isn't set. Works as an offset if x is set with Element.
+    # @option opts [integer] :y y co-ordinate to move to if element isn't set. Works as an offset if y is set with Element.
     # @option opts [WebDriver::Element] Element to scope this move within.
     def move_to(opts)
       opts = args_with_ele_ref(opts)
@@ -123,39 +126,38 @@ module Appium
     #
     # Note that iOS 7 simulators have broken swipe.
     #
+    # For iOS: Use `offset_x` and `offset_y` to define the end point.
+    #
+    # For Android: Use `end_x` and `end_y` to define the end point.
+    #
+    # If you'd like more details, please read tests and its log samples in
+    # `ios_tests/lib/ios/specs/device/touch_actions.rb` and `ios_tests/lib/ios/specs/device/touch_actions.rb`
+    #
     # @option opts [int] :start_x Where to start swiping, on the x axis.  Default 0.
     # @option opts [int] :start_y Where to start swiping, on the y axis.  Default 0.
-    # @option opts [int] :delta_x The distance from start to move, on the x axis.  Default 0.
-    # @option opts [int] :delta_y The distance from start to move, on the y axis.  Default 0.
+    # @option opts [int] :offset_x For iOS. Offset, on the x axis.  Default 0.
+    # @option opts [int] :offset_y For iOS. Offset, on the y axis.  Default 0.
+    # @option opts [int] :end_x For Android. Where to end swiping, on the x axis.  Default 0.
+    # @option opts [int] :end_y For Android. Where to end swiping, on the y axis.  Default 0.
     # @option opts [int] :duration How long the actual swipe takes to complete in milliseconds. Default 200.
-    # @deprecated Please do not use end_x, end_y anymore
     def swipe(opts, ele = nil)
       start_x  = opts.fetch :start_x, 0
       start_y  = opts.fetch :start_y, 0
-      delta_x  = opts.fetch :delta_x, nil
-      delta_y  = opts.fetch :delta_y, nil
+      offset_x = opts.fetch :offset_x, nil
+      offset_y = opts.fetch :offset_y, nil
       end_x    = opts.fetch :end_x, nil
       end_y    = opts.fetch :end_y, nil
-
-      if end_x || end_y
-        warn '[DEPRECATION] `end_x` and `end_y` are deprecated. Please use `delta_x` and `delta_y` instead.'
-      end
-
-      delta_x ||= end_x
-      delta_y ||= end_y
-
-      delta_x ||= 0
-      delta_y ||= 0
-
       duration = opts.fetch :duration, 200
 
+      coordinates = swipe_coordinates(end_x: end_x, end_y: end_y, offset_x: offset_x, offset_y: offset_y)
+
       if ele # pinch/zoom for XCUITest
         press x: start_x, y: start_y, element: ele
-        move_to x: start_x + delta_x, y: start_y + delta_y, element: ele
+        move_to x: coordinates[:offset_x], y: coordinates[:offset_y], element: ele
       else
         press x: start_x, y: start_y
         wait(duration) if duration
-        move_to x: start_x + delta_x, y: start_y + delta_y
+        move_to x: coordinates[:offset_x], y: coordinates[:offset_y]
       end
       release
 
@@ -175,6 +177,22 @@ module Appium
       self
     end
 
+    def swipe_coordinates(end_x: nil, end_y: nil, offset_x: nil, offset_y: nil)
+      if $driver.device_is_android?
+        puts 'end_x and end_y are used for Android. Not offset_x and offset_y.' if end_x.nil? || end_y.nil?
+        end_x ||= 0
+        end_y ||= 0
+        return { offset_x: end_x, offset_y: end_y }
+      elsif offset_x.nil? || offset_y.nil?
+        puts 'offset_x and offset_y are used for iOS. Not end_x and end_y point.'
+      end
+
+      offset_x ||= 0
+      offset_y ||= 0
+
+      { offset_x: offset_x, offset_y: offset_y }
+    end
+
     private
 
     def chain_method(method, args = nil)

data/lib/appium_lib/driver.rb

@@ -304,23 +304,52 @@ module Appium
     # Return http client called in start_driver()
     # @return [Selenium::WebDriver::Remote::Http::Default] the http client
     attr_reader :http_client
+    # Return a time wait timeout
+    # Wait time for ::Appium::Common.wait or ::Appium::Common.wait_true.
+    # Provide Appium::Drive like { appium_lib: { wait_timeout: 20 } }
+    # @return [Integer]
+    attr_reader :appium_wait_timeout
+    # Return a time wait timeout
+    # Wait interval time for ::Appium::Common.wait or ::Appium::Common.wait_true.
+    # Provide Appium::Drive like { appium_lib: { wait_interval: 20 } }
+    # @return [Integer]
+    attr_reader :appium_wait_interval
 
     # Creates a new driver
     #
-    # ```ruby
-    # require 'rubygems'
-    # require 'appium_lib'
+    # @example
     #
-    # # platformName takes a string or a symbol.
+    #     ```ruby
+    #     require 'rubygems'
+    #     require 'appium_lib'
     #
-    # # Start iOS driver
-    # opts = { caps: { platformName: :ios, app: '/path/to/MyiOS.app' } }
-    # Appium::Driver.new(opts).start_driver
+    #     # platformName takes a string or a symbol.
     #
-    # # Start Android driver
-    # opts = { caps: { platformName: :android, app: '/path/to/my.apk' } }
-    # Appium::Driver.new(opts).start_driver
-    # ```
+    #     # Start iOS driver
+    #     opts = {
+    #              caps: {
+    #                platformName: :ios,
+    #                app: '/path/to/MyiOS.app'
+    #              },
+    #              appium_lib: {
+    #                wait_timeout: 30
+    #              }
+    #            }
+    #     Appium::Driver.new(opts).start_driver
+    #
+    #     # Start Android driver
+    #     opts = {
+    #              caps: {
+    #                platformName: :android,
+    #                app: '/path/to/my.apk'
+    #              },
+    #              appium_lib: {
+    #                wait_timeout: 30,
+    #                wait_interval: 1
+    #              }
+    #            }
+    #     Appium::Driver.new(opts).start_driver
+    #     ```
     #
     # @param opts [Object] A hash containing various options.
     # @return [Driver]
@@ -344,6 +373,9 @@ module Appium
       @sauce_access_key = appium_lib_opts.fetch :sauce_access_key, ENV['SAUCE_ACCESS_KEY']
       @sauce_access_key = nil if !@sauce_access_key || (@sauce_access_key.is_a?(String) && @sauce_access_key.empty?)
       @appium_port      = appium_lib_opts.fetch :port, 4723
+      # timeout and interval used in ::Appium::Comm.wait/wait_true
+      @appium_wait_timeout  = appium_lib_opts.fetch :wait_timeout, 30
+      @appium_wait_interval = appium_lib_opts.fetch :wait_interval, 0.5
 
       # to pass it in Selenium.new.
       # `listener = opts.delete(:listener)` is called in Selenium::Driver.new
@@ -408,7 +440,9 @@ module Appium
           port:             @appium_port,
           device:           @appium_device,
           debug:            @appium_debug,
-          listener:         @listener
+          listener:         @listener,
+          wait_timeout:     @appium_wait_timeout,
+          wait_interval:    @appium_wait_interval
       }
 
       # Return duplicates so attributes are immutable
@@ -432,8 +466,8 @@ module Appium
     # If the Appium server is under REQUIRED_VERSION_XCUITEST, then error is raised.
     # @return [Boolean]
     def check_server_version_xcuitest
-      if automation_name_is_xcuitest? && (@appium_server_version['build']['version'] <= REQUIRED_VERSION_XCUITEST)
-        raise Appium::Error::NotSupportedAppiumServer, "XCUITest requires over Appium #{REQUIRED_VERSION_XCUITEST}"
+      if automation_name_is_xcuitest? && (@appium_server_version['build']['version'] < REQUIRED_VERSION_XCUITEST)
+        raise Appium::Error::NotSupportedAppiumServer, "XCUITest requires Appium version >= #{REQUIRED_VERSION_XCUITEST}"
       end
       true
     end
@@ -610,11 +644,11 @@ module Appium
     #
     # exists { button('sign in') } ? puts('true') : puts('false')
     #
-    # @param pre_check [Integer]  the amount in seconds to set the
-    #                             wait to before checking existance
-    # @param post_check [Integer] the amount in seconds to set the
-    #                             wait to after checking existance
-    # @param search_block [Block] the block to call
+    # @param [Integer] pre_check The amount in seconds to set the
+    #                             wait to before checking existence
+    # @param [Integer] post_check The amount in seconds to set the
+    #                             wait to after checking existence
+    # @yield The block to call
     # @return [Boolean]
     def exists(pre_check = 0, post_check = @default_wait)
       # do not uset set_wait here.
@@ -637,8 +671,8 @@ module Appium
     end
 
     # The same as @driver.execute_script
-    # @param script [String] the script to execute
-    # @param args [*args] the args to pass to the script
+    # @param [String] script The script to execute
+    # @param [*args] args The args to pass to the script
     # @return [Object]
     def execute_script(script, *args)
       @driver.execute_script script, *args
@@ -646,7 +680,7 @@ module Appium
 
     # Calls @driver.find_elements
     #
-    # @param args [*args] the args to use
+    # @param [*args] args The args to use
     # @return [Array<Element>] Array is empty when no elements are found.
     def find_elements(*args)
       @driver.find_elements_with_appium(*args)
@@ -654,7 +688,7 @@ module Appium
 
     # Calls @driver.find_elements
     #
-    # @param args [*args] the args to use
+    # @param [*args] args The args to use
     # @return [Element]
     def find_element(*args)
       @driver.find_element_with_appium(*args)
@@ -664,7 +698,7 @@ module Appium
     #
     # @note This method does not work on real devices.
     #
-    # @param [Hash] opts consisting of:
+    # @param  [Hash] opts consisting of:
     # @option opts [Float] :latitude the latitude in degrees (required)
     # @option opts [Float] :longitude the longitude in degees (required)
     # @option opts [Float] :altitude the altitude, defaulting to 75

data/lib/appium_lib/ios/element/button.rb

@@ -18,7 +18,7 @@ module Appium
       return ele_index button_class, value if value.is_a? Numeric
 
       if automation_name_is_xcuitest?
-        _raise_error_if_no_element buttons(value).first
+        raise_error_if_no_element buttons(value).first
       else
         ele_by_json_visible_contains button_class, value
       end
@@ -32,8 +32,8 @@ module Appium
       return tags button_class unless value
 
       if automation_name_is_xcuitest?
-        elements = tags button_class
-        _elements_include elements, value
+        visible_elements = tags button_class
+        elements_include visible_elements, value
       else
         eles_by_json_visible_contains button_class, value
       end
@@ -58,7 +58,7 @@ module Appium
     # @return [UIAButton|XCUIElementTypeButton]
     def button_exact(value)
       if automation_name_is_xcuitest?
-        _raise_error_if_no_element buttons_exact(value).first
+        raise_error_if_no_element buttons_exact(value).first
       else
         ele_by_json_visible_exact button_class, value
       end
@@ -69,8 +69,8 @@ module Appium
     # @return [Array<UIAButton|XCUIElementTypeButton>]
     def buttons_exact(value)
       if automation_name_is_xcuitest?
-        elements = tags button_class
-        _elements_exact elements, value
+        visible_elements = tags button_class
+        elements_exact visible_elements, value
       else
         eles_by_json_visible_exact button_class, value
       end

data/lib/appium_lib/ios/element/generic.rb

@@ -5,7 +5,7 @@ module Appium
     # @return [Element]
     def find(value)
       if automation_name_is_xcuitest?
-        find_ele_by_attr_include '*', '*', value
+        raise_error_if_no_element finds(value).first
       else
         ele_by_json_visible_contains '*', value
       end
@@ -16,7 +16,8 @@ module Appium
     # @return [Array<Element>]
     def finds(value)
       if automation_name_is_xcuitest?
-        find_eles_by_attr_include '*', '*', value
+        elements = find_eles_by_attr_include '*', '*', value
+        select_visible_elements elements
       else
         eles_by_json_visible_contains '*', value
       end
@@ -27,7 +28,7 @@ module Appium
     # @return [Element]
     def find_exact(value)
       if automation_name_is_xcuitest?
-        find_ele_by_attr '*', '*', value
+        raise_error_if_no_element finds_exact(value).first
       else
         ele_by_json_visible_exact '*', value
       end
@@ -38,7 +39,8 @@ module Appium
     # @return [Array<Element>]
     def finds_exact(value)
       if automation_name_is_xcuitest?
-        find_eles_by_attr '*', '*', value
+        elements = find_eles_by_attr '*', '*', value
+        select_visible_elements elements
       else
         eles_by_json_visible_exact '*', value
       end
@@ -46,25 +48,43 @@ module Appium
 
     private
 
-    def _raise_error_if_no_element(element)
-      raise ::Selenium::WebDriver::Error::NoSuchElementError if element.nil?
+    def raise_error_if_no_element(element)
+      error_message = 'An element could not be located on the page using the given search parameters.'
+      raise(::Selenium::WebDriver::Error::NoSuchElementError, error_message) if element.nil?
       element
     end
 
-    def _elements_include(elements, value)
+    # Return all elements include not displayed elements.
+    def elements_include(elements, value)
       return [] if elements.empty?
       elements.select do |element|
+        # `text` is equal to `value` if value is not `nil`
+        # `text` is equal to `name` if value is `nil`
         name = element.name
-        name.nil? ? false : name.downcase.include?(value.downcase)
+        text = element.value
+        name_result = name.nil? ? false : name.downcase.include?(value.downcase)
+        text_result = text.nil? ? false : text.downcase.include?(value.downcase)
+        name_result || text_result
       end
     end
 
-    def _elements_exact(elements, value)
+    # Return all elements include not displayed elements.
+    def elements_exact(elements, value)
       return [] if elements.empty?
       elements.select do |element|
+        # `text` is equal to `value` if value is not `nil`
+        # `text` is equal to `name` if value is `nil`
         name = element.name
-        name.nil? ? false : name.casecmp(value).zero?
+        text = element.value
+        name_result = name.nil? ? false : name.casecmp(value).zero?
+        text_result = text.nil? ? false : text.casecmp(value).zero?
+        name_result || text_result
       end
     end
+
+    # Return visible elements.
+    def select_visible_elements(elements)
+      elements.select(&:displayed?)
+    end
   end # module Ios
 end # module Appium

data/lib/appium_lib/ios/element/text.rb

@@ -1,12 +1,12 @@
 # UIAStaticText|XCUIElementTypeStaticText methods
 module Appium
   module Ios
-    IAStaticText = 'UIAStaticText'.freeze
+    UIAStaticText = 'UIAStaticText'.freeze
     XCUIElementTypeStaticText = 'XCUIElementTypeStaticText'.freeze
 
     # @return [String] Class name for text
     def static_text_class
-      automation_name_is_xcuitest? ? XCUIElementTypeStaticText : IAStaticText
+      automation_name_is_xcuitest? ? XCUIElementTypeStaticText : UIAStaticText
     end
 
     # Find the first UIAStaticText|XCUIElementTypeStaticText that contains value or by index.
@@ -17,7 +17,7 @@ module Appium
       return ele_index static_text_class, value if value.is_a? Numeric
 
       if automation_name_is_xcuitest?
-        _raise_error_if_no_element texts(value).first
+        raise_error_if_no_element texts(value).first
       else
         ele_by_json_visible_contains static_text_class, value
       end
@@ -31,8 +31,8 @@ module Appium
       return tags static_text_class unless value
 
       if automation_name_is_xcuitest?
-        elements = tags static_text_class
-        _elements_include elements, value
+        visible_elements = tags static_text_class
+        elements_include visible_elements, value
       else
         eles_by_json_visible_contains static_text_class, value
       end
@@ -55,7 +55,7 @@ module Appium
     # @return [UIAStaticText|XCUIElementTypeStaticText]
     def text_exact(value)
       if automation_name_is_xcuitest?
-        _raise_error_if_no_element texts_exact(value).first
+        raise_error_if_no_element texts_exact(value).first
       else
         ele_by_json_visible_exact static_text_class, value
       end
@@ -66,8 +66,8 @@ module Appium
     # @return [Array<UIAStaticText|XCUIElementTypeStaticText>]
     def texts_exact(value)
       if automation_name_is_xcuitest?
-        elements = tags static_text_class
-        _elements_exact elements, value
+        visible_elements = tags static_text_class
+        elements_exact visible_elements, value
       else
         eles_by_json_visible_exact static_text_class, value
       end

data/lib/appium_lib/ios/element/textfield.rb

@@ -27,13 +27,14 @@ module Appium
     # @private
     # for XCUITest
     def _textfield_with_xpath
-      xpath "//#{_textfields}"
+      raise_error_if_no_element _textfields_with_xpath.first
     end
 
     # @private
     # for XCUITest
     def _textfields_with_xpath
-      xpaths "//#{_textfields}"
+      elements = xpaths "//#{_textfields}"
+      select_visible_elements elements
     end
 
     # Appium
@@ -78,7 +79,7 @@ module Appium
       end
 
       if automation_name_is_xcuitest?
-        find_ele_by_attr_include _textfields, '*', value
+        raise_error_if_no_element textfields(value).first
       else
         ele_by_json _textfield_contains_string value
       end
@@ -91,7 +92,8 @@ module Appium
     def textfields(value = false)
       if automation_name_is_xcuitest?
         return _textfields_with_xpath unless value
-        find_eles_by_attr_include _textfields, '*', value
+        elements = find_eles_by_attr_include _textfields, '*', value
+        select_visible_elements elements
       else
         return eles_by_json _textfield_visible unless value
         eles_by_json _textfield_contains_string value
@@ -125,7 +127,7 @@ module Appium
     # @return [TextField]
     def textfield_exact(value)
       if automation_name_is_xcuitest?
-        find_ele_by_attr _textfields, '*', value
+        raise_error_if_no_element textfields_exact(value).first
       else
         ele_by_json _textfield_exact_string value
       end
@@ -136,7 +138,8 @@ module Appium
     # @return [Array<TextField>]
     def textfields_exact(value)
       if automation_name_is_xcuitest?
-        find_eles_by_attr _textfields, '*', value
+        elements = find_eles_by_attr _textfields, '*', value
+        select_visible_elements elements
       else
         eles_by_json _textfield_exact_string value
       end