calabash 2.0.0.pre11 → 2.0.0.prelegacy

data/lib/calabash/gestures.rb

@@ -1,6 +1,8 @@
 module Calabash
   # Methods for performing gestures.  Gestures are taps, flicks, and pans.
-  # All gestures execute "physical gestures" like human users would.
+  #
+  # Many gestures take an optional :duration. On iOS, the duration must be
+  # between 0.5 and 60 (seconds).  This is a limitation of the UIAutomation API.
   #
   # @note All gestures have _undefined return values._  This is intentional.
   #  Please do not rely on return values of gestures in your tests.  For
@@ -29,24 +31,23 @@ module Calabash
     #      |    │                 4                   │
     #      ┴    └─────────────────────────────────────┘
     #
-    #   1. cal.tap("* marked:'email'")
-    #   2. cal.tap("* marked:'email'", at: {x: 0, y: 0})
-    #   3. cal.tap("* marked:'email'", at: {x: 100, y: 0})
-    #   4. cal.tap("* marked:'email'", at: {x: 50, y: 100})
+    #   1. tap("* marked:'email'")
+    #   2. tap("* marked:'email'", at:  {x: 0, y: 0})
+    #   3. tap("* marked:'email'", at:  {x: 100, y: 0})
+    #   4. tap("* marked:'email'", at:  {x: 50, y: 100})
     #
     # @param [String, Hash, Calabash::Query] query A query describing the view
     #   to tap.
-    # @param [Hash] at (default: `{x: 50, y: 50}`) The point at which the
+    # @param [Hash] options Options for modifying the details of the touch.
+    # @option options [Hash] :at ({x: 50, y: 50}) The point at which the
     #   gesture originates from.  It is a percentage-based translation using
-    #   top-left `{x: 0, y: 0}` as the reference point.
+    #   top-left `(0,0)` as the reference point.
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def tap(query, at: nil)
+    def tap(query, options={})
       Query.ensure_valid_query(query)
 
-      options = {at: at || {x: 50, y: 50}}
-
-      Calabash::Internal.with_default_device {|device| device.tap(Query.new(query), options)}
+      Device.default.tap(Query.new(query), options)
     end
 
     # Performs a **double_tap** on the first view that matches `query`.
@@ -55,18 +56,17 @@ module Calabash
     #
     # @param [String, Hash, Calabash::Query] query A query describing the view
     #  to tap.
-    # @param [Hash] at (default: `{x: 50, y: 50}`) The point at which the
+    # @param [Hash] options Options for modifying the details of the touch.
+    # @option options [Hash] :at ({x: 50, y: 50}) The point at which the
     #   gesture originates from.  It is a percentage-based translation using
-    #   top-left `{x: 0, y: 0}` as the reference point.
+    #   top-left `(0,0)` as the reference point.
     #
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def double_tap(query, at: nil)
+    def double_tap(query, options={})
       Query.ensure_valid_query(query)
 
-      options = {at: at || {x: 50, y: 50}}
-
-      Calabash::Internal.with_default_device {|device| device.double_tap(Query.new(query), options)}
+      Device.default.double_tap(Query.new(query), options)
     end
 
     # Performs a **long_press** on the first view that matches `query`.
@@ -77,39 +77,33 @@ module Calabash
     # @see #tap
     #
     # @param [String] query A query describing the view to tap.
-    # @param [Number] duration (default: 1.0) The amount of time in seconds to
+    # @param [Hash] options Options for modifying the details of the touch.
+    # @option options [Number] :duration (1.0) The amount of time in seconds to
     #  press.  On iOS, the duration must be between 0.5 and 60.
-    # @param [Hash] at (default: `{x: 50, y: 50}`) The point at which the
-    #   gesture originates from.  It is a percentage-based translation using
-    #   top-left `{x: 0, y: 0}` as the reference point.
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def long_press(query, duration: nil, at: nil)
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def long_press(query, options={})
       Query.ensure_valid_query(query)
 
-      options = {
-          at: at || {x: 50, y: 50},
-          duration: duration || 1.0
-      }
-
-      Calabash::Internal.with_default_device {|device| device.long_press(Query.new(query), options)}
+      Device.default.long_press(Query.new(query), options)
     end
 
-    # Performs a **pan** inside the first view that matches `query`.
+    # Performs a **pan** on the first view that matches `query`.
     #
     # A pan is a straight line swipe that pauses at the final point
     # before releasing the gesture. This is the general purpose pan method. For
-    # standardized pans see {pan_left}, {pan_right}, {pan_up}, and {pan_down}.
+    # standardized pans see `pan_left`, `pan_right`, `pan_up`, and `pan_down`.
     #
-    # @example
-    #  # Consider a pan on a scrollable view.  When the finger is is released,
-    #  # the velocity of the view is zero.
+    # Also known as **scroll** and **swipe**.
     #
     # @example
-    #  # A scrollable view displays the alphabet. Panning left will cause the
-    #  # view to scroll right.
+    #  Consider a pan on a scrollable view.  When the finger is is released,
+    #  the velocity of the view is zero.
     #
-    #  cal.pan("* id:'alphabetView'", cal.pct(80, 80), cal.pct(20, 80))
+    # @example
+    #  A scrollable view displays the alphabet. Panning left will cause the
+    #  view to scroll right.
     #
     #      Before             After
     #   ┌───────────┐  |  ┌───────────┐
@@ -118,6 +112,15 @@ module Calabash
     #   │ <───────┤ │  |  │           │
     #   └───────────┘  |  └───────────┘
     #
+    # Apple's UIAutomation 'dragInsideWithOptions' is broken on iOS Simulators.
+    # Call `pan` on iOS Simulators >= iOS 7.0 will raise an error.  See the
+    # iOS Scroll API for alternatives.
+    #
+    # @see Calabash::IOS::Scroll#scroll
+    # @see Calabash::IOS::Scroll#scroll_to_row
+    # @see Calabash::IOS::Scroll#scroll_to_row_with_mark
+    # @see Calabash::IOS::Scroll#scroll_to_item
+    # @see Calabash::IOS::Scroll#scroll_to_item_with_mark
     #
     # @param [String, Hash, Calabash::Query] query A query describing the view
     #  to pan inside.
@@ -125,18 +128,19 @@ module Calabash
     #   originates from.
     # @param [Hash] to `({:x, :y})` The point at which the gesture
     #   ends.
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
+    #
+    # @param [Hash] options Options for modifying the details of the pan.
+    # @option options [Number] :duration (0.5) How many seconds the pan takes
+    #   to complete. On iOS, the duration must be between 0.5 and 60.
+    #
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def pan(query, from, to, duration: nil)
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    # @raise [RuntimeError] If called on an iOS Simulator > iOS 7.
+    def pan(query, from, to, options={})
       Query.ensure_valid_query(query)
 
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
-      Calabash::Internal.with_default_device {|device| device.pan(Query.new(query), from, to, options)}
+      Device.default.pan(Query.new(query), from, to, options)
     end
 
     # Performs a **pan** from the center of the first view that matches
@@ -145,8 +149,8 @@ module Calabash
     # Also known as **drag and drop**.
     #
     # @example
-    #  #Panning between two elements.
-    #  cal.pan_between("* id:'first'", "* id:'second'")
+    #  Panning between two elements.
+    #  `pan_between("* id:'first'", "* id:'second'")`
     #
     #
     #      ┌───────────┐
@@ -166,137 +170,86 @@ module Calabash
     #                 │           │
     #                 └───────────┘
     #
-    # @param [String, Hash, Calabash::Query] query_from A query describing the
-    #  view to pan *from*
-    # @param [String, Hash, Calabash::Query] query_to A query describing the
-    #  view to pan *to*
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
+    # @option options [Number] :duration (1.0) How many seconds the swipe takes
+    #   to complete.
     # @raise [ViewNotFoundError] If the `query_from` returns no results.
     # @raise [ViewNotFoundError] If the `query_to` returns no results.
     # @raise [ArgumentError] If `query_from` is invalid.
     # @raise [ArgumentError] If `query_to` is invalid.
-    def pan_between(query_from, query_to, duration: nil)
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pan_between(query_from, query_to, options={})
       Query.ensure_valid_query(query_from)
       Query.ensure_valid_query(query_to)
 
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
-      Calabash::Internal.with_default_device do |device|
-        device.pan_between(Query.new(query_from), Query.new(query_to), options)
-      end
+      Device.default.pan_between(Query.new(query_from), Query.new(query_to), options)
     end
 
-    # Performs a **pan** heading _left_ inside the first view that matches
-    # `query`.
+    # Performs a **pan** heading _left_ on the first view that matches `query`.
     #
     # @see #pan
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def pan_left(query, duration: nil)
-      pan(query, {x: 90, y: 50}, {x: 10, y: 50}, duration: duration)
+    def pan_left(query, options={})
+      pan(query, {x: 90, y: 50}, {x: 10, y: 50}, options)
     end
 
-    # Performs a **pan** heading _right_ inside the first view that matches
-    # `query`.
+    # Performs a **pan** heading _right_ on the first view that matches `query`.
     #
     # @see #pan
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def pan_right(query, duration: nil)
-      pan(query, {x: 10, y: 50}, {x: 90, y: 50}, duration: duration)
+    def pan_right(query, options={})
+      pan(query, {x: 10, y: 50}, {x: 90, y: 50}, options)
     end
 
-    # Performs a **pan** heading _up_ inside the first view that matches
-    # `query`.
+    # Performs a **pan** heading _up_ on the first view that matches `query`.
     #
     # @see #pan
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def pan_up(query, duration: nil)
-      pan(query, {x: 50, y: 90}, {x: 50, y: 10}, duration: duration)
+    def pan_up(query, options={})
+      pan(query, {x: 50, y: 90}, {x: 50, y: 10}, options)
     end
 
-    # Performs a **pan** heading _down_ inside the first view that matches
-    # `query`.
+    # Performs a **pan** heading _down_ on the first view that matches `query`.
     #
     # @see #pan
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def pan_down(query, duration: nil)
-      pan(query, {x: 50, y: 10}, {x: 50, y: 90}, duration: duration)
+    def pan_down(query, options={})
+      pan(query, {x: 50, y: 10}, {x: 50, y: 90}, options)
     end
 
     # Performs a **pan** heading _left_ on the screen.
     #
     # @see #pan
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def pan_screen_left(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
+    def pan_screen_left(options={})
       pan_left('*', options)
     end
 
     # Performs a **pan** heading _right_ on the screen.
     #
     # @see #pan
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def pan_screen_right(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
+    def pan_screen_right(options={})
       pan_right('*', options)
     end
 
     # Performs a **pan** heading _up_ on the screen.
     #
     # @see #pan
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def pan_screen_up(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
+    def pan_screen_up(options={})
       _pan_screen_up(options)
     end
 
     # Performs a **pan** heading _down_ on the screen.
     #
     # @see #pan
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def pan_screen_down(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
+    def pan_screen_down(options={})
       _pan_screen_down(options)
     end
 
-    # Performs a **flick** inside the first view that matches `query`.
+    # Performs a **flick** on the first view that matches `query`.
     #
     # A flick is a straight line swipe that **lifts the finger while
     # the gesture is still in motion**. This will often cause scrollable
     # views to continue moving for some time after the gesture is released.
-    #
-    # It is likely that the gesture you want to automate is a {pan}, not a
-    # flick.
-    #
     # @see pan
     #
     # @example
-    #  # A scrollable view displays the alphabet. Flicking left will cause the
-    #  # view to scroll right.
-    #
-    #  cal.flick("* id:'alphabetView'", cal.pct(80, 80), cal.pct(20, 80))
+    #  A scrollable view displays the alphabet. Flicking left will cause the
+    #  view to scroll right.
     #
     #       Before             After
     #    ┌───────────┐  |  ┌───────────┐
@@ -306,266 +259,219 @@ module Calabash
     #    └───────────┘  |  └───────────┘
     #
     # @param [String,Hash,Query] query A query describing the view to flick
-    #  inside.
+    #  inside of.
     # @param [Hash] from `({:x, :y})` The point at which the gesture
     #   originates from.
     # @param [Hash] to `({:x, :y})` The point at which the gesture
     #   ends.
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
+    #
+    # @param [Hash] options Options for controlling the flick.
+    # @option options [Numeric] :duration The duration of the flick. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def flick(query, from, to, duration: nil)
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def flick(query, from, to, options={})
       Query.ensure_valid_query(query)
 
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
-      Calabash::Internal.with_default_device do |device|
-        device.flick(Query.new(query), from, to, options)
-      end
+      Device.default.flick(Query.new(query), from, to, options)
     end
 
-    # Performs a **flick** heading _left_ inside the first view that matches
-    # `query`.
+    # Performs a **flick** heading _left_ on the first view that matches `query`.
     # @see #flick
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def flick_left(query, duration: nil)
-      flick(query, {x: 90, y: 50}, {x: 10, y: 50}, duration: duration)
+    def flick_left(query, options={})
+      flick(query, {x: 90, y: 50}, {x: 10, y: 50}, options)
     end
 
-    # Performs a **flick** heading _right_ inside the first view that matches
+    # Performs a **flick** heading _right_ on the first view that matches
     # `query`.
     # @see #flick
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def flick_right(query, duration: nil)
-      flick(query, {x: 10, y: 50}, {x: 90, y: 50}, duration: duration)
+    def flick_right(query, options={})
+      flick(query, {x: 10, y: 50}, {x: 90, y: 50}, options)
     end
 
-    # Performs a **flick** heading _up_ inside the first view that matches
-    # `query`.
+    # Performs a **flick** heading _up_ on the first view that matches `query`.
     # @see #flick
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def flick_up(query, duration: nil)
-      flick(query, {x: 50, y: 90}, {x: 50, y: 10}, duration: duration)
+    def flick_up(query, options={})
+      flick(query, {x: 50, y: 90}, {x: 50, y: 10}, options)
     end
 
-    # Performs a **flick** heading _down_ inside the first view that matches
-    # `query`.
+    # Performs a **flick** heading _down_ on the first view that matches `query`.
     # @see #flick
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def flick_down(query, duration: nil)
-      flick(query, {x: 50, y: 10}, {x: 50, y: 90}, duration: duration)
+    def flick_down(query, options={})
+      flick(query, {x: 50, y: 10}, {x: 50, y: 90}, options)
     end
 
     # Performs a **flick** heading _left_ on the screen.
     # @see #flick
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def flick_screen_left(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
+    def flick_screen_left(options={})
       flick_left('*', options)
     end
 
     # Performs a **flick** heading _right_ on the screen.
     # @see #flick
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def flick_screen_right(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
+    def flick_screen_right(options={})
       flick_right('*', options)
     end
 
     # Performs a **flick** heading _up_ on the screen.
     # @see #flick
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def flick_screen_up(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
+    def flick_screen_up(options={})
       _flick_screen_up(options)
     end
 
     # Performs a **flick** heading _down_ on the screen.
     # @see #flick
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
-    def flick_screen_down(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
+    def flick_screen_down(options={})
       _flick_screen_down(options)
     end
 
-    # Performs a **pinch** outwards inside the first view match by `query`.
+    # Performs a **pinch** outwards on the first view match by `query`.
     #
-    # The gestures will be similar to two fingers pressing down near the
-    # center of the view and simultaneously moving towards the opposite corners
-    # of the view
-    #
-    # @example
-    #  # We have a webview that we want to pinch out on
-    #
-    #  cal.pinch_out("* id:'webView'")
-    #
-    #         Application
-    #  ┌───────────────────────┐
-    #  │───────────────────────│
-    #  │      id: webview      │
-    #  │  ┌─────────────────┐  │
-    #  │  │  ^              │  │
-    #  │  │   \             │  │
-    #  │  │    \            │  │
-    #  │  │     *    *      │  │
-    #  │  │           \     │  │
-    #  │  │            \    │  │
-    #  │  │             v   │  │
-    #  │  └─────────────────┘  │
-    #  └───────────────────────┘
-    #
-    # @example
-    #  # We have a MapView rendering a map. We want to zoom it in.
-    #  # On iOS, we should pinch out to zoom in
-    #  # On Android, we should pinch in to zoom in.
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #   to pinch.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
     #
-    #  if cal.android?
-    #    cal.pinch_in({class: "MapView"})
-    #  elsif cal.ios?
-    #    cal.pinch_out({class: "MapView"})
-    #  end
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pinch_out(query, options={})
+      Device.default.pinch(:out, query, options)
+    end
+
+    # Performs a **pinch** inwards on the first view match by `query`.
     #
     # @param [String, Hash, Calabash::Query] query A query describing the view
     #   to pinch.
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def pinch_out(query, duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
-      Calabash::Internal.with_default_device {|device| device.pinch(:out, query, options)}
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pinch_in(query, options={})
+      Device.default.pinch(:in, query, options)
     end
 
-    # Performs a **pinch** inwards inside the first view match by `query`.
+    # Performs a **pinch** outwards on the screen.
     #
-    # The gestures will be similar to two fingers pressing down in the opposite
-    # corners of the view  and simultaneously moving towards the center of the
-    # view.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
     #
-    # @example
-    #  # We have a webview that we want to pinch in on
-    #
-    #  cal.pinch_in("* id:'webView'")
-    #
-    #         Application
-    #  ┌───────────────────────┐
-    #  │───────────────────────│
-    #  │      id: webview      │
-    #  │  ┌─────────────────┐  │
-    #  │  │  *              │  │
-    #  │  │   \             │  │
-    #  │  │    \            │  │
-    #  │  │     v    ^      │  │
-    #  │  │           \     │  │
-    #  │  │            \    │  │
-    #  │  │             *   │  │
-    #  │  └─────────────────┘  │
-    #  └───────────────────────┘
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pinch_screen_out(options={})
+      _pinch_screen(:out, options)
+    end
+
+    # Performs a **pinch** inwards on the screen.
     #
-    # @example
-    #  # We have a MapView rendering a map. We want to zoom it in.
-    #  # On iOS, we should pinch out to zoom in
-    #  # On Android, we should pinch in to zoom in.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
     #
-    #  if cal.android?
-    #    cal.pinch_in({class: "MapView"})
-    #  elsif cal.ios?
-    #    cal.pinch_out({class: "MapView"})
-    #  end
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pinch_screen_in(options={})
+      _pinch_screen(:in, options)
+    end
+
+    # Performs a **pinch** to zoom out.
     #
     # @param [String, Hash, Calabash::Query] query A query describing the view
     #   to pinch.
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def pinch_in(query, duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
-
-      Calabash::Internal.with_default_device {|device| device.pinch(:in, query, options)}
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pinch_to_zoom_out(query, options={})
+      _pinch_to_zoom(:out, query, options)
     end
 
-    # Performs a **pinch** outwards on the screen.
+    # Performs a **pinch** to zoom in.
     #
-    # @see #pinch_out
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #   to pinch.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
     #
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def pinch_screen_out(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pinch_to_zoom_in(query, options={})
+      _pinch_to_zoom(:in, query, options)
+    end
 
-      _pinch_screen(:out, options)
+    # Performs a **pinch** on the screen to zoom in.
+    #
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pinch_screen_to_zoom_in(options={})
+      _pinch_screen_to_zoom(:in, options)
     end
 
-    # Performs a **pinch** inwards on the screen.
+    # Performs a **pinch** on the screen to zoom out.
     #
-    # @see #pinch_in
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
     #
-    # @param [Number] duration (default: 1.0) The amount of time in seconds the
-    #  gesture lasts.
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
-    def pinch_screen_in(duration: nil)
-      options = {
-          duration: duration || DEFAULT_PAN_OPTIONS[:duration]
-      }
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
+    def pinch_screen_to_zoom_out(options={})
+      _pinch_screen_to_zoom(:out, options)
+    end
 
-      _pinch_screen(:in, options)
+    # @!visibility private
+    def _pan_screen_up(options={})
+      abstract_method!
     end
 
     # @!visibility private
-    define_method(:_pan_screen_up) do |options={}|
-      abstract_method!(:_pan_screen_up)
+    def _pan_screen_down(options={})
+      abstract_method!
     end
 
     # @!visibility private
-    define_method(:_pan_screen_down) do |options={}|
-      abstract_method!(:_pan_screen_down)
+    def _flick_screen_up(options={})
+      abstract_method!
     end
 
     # @!visibility private
-    define_method(:_flick_screen_up) do |options={}|
-      abstract_method!(:_flick_screen_up)
+    def _flick_screen_down(options={})
+      abstract_method!
     end
 
     # @!visibility private
-    define_method(:_flick_screen_down) do |options={}|
-      abstract_method!(:_flick_screen_down)
+    def _pinch_screen(direction, options={})
+      abstract_method!
     end
 
     # @!visibility private
-    DEFAULT_PAN_OPTIONS = {duration: 1}
+    def _pinch_to_zoom(direction, query, options={})
+      abstract_method!
+    end
+
+    # @!visibility private
+    def _pinch_screen_to_zoom(direction, options={})
+      abstract_method!
+    end
   end
 end