calabash 1.9.9.pre3 → 2.0.0.pre1

data/lib/calabash/gestures.rb

@@ -1,16 +1,20 @@
 module Calabash
-  # Methods for performing gestures.  Gestures are taps, flicks,
-  # and pans.
+  # 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`.
+    # Performs a **tap** on the first view that matches `query`.
     #
     # Taps the center of the view by default.
     #
@@ -19,33 +23,25 @@ module Calabash
     #
     #      ┬    ┌─────────────────────────────────────┐
     #      |    │2                                   3│
-    #      |    │                 4                   │
+    #      |    │                                     │
     #      |    │                                     │
     #   200 px  │                 1                   │
     #      |    │                                     │
-    #      |    │             7     5                 │   6
     #      |    │                                     │
+    #      |    │                 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'", 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})
+    #   4. tap("* marked:'email'", at:  {x: 50, y: 100})
     #
-    # @param [String] query A query describing the view to 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. 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`.
+    #   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={})
@@ -54,8 +50,17 @@ module Calabash
       Device.default.tap(Query.new(query), options)
     end
 
-    # Performs a `double_tap` on the (first) view that matches `query`.
-    # @see tap
+    # 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={})
@@ -64,12 +69,14 @@ module Calabash
       Device.default.double_tap(Query.new(query), options)
     end
 
-    # Performs a `long_press` on the (first) view that matches `query`.
+    # 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
+    # @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.
@@ -82,11 +89,14 @@ module Calabash
       Device.default.long_press(Query.new(query), options)
     end
 
-    # Performs a `pan` on 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`.
     #
+    # 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.
@@ -112,7 +122,8 @@ module Calabash
     # @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 [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
@@ -132,9 +143,11 @@ module Calabash
       Device.default.pan(Query.new(query), from, to, options)
     end
 
-    # Performs a `pan` from the center of the first view that matches
+    # 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'")`
@@ -171,56 +184,64 @@ module Calabash
       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
+    # 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
+    # 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
+    # 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
+    # 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
+    # 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_right
+    # 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_up
+    # 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_down
+    # 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`.
+    # 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.
@@ -257,91 +278,163 @@ module Calabash
       Device.default.flick(Query.new(query), from, to, options)
     end
 
-    # Performs a `flick` heading `left` on the (first) view that matches `query`.
-    # @see flick
+    # 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
+    # Performs a **flick** heading _right_ on the first view that matches
     # `query`.
-    # @see flick
+    # @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
+    # 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
+    # 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
+    # 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_right
+    # 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_up
+    # 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_down
+    # Performs a **flick** heading _down_ on the screen.
+    # @see #flick
     def flick_screen_down(options={})
       _flick_screen_down(options)
     end
 
-    # Performs a `pinch` outwards.
+    # 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.
+    # 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.
+    # 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.
+    # 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.
+    # 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.
+    # 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` to zoom in on the screen.
+    # 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` to zoom in on the screen.
+    # 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

data/lib/calabash/http/retriable_client.rb

@@ -107,7 +107,7 @@ module Calabash
         interval = options.fetch(:interval, @interval)
         header = options.fetch(:header, HEADER)
 
-        @logger.log "Getting: #{@server.endpoint + request.route}"
+        @logger.log "Getting: #{@server.endpoint + request.route} #{options}"
 
         start_time = Time.now
         last_error = nil

data/lib/calabash/interactions.rb

@@ -1,12 +1,74 @@
 module Calabash
-  # @!visibility private
   module Interactions
-    # @todo Needs docs!
+    # Queries the view hierarchy to find all views matching `query`.
+    # Optionally query takes a variable number of “invocation” arguments
+    # (args below).
+    # If called with an empty list of *args, query will find the views
+    # specified by `query` and return a QueryResult of serialized views.
+    #
+    # @note If this method is called with invocation arguments, it might allow
+    #  the author of the test to do an interaction with app that a user would
+    #  not be able to (for example changing the text of a view).
+    #
+    # @example
+    #  query("* marked:'my view'")
+    #  query("* id:'foo' descendant UIButton")
+    #  query("android.widget.ProgressBar")
+    #  query("* {text CONTAINS 'something'}")
+    #  query("* {y > 200}")
+    #
+    # @example
+    #  # Find all the elements, visible as well as invisible
+    #  query("all *")
+    #
+    # @example
+    #  query("editText", :setText => 'my text')
+    #  query("scrollView", :scrollBy => [50, 10])
+    #
+    # @example
+    #  irb(main):009:0> query("UITabBarButton index:0")
+    #  [
+    #      [0] {
+    #      "class" => "UITabBarButton",
+    #      "id" => nil,
+    #      "rect" => {
+    #          "center_x" => 40,
+    #          "y" => 520,
+    #          "width" => 76,
+    #          "x" => 2,
+    #          "center_y" => 544,
+    #          "height" => 48
+    #      },
+    #      "frame" => {
+    #          "y" => 1,
+    #          "width" => 76,
+    #          "x" => 2,
+    #          "height" => 48
+    #      },
+    #      "label" => "Reader",
+    #      "description" => "<UITabBarButton: 0xdabb510; frame = (2 1; 76 48); opaque = NO; layer = <CALayer: 0xdabd8e0>>"
+    #  }
+    #  ]
+    #
+    # @note Even if the query matches only one view, the QueryResult returned
+    #  is still a list of elements.
+    #
+    # @param [String, Hash, Calabash::Query] query The query to match the
+    #  view(s)
+    #
+    # @param args Optional var-args list describing a chain of method
+    #  names (selectors).
+    #
+    # @return [Calabash::QueryResult] A result of the query
     def query(query, *args)
       Calabash::Device.default.map_route(Query.new(query), :query, *args)
     end
 
-    # @todo Needs docs!
+    # Flashes any views matching `query`. Only one view is flashed at a time,
+    # in the order they are returned.
+    #
+    # @param [String, Hash, Calabash::Query] query The query to match the
+    #  view(s)
     def flash(query)
       Calabash::Device.default.map_route(Query.new(query), :flash)
     end
@@ -18,7 +80,7 @@ module Calabash
     #  # iOS
     #  evaluate_javascript_in("UIWebView", "2+2")
     #  # Android
-    #  evaluate_javascript_in("WebView", "return 2+2"
+    #  evaluate_javascript_in("WebView", "return 2+2")
     #
     # @example
     #  # iOS
@@ -79,7 +141,7 @@ module Calabash
     #
     # @example
     #   # iOS
-    #   backdoor('calabashBackdoor:'', '')
+    #   backdoor('calabashBackdoor:', '')
     #
     # @example
     #   # iOS

data/lib/calabash/ios/conditions.rb

@@ -1,6 +1,5 @@
 module Calabash
   module IOS
-    # @!visibility private
     module Conditions
 
       # Waits for all elements to stop animating.

data/lib/calabash/ios/device/device_implementation.rb

@@ -22,8 +22,6 @@ module Calabash
 
       include Calabash::IOS::GesturesMixin
 
-      # @todo Should these be public?
-      # @todo If public, document!
       attr_reader :run_loop
       attr_reader :uia_strategy
       attr_reader :start_options
@@ -292,6 +290,13 @@ module Calabash
         runtime_attributes.server_version
       end
 
+      # @!visibility private
+      # A dump of runtime details.
+      def runtime_details
+        expect_runtime_attributes_available(__method__)
+        @runtime_attributes.runtime_info
+      end
+
       # Is this device a simulator?
       # @return [Boolean] Returns true if this device is a simulator.
       def simulator?
@@ -729,11 +734,18 @@ module Calabash
 
       # @!visibility private
       def expect_runtime_attributes_available(method_name)
+
         if runtime_attributes.nil?
-          logger.log("The method '#{method_name}' is not available to IOS::Device until", :info)
-          logger.log('the app has been launched with Calabash start_app.', :info)
-          raise "The method '#{method_name}' can only be called after the app has been launched"
+          begin
+            # Populates the @runtime_attributes
+            wait_for_server_to_start({:timeout => 1.0})
+          rescue Calabash::Device::EnsureTestServerReadyTimeoutError => _
+            logger.log("The method '#{method_name}' is not available to IOS::Device until", :info)
+            logger.log('the app has been launched with Calabash start_app.', :info)
+            raise "The method '#{method_name}' can only be called after the app has been launched"
+          end
         end
+
         true
       end