module Calabash # Methods for performing gestures. Gestures are taps, flicks, and pans. # # 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 # convenience when working in the console, some gestures return sensible # values. However, these values are subject to change. module Gestures # How long do we wait for a view to appear by default when performing a # gesture. DEFAULT_GESTURE_WAIT_TIMEOUT = 3 # Performs a **tap** on the first view that matches `query`. # # Taps the center of the view by default. # # @example # . ├────────────── 400 px ───────────────┤ # # ┬ ┌─────────────────────────────────────┐ # | │2 3│ # | │ │ # | │ │ # 200 px │ 1 │ # | │ │ # | │ │ # | │ 4 │ # ┴ └─────────────────────────────────────┘ # # 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] 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 `(0,0)` as the reference point. # @raise [ViewNotFoundError] If the `query` returns no results. # @raise [ArgumentError] If `query` is invalid. def tap(query, options={}) Query.ensure_valid_query(query) Device.default.tap(Query.new(query), options) end # Performs a **double_tap** on the first view that matches `query`. # # @see #tap # # @param [String, Hash, Calabash::Query] query A query describing the view # to tap. # @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 `(0,0)` as the reference point. # # @raise [ViewNotFoundError] If the `query` returns no results. # @raise [ArgumentError] If `query` is invalid. def double_tap(query, options={}) Query.ensure_valid_query(query) Device.default.double_tap(Query.new(query), options) end # Performs a **long_press** on the first view that matches `query`. # # On iOS this is often referred to as _touch-and-hold_. On Android this # is known variously as _press_, _long-push_, _press-and-hold_, or _hold_. # # @see #tap # # @param [String] query A query describing the view to tap. # @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. # @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 long_press(query, options={}) Query.ensure_valid_query(query) Device.default.long_press(Query.new(query), options) end # 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`. # # Also known as **scroll** and **swipe**. # # @example # Consider a pan on a scrollable view. When the finger is is released, # the velocity of the view is zero. # # @example # A scrollable view displays the alphabet. Panning left will cause the # view to scroll right. # # Before After # ┌───────────┐ | ┌───────────┐ # │ A B C D E │ | │ E F G H I │ # │ │ | │ │ # │ <───────┤ │ | │ │ # └───────────┘ | └───────────┘ # # 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. # @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 [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. # @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) Device.default.pan(Query.new(query), from, to, options) end # Performs a **pan** from the center of the first view that matches # `query_from` to the center of the first view that matches `query_to`. # # Also known as **drag and drop**. # # @example # Panning between two elements. # `pan_between("* id:'first'", "* id:'second'")` # # # ┌───────────┐ # │ │ # │ ─ │ id: 'first' # │ \ │ # └───────\───┘ # \ # \ # \ # \ # \ # \ # ┌───\───────┐ # │ \ │ # id: 'second' │ x │ # │ │ # └───────────┘ # # @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. # @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) Device.default.pan_between(Query.new(query_from), Query.new(query_to), options) end # Performs a **pan** heading _left_ on the first view that matches `query`. # # @see #pan def pan_left(query, options={}) pan(query, {x: 90, y: 50}, {x: 10, y: 50}, options) end # Performs a **pan** heading _right_ on the first view that matches `query`. # # @see #pan def pan_right(query, options={}) pan(query, {x: 10, y: 50}, {x: 90, y: 50}, options) end # Performs a **pan** heading _up_ on the first view that matches `query`. # # @see #pan def pan_up(query, options={}) pan(query, {x: 50, y: 90}, {x: 50, y: 10}, options) end # Performs a **pan** heading _down_ on the first view that matches `query`. # # @see #pan 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 def pan_screen_left(options={}) pan_left('*', options) end # Performs a **pan** heading _right_ on the screen. # # @see #pan def pan_screen_right(options={}) pan_right('*', options) end # Performs a **pan** heading _up_ on the screen. # # @see #pan def pan_screen_up(options={}) _pan_screen_up(options) end # Performs a **pan** heading _down_ on the screen. # # @see #pan def pan_screen_down(options={}) _pan_screen_down(options) end # 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. # @see pan # # @example # A scrollable view displays the alphabet. Flicking left will cause the # view to scroll right. # # Before After # ┌───────────┐ | ┌───────────┐ # │ A B C D E │ | │F G H I J K│ # │ │ | │ │ # <·····──────┤ │ | │ │ # └───────────┘ | └───────────┘ # # @param [String,Hash,Query] query A query describing the view to flick # 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 [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. # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60. def flick(query, from, to, options={}) Query.ensure_valid_query(query) Device.default.flick(Query.new(query), from, to, options) end # Performs a **flick** heading _left_ on the first view that matches `query`. # @see #flick def flick_left(query, options={}) flick(query, {x: 90, y: 50}, {x: 10, y: 50}, options) end # Performs a **flick** heading _right_ on the first view that matches # `query`. # @see #flick def flick_right(query, options={}) flick(query, {x: 10, y: 50}, {x: 90, y: 50}, options) end # Performs a **flick** heading _up_ on the first view that matches `query`. # @see #flick def flick_up(query, options={}) flick(query, {x: 50, y: 90}, {x: 50, y: 10}, options) end # Performs a **flick** heading _down_ on the first view that matches `query`. # @see #flick 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 def flick_screen_left(options={}) flick_left('*', options) end # Performs a **flick** heading _right_ on the screen. # @see #flick def flick_screen_right(options={}) flick_right('*', options) end # Performs a **flick** heading _up_ on the screen. # @see #flick def flick_screen_up(options={}) _flick_screen_up(options) end # Performs a **flick** heading _down_ on the screen. # @see #flick def flick_screen_down(options={}) _flick_screen_down(options) end # Performs a **pinch** outwards on the first view match by `query`. # # @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. # # @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 [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_in(query, options={}) Device.default.pinch(:in, query, options) end # Performs a **pinch** outwards on the screen. # # @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_out(options={}) _pinch_screen(:out, options) end # Performs a **pinch** inwards on the screen. # # @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_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 [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_to_zoom_out(query, options={}) _pinch_to_zoom(:out, query, options) end # Performs a **pinch** 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. # # @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_to_zoom_in(query, options={}) _pinch_to_zoom(:in, query, options) end # 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** on the screen to zoom out. # # @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_out(options={}) _pinch_screen_to_zoom(:out, options) end # @!visibility private def _pan_screen_up(options={}) abstract_method! end # @!visibility private def _pan_screen_down(options={}) abstract_method! end # @!visibility private def _flick_screen_up(options={}) abstract_method! end # @!visibility private def _flick_screen_down(options={}) abstract_method! end # @!visibility private def _pinch_screen(direction, options={}) abstract_method! end # @!visibility private def _pinch_to_zoom(direction, query, options={}) abstract_method! end # @!visibility private def _pinch_screen_to_zoom(direction, options={}) abstract_method! end end end