calabash 1.2.1 → 1.9.9.pre1

data/lib/calabash/environment.rb

@@ -0,0 +1,75 @@
+module Calabash
+
+  # A representation of the Calabash environment.
+  # @todo Need ENVIRONMENT.md file.
+  class Environment
+    # Utility method to retrieve an environment variable.
+    #
+    # @param [String] name of the environment variable
+    # @return Value of the environment variable
+    def self.variable(name)
+      ENV[name]
+    end
+
+    # Utility method to set the value of an environment variable.
+    #
+    # @param [String] name of the environment variable
+    # @param [Object] value of the environment variable
+    def self.set_variable!(name, value)
+      Logger.debug("Setting environment variable '#{name}' to '#{value}'")
+      ENV[name] = value
+    end
+
+    # Are we running in the Xamarin Test Cloud?
+    #
+    # @return [Boolean] Returns true if cucumber is running in the test cloud.
+    def self.xamarin_test_cloud?
+      variable('XAMARIN_TEST_CLOUD') == '1'
+    end
+
+    # Is Calabash running in debug mode. True if $CAL_DEBUG is '1'
+    DEBUG = variable('CAL_DEBUG') == '1'
+
+    # The path of the default app under test. This value is used if no app is
+    # given from the command line. e.g. $ calabash run.
+    #
+    # @todo On iOS, a great deal of effort is spent trying to deduce the
+    # application path for simulators.  This needs to be reproduced here
+    # (somehow).  Or maybe not?  The console requires the app path to perform
+    # commands.  Maybe cucumber should too?  See the todo in the
+    # Calabash::IOS::Application for more details.
+    APP_PATH = variable('CAL_APP')
+
+    # The time in seconds to wait by default before failing in the methods of
+    # {Calabash::Wait}. Defaults to 30. Notice that this value is only the
+    # **default** for {Calabash::Wait} and that the actual default wait timeout
+    # can be changed at any time during the test.
+    WAIT_TIMEOUT = (variable('CAL_WAIT_TIMEOUT') &&
+        variable('CAL_WAIT_TIMEOUT').to_i) || 15
+
+    # The directory to save screenshots in. The directory can be absolute or
+    # relative. Defaults to 'screenshots'.
+    SCREENSHOT_DIRECTORY = variable('CAL_SCREENSHOT_DIR') || 'screenshots'
+
+    # The irbrc file to load when starting a console
+    IRBRC = (variable('CAL_IRBRC') || (File.exist?('.irbrc') && File.expand_path('.irbrc')) || nil)
+
+    # The Android test server path
+    TEST_SERVER_PATH = variable('CAL_TEST_SERVER')
+
+    # The default device identifier.
+    #
+    # To change this value, set the `CAL_DEVICE_ID` environment variable.
+    #
+    # On iOS, this value can be any of the following:
+    # * "iPhone 5s (8.3 Simulator)"
+    # * "EE598265-CAB4-4F6A-96B1-3FA11693325B"   # A simulator UDID.
+    # * 893688959205dc7eb47d603c558ede919ad8dd0f # A physical device UDID.
+    # * "Tom's iPhone" or "saturn"               # The name of a physical device.
+    # * my-special-simulator                     # The name of a configured simulator.
+    DEVICE_IDENTIFIER = variable('CAL_DEVICE_ID')
+
+    # @!visibility private
+    SKELETON_DIR_PATH = File.join(File.dirname(__FILE__), 'lib', 'skeleton')
+  end
+end

data/lib/calabash/gestures.rb

@@ -0,0 +1,384 @@
+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.
+  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│
+    #      |    │                 4                   │
+    #      |    │                                     │
+    #   200 px  │                 1                   │
+    #      |    │                                     │
+    #      |    │             7     5                 │   6
+    #      |    │                                     │
+    #      ┴    └─────────────────────────────────────┘
+    #
+    #   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'", offset: {y: -40})
+    #   5. tap("* marked:'email'", offset: {x: 20, y: 40})
+    #   6. tap("* marked:'email'", at: {x: 100, y: 75}, offset: {x: 80})
+    #   7. tap("* marked:'email'", at: {x: 50, y: 100},
+    #                              offset: {x: -80, y: -40})
+    #
+    # @param [String] 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. This translation is always
+    #   applied before any `:offset`.
+    # @option options [Hash] :offset ({x: 0, y: 0}) Offset to touch point.
+    #   Offset supports an `:x` and `:y` key and causes the touch to be
+    #   offset with `(x,y)`.  This offset is always applied _after_ any
+    #   translation performed by `:at`.
+    # @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
+    # @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 [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`.
+    #
+    # @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] 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`.
+    #
+    # @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_left
+    def pan_screen_left(options={})
+      pan_left('*', options)
+    end
+
+    # Performs a `pan` heading `right` on the screen.
+    # @see pan_right
+    def pan_screen_right(options={})
+      pan_right('*', options)
+    end
+
+    # Performs a `pan` heading `up` on the screen.
+    # @see pan_up
+    def pan_screen_up(options={})
+      _pan_screen_up(options)
+    end
+
+    # Performs a `pan` heading `down` on the screen.
+    # @see pan_down
+    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.
+    # @options 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_left
+    def flick_screen_left(options={})
+      flick_left('*', options)
+    end
+
+    # Performs a `flick` heading `right` on the screen.
+    # @see flick_right
+    def flick_screen_right(options={})
+      flick_right('*', options)
+    end
+
+    # Performs a `flick` heading `up` on the screen.
+    # @see flick_up
+    def flick_screen_up(options={})
+      _flick_screen_up(options)
+    end
+
+    # Performs a `flick` heading `down` on the screen.
+    # @see flick_down
+    def flick_screen_down(options={})
+      _flick_screen_down(options)
+    end
+
+    # Performs a `pinch` outwards.
+    def pinch_out(query, options={})
+      Device.default.pinch(:out, query, options)
+    end
+
+    # Performs a `pinch` inwards.
+    def pinch_in(query, options={})
+      Device.default.pinch(:in, query, options)
+    end
+
+    # Performs a `pinch` outwards on the screen.
+    def pinch_screen_out(options={})
+      _pinch_screen(:out, options)
+    end
+
+    # Performs a `pinch` inwards on the screen.
+    def pinch_screen_in(options={})
+      _pinch_screen(:in, options)
+    end
+
+    # Performs a `pinch` to zoom out.
+    def pinch_to_zoom_out(query, options={})
+      _pinch_to_zoom(:out, query, options)
+    end
+
+    # Performs a `pinch` to zoom in.
+    def pinch_to_zoom_in(query, options={})
+      _pinch_to_zoom(:in, query, options)
+    end
+
+    # Performs a `pinch` to zoom in on the screen.
+    def pinch_screen_to_zoom_in(options={})
+      _pinch_screen_to_zoom(:in, options)
+    end
+
+    # Performs a `pinch` to zoom in on the screen.
+    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