Add multi-touch actions, touch actions.

DylanLacey · DylanLacey · commit 965ec7bab13e · 2014-04-22T12:00:46.000-07:00
diff --git a/lib/appium_lib/device/device.rb b/lib/appium_lib/device/device.rb
@@ -102,7 +102,7 @@ def remove(id)
           end
         end
 
-        add_endpoint_method(:is_installed?, 'session/:session_id?/appium/device/app_installed') do
+        add_endpoint_method(:is_installed?, 'session/:session_id/appium/device/app_installed') do
           def is_installed?(app_id)
             execute :is_installed?, {}, :bundleId => app_id
           end
@@ -160,6 +160,7 @@ def pull_file(path)
           end
         end
 
+        add_touch_actions
         extend_search_contexts
       end
 
@@ -176,8 +177,8 @@ def add_endpoint_method(method, path, verb=:post)
         end
 
         delegate_driver_method method
-        delegate_appium_driver_method method
-      end
+        delegate_from_appium_driver method
+      end 
 
       # @private
       def extend_webdriver_with_forwardable
@@ -194,8 +195,8 @@ def delegate_driver_method(method)
       end
 
       # @private
-      def delegate_appium_driver_method(method)
-        def_delegator :@driver, method
+      def delegate_from_appium_driver(method, delegation_target=:driver)
+        def_delegator delegation_target, method
       end
 
       # @private
@@ -246,37 +247,60 @@ def extend_search_contexts
         end
       end
 
-      # Perform a block within the given context, then switch back to the starting context.
-      # @param context (String) The context to switch to for the duration of the block.
-      #
-      # ```ruby
-      # within_context('NATIVE_APP') do
-      #   find_element [:tag, "button"]
-      # ```
-      def within_context(context)
-        existing_context = current_context
-        yield if block_given?
-        current_context = existing_context
-      end
+      def add_touch_actions
+        add_endpoint_method(:touch_actions, 'session/:session_id/touch/perform') do
+          def touch_actions(actions)
+            actions = [actions].flatten
+            execute :touch_actions, {}, actions
+          end
+        end
+
+        add_endpoint_method(:multi_touch, 'session/:session_id/touch/multi/perform') do
+          def multi_touch(actions)
+            execute :multi_touch, {}, actions: actions
+          end
+        end
+
+        actions = Appium::TouchAction::ACTIONS + Appium::TouchAction::COMPLEX_ACTIONS
+        actions.each do |method|
+          delegate_from_appium_driver(method, Appium::TouchAction)
+        end
 
-      # Change to the default context.  This is equivalent to `current_context= nil`.
-      def switch_to_default_context
-        current_context = nil
+        delegate_from_appium_driver(:pinch, Appium::MultiTouch)
+        delegate_from_appium_driver(:zoom, Appium::MultiTouch)
       end
+    end # class << self
+        
+    # @!method current_context=
+    #   Change the context to the given context.
+    #   @param [String] The context to change to
+    #
+    #   ```ruby
+    #   current_context= "NATIVE_APP"
+    #   ```
 
-      # @!method current_context=
-      #   Change the context to the given context.
-      #   @param [String] The context to change to
-      #
-      #   ```ruby
-      #   current_context= "NATIVE_APP"
-      #   ```
+    # @!method current_context
+    #   @return [String] The context currently being used.
 
-      # @!method current_context
-      #   @return [String] The context currently being used.
+    # @!method available_contexts
+    # @return [Array<String>] All usable contexts, as an array of strings.
 
-      # @!method available_contexts
-      # @return [Array<String>] All usable contexts, as an array of strings
-    end # class << self
+    # Perform a block within the given context, then switch back to the starting context.
+    # @param context (String) The context to switch to for the duration of the block.
+    #
+    # ```ruby
+    # within_context('NATIVE_APP') do
+    #   find_element [:tag, "button"]
+    # ```
+    def within_context(context)
+      existing_context = current_context
+      yield if block_given?
+      current_context = existing_context
+    end
+
+    # Change to the default context.  This is equivalent to `current_context= nil`.
+    def switch_to_default_context
+      current_context = nil
+    end
   end # module Device
-end # module Appium
+end # module Appium
diff --git a/lib/appium_lib/device/multi_touch.rb b/lib/appium_lib/device/multi_touch.rb
@@ -0,0 +1,94 @@
+module Appium
+
+  # 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).release
+  #
+  # multi_touch_action = MultiTouch.new
+  # 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)
+      #
+      # ```ruby
+      # action = pinch 75 #=> 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)
+        raise ArgumentError("Can't pinch to greater than screen size.") if percentage > 100
+
+        p = Float(percentage) / 100
+        i = 1 - p
+
+        top = TouchAction.new
+        top.swipe start_x: 1.0, start_y: 0.0, end_x: i, end_y: i, duration: 1
+
+        bottom = TouchAction.new
+        bottom.swipe(start_x: 0.0, start_y: 1.0, end_x: p, end_y: p, duration: 1)
+
+        pinch = MultiTouch.new
+        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)
+      #
+      # ```ruby
+      # action = zoom 200 #=> Zoom in the screen from the center until it doubles in size.
+      # action.perform
+      # ```
+      def zoom(percentage=200, auto_perform=true)
+        raise ArgumentError("Can't zoom to smaller then screen size.") if percentage < 100
+
+        p = 100 / Float(percentage)
+        i = 1 - p
+
+        top = TouchAction.new
+        top.swipe start_x: i, start_y: i, end_x: 1, end_y: 1, duration: 1
+
+        bottom = TouchAction.new
+        bottom.swipe start_x: p, start_y: p, end_x: 1, end_y: 1, duration: 1
+
+        zoom = MultiTouch.new
+        zoom.add top
+        zoom.add bottom
+        return zoom unless auto_perform
+        zoom.perform
+      end
+    end
+    
+    # Create a new multi-action
+    def initialize
+      @actions = []
+    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
+    end
+  end
+end
diff --git a/lib/appium_lib/device/touch_actions.rb b/lib/appium_lib/device/touch_actions.rb
@@ -0,0 +1,149 @@
+module Appium
+
+  # Perform a series of gestures, one after another.  Gestures are chained
+  # together and only performed when `perform()` is called.
+  #
+  # Each method returns the object itself, so calls can be chained.
+  #
+  # ```ruby
+  # action = TouchAction.new.press(x: 45, y: 100).wait(5).release
+  class TouchAction
+    ACTIONS = [:moveTo, :longPress, :press, :release, :tap, :wait, :perform]
+    COMPLEX_ACTIONS = [:swipe]
+    
+    class << self
+      ACTIONS.each do |action|
+        define_method(action) do |*args|
+          ta = TouchAction.new
+          ta.send(action, args)
+          ta.perform
+        end
+      end
+
+      COMPLEX_ACTIONS.each do |action|
+        define_method(action) do |opts|
+          auto_perform = opts.delete(:auto_perform) {|k| true}
+          ta = TouchAction.new
+          ta.send(action, opts)
+          return ta unless auto_perform
+          ta.perform
+        end
+      end
+    end  
+
+    attr_reader :actions
+
+    def initialize
+      @actions = []
+    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.
+    # @option opts (WebDriver::Element) Element to scope this move within.
+    def moveTo(opts)
+      opts = args_with_ele_ref(opts)
+      chain_method(:moveTo, opts)
+    end
+
+    # Press down for a specific duration.
+    # @param element (WebDriver::Element) the element to press.
+    # @param x (integer) x co-ordinate to press on.
+    # @param y (integer) y co-ordinate to press on.
+    # @param (integer) Number of seconds to press.
+    def press_for_duration(element, x, y, duration)
+      @actions << {element: element.ref, x: x, y: y, duration: duration}
+      chain_method(:longPress, args)
+    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
+    #
+    # @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_with_defaults = {count: 1}.merge opts
+      chain_method(:tap, opts_with_defaults)
+    end
+
+    # Pause for a number of seconds before the next action
+    # @params seconds (integer) Number of seconds to pause for
+    def wait(seconds)
+      args = {ms: seconds}
+      chain_method(:wait, args)
+    end
+
+    # Convenience method to peform a swipe.
+    # @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] :end_x Where to end swiping, on the x axis.  Default 0.
+    # @option opts [int] :end_y Where to end swiping, on the y axis.  Default 0.
+    # @option opts [int] :duration How long the actual swipe takes to complete.
+    def swipe(opts)
+      start_x = opts.fetch :start_x, 0
+      start_y = opts.fetch :start_y, 0
+      end_x = opts.fetch :end_x, 0
+      end_y = opts.fetch :end_y, 0
+      duration = opts[:duration]
+
+      self.press x: start_x, y: start_y
+      self.wait(duration) if duration
+      self.moveTo x: end_x, y: end_y
+      self.release
+      self
+    end
+
+    # Ask the driver to perform all actions in this action chain.
+    def perform
+      $driver.touch_actions @actions
+      self
+    end
+
+    # Does nothing, currently.
+    def cancel
+      @actions << {action: cancel}
+      $driver.touch_actions @actions
+      self
+    end
+
+    private
+
+    def chain_method(method, args=nil)
+      if args
+        @actions << {action: method, options: args}
+      else
+        @actions << {action: method}
+      end
+      self
+    end
+
+    def args_with_ele_ref(args)
+      args[:element] = args[:element].ref if args.has_key? :element
+      args
+    end
+  end
+end
diff --git a/lib/appium_lib/driver.rb b/lib/appium_lib/driver.rb
@@ -33,6 +33,8 @@
 
 # device methods
 require_relative 'device/device'
+require_relative 'device/touch_actions'
+require_relative 'device/multi_touch'
 
 # Fix uninitialized constant Minitest (NameError)
 module Minitest
