appium_lib 9.6.1 → 9.7.0

data/lib/appium_lib/core/common/error.rb

@@ -0,0 +1,13 @@
+module Appium
+  module Core
+    module Error
+      class CoreError < StandardError; end
+
+      class NotSupportedAppiumServer < CoreError; end
+      class NoSuchElementError < CoreError; end
+
+      # Server side error
+      class ServerError; end
+    end
+  end
+end

data/lib/appium_lib/core/common/log.rb

@@ -0,0 +1,30 @@
+module Appium
+  module Core
+    class Logs
+      def initialize(bridge)
+        @bridge = bridge
+      end
+
+      # @param [String|Hash] type You can get particular type's logs.
+      # @return [[Selenium::WebDriver::LogEntry]] A list of logs data.
+      #
+      # @example
+      #   Appium::Core::Logs.new(driver).get("syslog") #=> [[Selenium::WebDriver::LogEntry]]
+      #   Appium::Core::Logs.new(driver).get(:syslog)  #=> [[Selenium::WebDriver::LogEntry]]
+      #
+      def get(type)
+        @bridge.get type
+      end
+
+      # Get a list of available log types
+      #
+      # @return [[Hash]] A list of available log types.
+      # @example
+      #   Appium::Core::Logs.new(driver).available_types #=>  [:syslog, :crashlog, :performance]
+      #
+      def available_types
+        @bridge.available_types
+      end
+    end
+  end # module Core
+end # module Appium

data/lib/appium_lib/{logger.rb → core/common/logger.rb}

@@ -1,4 +1,6 @@
+require 'forwardable'
 require 'logger'
+require 'ap'
 
 module Appium
   module Logger

data/lib/appium_lib/core/core.rb

@@ -0,0 +1,38 @@
+require 'selenium-webdriver'
+
+require_relative 'common'
+require_relative 'patch'
+require_relative 'driver'
+
+# for multi touch related methods
+require_relative 'device/touch_actions'
+require_relative 'device/multi_touch'
+
+require_relative 'android'
+require_relative 'android_uiautomator2'
+
+require_relative 'ios'
+require_relative 'ios_xcuitest'
+
+module Appium
+  # convert all keys (including nested) 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 'symbolize_keys requires a hash' unless hash.is_a? Hash
+    result = {}
+    hash.each do |key, value|
+      key = key.to_sym rescue key # rubocop:disable Style/RescueModifier
+      result[key] = value.is_a?(Hash) ? symbolize_keys(value) : value
+    end
+    result
+  end
+
+  module Core
+    def self.for(*args)
+      Core::Driver.for(*args)
+    end
+  end
+end

data/lib/appium_lib/core/device/multi_touch.rb

@@ -0,0 +1,213 @@
+module Appium
+  module Core
+    # MultiTouch actions allow for multiple touches to happen at the same time,
+    # for instance, to simulate multiple finger swipes.
+    #
+    # Create a series of touch actions by themselves (without a `prepare()`), then
+    # add to a new MultiTouch action.  When ready, call `prepare()` and all
+    # actions will be executed simultaneously.
+    #
+    # ```ruby
+    # action_1 = TouchAction.new.press(x: 45, y: 100).wait(5).release
+    # action_2 = TouchAction.new.tap(element: el, x: 50, y:5, count: 3)
+    #
+    # driver =  Appium::Driver.new(opts, false).start_driver
+    # multi_touch_action = MultiTouch.new(driver)
+    # multi_touch_action.add action_1
+    # multi_touch_action.add action_2
+    # multi_touch_action.perform
+    # ```
+
+    class MultiTouch
+      class << self
+        # Convenience method for pinching the screen.
+        # Places two fingers at the edges of the screen and brings them together.
+        # @param percentage (int) The percent size by which to shrink the screen when pinched.
+        # @param auto_perform (boolean) Whether to perform the action immediately (default true)
+        # @param driver (Driver) Set a driver to conduct the action. DEfault is global driver($driver)
+        #
+        # ```ruby
+        # driver =  Appium::Driver.new(opts, false).start_driver
+        # pinch percentage: 75, driver: driver #=> Pinch the screen from the top right and bottom left corners
+        # ```
+        #
+        # Without auto_perform
+        #
+        # ```ruby
+        # driver =  Appium::Driver.new(opts, false).start_driver
+        # action = pinch percentage: 75, auto_perform: false, driver: driver
+        #   #=> Pinch the screen from the top right and bottom left corners
+        # action.perform    #=> to 25% of its size.
+        # ```
+        def pinch(percentage: 25, auto_perform: true, driver:)
+          raise ArgumentError("Can't pinch to greater than screen size.") if percentage > 100
+
+          rate = Float(percentage) / 100
+          pinch = MultiTouch.new(driver)
+
+          # TODO: Don't use driver automation handler here.
+          if pinch.driver.automation_name_is_xcuitest?
+            top, bottom = pinch_for_xcuitest(rate, pinch.driver)
+          elsif pinch.driver.device_is_android?
+            top, bottom = pinch_android(rate, pinch.driver)
+          else
+            top, bottom = pinch_ios(rate, pinch.driver)
+          end
+
+          pinch.add top
+          pinch.add bottom
+          return pinch unless auto_perform
+          pinch.perform
+        end
+
+        # Convenience method for zooming the screen.
+        # Places two fingers at the edges of the screen and brings them together.
+        # @param percentage (int) The percent size by which to shrink the screen when pinched.
+        # @param auto_perform (boolean) Whether to perform the action immediately (default true)
+        # @param driver (Driver) Set a driver to conduct the action. DEfault is global driver($driver)
+        #
+        # ```ruby
+        # driver =  Appium::Driver.new(opts, false).start_driver
+        # action = zoom percentage: 200, driver: driver #=> Zoom in the screen from the center until it doubles in size.
+        # ```
+        #
+        # Without auto_perform
+        #
+        # ```ruby
+        # driver =  Appium::Driver.new(opts, false).start_driver
+        # action = zoom percentage: 200, auto_perform: false, driver: driver
+        #   #=> Zoom in the screen from the center until it doubles in size.
+        # action.perform    #=> to 25% of its size.
+        # ```
+        def zoom(percentage: 200, auto_perform: true, driver:)
+          raise ArgumentError("Can't zoom to smaller then screen size.") if percentage < 100
+
+          rate = 100 / Float(percentage)
+          zoom = MultiTouch.new(driver)
+
+          # TODO: Don't use driver automation handler here.
+          if zoom.driver.automation_name_is_xcuitest?
+            top, bottom = zoom_for_xcuitest(rate, zoom.driver)
+          elsif zoom.driver.device_is_android?
+            top, bottom = zoom_android(rate, zoom.driver)
+          else
+            top, bottom = zoom_ios(rate, zoom.driver)
+          end
+
+          zoom.add top
+          zoom.add bottom
+          return zoom unless auto_perform
+          zoom.perform
+        end
+
+        private
+
+        def pinch_for_xcuitest(rate, driver)
+          height = 100
+
+          ele = driver.find_element :class, 'XCUIElementTypeApplication'
+          top = ::Appium::Core::TouchAction.new(driver)
+          top.swipe({ start_x: 0.5, start_y: 0.0,
+                      offset_x: 0.0, offset_y: (1 - rate) * height }, ele)
+
+          bottom = ::Appium::Core::TouchAction.new(driver)
+          bottom.swipe({ start_x: 0.5, start_y: 1.0,
+                         offset_x: 0.0, offset_y: rate * height }, ele)
+
+          [top, bottom]
+        end
+
+        def pinch_android(rate, driver)
+          height = 100
+
+          top = ::Appium::Core::TouchAction.new(driver)
+          top.swipe start_x: 0.5, start_y: 1.0 * height,
+                    end_x: 0.5, end_y: rate * height, duration: 1_000
+
+          bottom = ::Appium::Core::TouchAction.new(driver)
+          bottom.swipe start_x: 0.5, start_y: 0.0,
+                       end_x: 0.5, end_y: (1 - rate) * height, duration: 1_000
+
+          [top, bottom]
+        end
+
+        def pinch_ios(rate, driver)
+          height = 100
+
+          top = ::Appium::Core::TouchAction.new(driver)
+          top.swipe start_x: 0.5, start_y: 0.0,
+                    offset_x: 0.0, offset_y: (1 - rate) * height, duration: 1_000
+
+          bottom = ::Appium::Core::TouchAction.new(driver)
+          bottom.swipe start_x: 0.5, start_y: 1.0,
+                       offset_x: 0.0, offset_y: rate * height, duration: 1_000
+
+          [top, bottom]
+        end
+
+        def zoom_for_xcuitest(rate, driver)
+          height = 100
+
+          ele = driver.find_element :class, 'XCUIElementTypeApplication'
+          top = ::Appium::Core::TouchAction.new(driver)
+          top.swipe({ start_x: 0.5, start_y: (1 - rate) * height,
+                      offset_x: 0.0, offset_y: - (1 - rate) * height }, ele)
+
+          bottom = ::Appium::Core::TouchAction.new(driver)
+          bottom.swipe({ start_x: 0.5, start_y: rate * height,
+                         offset_x: 0.0, offset_y: (1 - rate) * height }, ele)
+
+          [top, bottom]
+        end
+
+        def zoom_android(rate, driver)
+          height = 100
+
+          top = ::Appium::Core::TouchAction.new(driver)
+          top.swipe start_x: 0.5, start_y: (1.0 - rate) * height,
+                    end_x: 0.5, end_y: 0.0, duration: 1_000
+
+          bottom = ::Appium::Core::TouchAction.new(driver)
+          bottom.swipe start_x: 0.5, start_y: rate * height,
+                       end_x: 0.5, end_y: 1.0 * height, duration: 1_000
+
+          [top, bottom]
+        end
+
+        def zoom_ios(rate, driver)
+          height = 100
+
+          top = ::Appium::Core::TouchAction.new(driver)
+          top.swipe start_x: 0.5, start_y: (1 - rate) * height,
+                    offset_x: 0.0, offset_y: - (1 - rate) * height, duration: 1_000
+
+          bottom = ::Appium::Core::TouchAction.new(driver)
+          bottom.swipe start_x: 0.5, start_y: rate * height,
+                       offset_x: 0.0, offset_y: (1 - rate) * height, duration: 1_000
+
+          [top, bottom]
+        end
+      end # self
+
+      attr_reader :actions, :driver
+
+      # Create a new multi-action with Driver
+      def initialize(driver)
+        @actions = []
+        @driver = driver
+      end
+
+      # Add a touch_action to be performed
+      # @param chain (TouchAction) The action to add to the chain
+      def add(chain)
+        @actions << chain.actions
+      end
+
+      # Ask Appium to perform the actions
+      def perform
+        @driver.multi_touch @actions
+        @actions.clear
+      end
+    end # class MultiTouch
+  end # module Core
+end # module Appium

data/lib/appium_lib/core/device/touch_actions.rb

@@ -0,0 +1,206 @@
+module Appium
+  # Perform a series of gestures, one after another.  Gestures are chained
+  # together and only performed when `perform()` is called. Default is conducted by global driver.
+  #
+  # Each method returns the object itself, so calls can be chained.
+  #
+  # ```ruby
+  # action = TouchAction(@driver).new.press(x: 45, y: 100).wait(5).release
+  # action.perform
+  # action = TouchAction.new.swipe(....)
+  # action.perform
+  # ```
+  module Core
+    class TouchAction
+      ACTIONS         = [:move_to, :long_press, :double_tap, :two_finger_tap, :press, :release, :tap, :wait, :perform].freeze
+      COMPLEX_ACTIONS = [:swipe].freeze
+
+      attr_reader :actions, :driver
+
+      def initialize(driver)
+        @actions = []
+        @driver = driver
+      end
+
+      # Move to the given co-ordinates.
+      #
+      # `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)
+        chain_method(:moveTo, opts)
+      end
+
+      # Press down for a specific duration.
+      # Alternatively, you can use `press(...).wait(...).release()` instead of `long_press` if duration doesn't work well.
+      # https://github.com/appium/ruby_lib/issues/231#issuecomment-269895512
+      # e.g. Appium::TouchAction.new.press(x: 280, y: 530).wait(2000).release.perform
+      #
+      # @option element [WebDriver::Element] the element to press.
+      # @option x [integer] x co-ordinate to press on.
+      # @option y [integer] y co-ordinate to press on.
+      # @option duration [integer] Number of milliseconds to press.
+      def long_press(opts)
+        args = opts.select { |k, _v| [:element, :x, :y, :duration].include? k }
+        args = args_with_ele_ref(args)
+        chain_method(:longPress, args) # longPress is what the appium server expects
+      end
+
+      # Press a finger onto the screen.  Finger will stay down until you call
+      # `release`.
+      #
+      # @option opts [WebDriver::Element] :element (Optional) Element to press within.
+      # @option opts [integer] :x x co-ordinate to press on
+      # @option opts [integer] :y y co-ordinate to press on
+      def press(opts)
+        args = opts.select { |k, _v| [:element, :x, :y].include? k }
+        args = args_with_ele_ref(args)
+        chain_method(:press, args)
+      end
+
+      # Remove a finger from the screen.
+      #
+      # @option opts [WebDriver::Element] :element (Optional) Element to release from.
+      # @option opts [integer] :x x co-ordinate to release from
+      # @option opts [integer] :y y co-ordinate to release from
+      def release(opts = nil)
+        args = args_with_ele_ref(opts) if opts
+        chain_method(:release, args)
+      end
+
+      # Touch a point on the screen.
+      # Alternatively, you can use `press(...).release.perform` instead of `tap(...).perform`.
+      #
+      # @option opts [WebDriver::Element] :element (Optional) Element to restrict scope too.
+      # @option opts [integer] :x x co-ordinate to tap
+      # @option opts [integer] :y y co-ordinate to tap
+      # @option opts [integer] :fingers how many fingers to tap with (Default 1)
+      def tap(opts)
+        opts[:count] = opts.delete(:fingers) if opts[:fingers]
+        opts[:count] ||= 1
+        args = args_with_ele_ref opts
+        chain_method(:tap, args)
+      end
+
+      # Double tap an element on the screen
+      #
+      # @option opts [WebDriver::Element] :element (Optional) Element to restrict scope too.
+      # @option opts [integer] :x x co-ordinate to tap
+      # @option opts [integer] :y y co-ordinate to tap
+
+      def double_tap(opts)
+        args = opts.select { |k, _v| [:element, :x, :y].include? k }
+        args = args_with_ele_ref(args)
+        chain_method(:doubleTap, args) # doubleTap is what the appium server expects
+      end
+
+      # Two finger tap an element on the screen
+      #
+      # @option opts [WebDriver::Element] :element (Optional) Element to restrict scope too.
+      # @option opts [integer] :x x co-ordinate to tap
+      # @option opts [integer] :y y co-ordinate to tap
+      def two_finger_tap(opts)
+        args = opts.select { |k, _v| [:element, :x, :y].include? k }
+        args = args_with_ele_ref(args)
+        chain_method(:twoFingerTap, args) # twoFingerTap is what the appium server expects
+      end
+
+      # Pause for a number of milliseconds before the next action
+      # @param milliseconds [integer] Number of milliseconds to pause for
+      def wait(milliseconds)
+        args = { ms: milliseconds }
+        chain_method(:wait, args)
+      end
+
+      # Convenience method to peform a swipe.
+      #
+      # 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] :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.
+      def swipe(opts, ele = nil)
+        start_x  = opts.fetch :start_x, 0
+        start_y  = opts.fetch :start_y, 0
+        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
+        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: coordinates[:offset_x], y: coordinates[:offset_y], element: ele
+        else
+          press x: start_x, y: start_y
+          wait(duration) if duration
+          move_to x: coordinates[:offset_x], y: coordinates[:offset_y]
+        end
+        release
+
+        self
+      end
+
+      # Ask the driver to perform all actions in this action chain.
+      def perform
+        @driver.touch_actions @actions
+        @actions.clear
+        self
+      end
+
+      # Does nothing, currently.
+      def cancel
+        @actions << { action: cancel }
+        @driver.touch_actions @actions
+        self
+      end
+
+      # Visible for testing
+      # @private
+      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)
+        action = args ? { action: method, options: args } : { action: method }
+        @actions << action
+        self
+      end
+
+      def args_with_ele_ref(args)
+        args[:element] = args[:element].ref if args.key? :element
+        args
+      end
+    end # class TouchAction
+  end # module Core
+end # module Appium