calabash-cucumber 0.10.0.pre1 → 0.10.0.pre2

data/lib/calabash-cucumber/status_bar_helpers.rb

@@ -2,10 +2,32 @@ require 'calabash-cucumber/utils/logging'
 
 module Calabash
   module Cucumber
-    module StatusBarHelpers #=> Map
+
+    # Contains methods for interacting with the status bar.
+    module StatusBarHelpers
 
       include Calabash::Cucumber::Logging
 
+      # Returns the device orientation as reported by `[[UIDevice currentDevice] orientation]`.
+      #
+      # @note This method is not used internally by the gem.  It is provided
+      #  as an alternative to `status_bar_orientation`.  We recommend that you
+      #  use `status_bar_orientation` whenever possible.
+      #
+      # @note Devices that are lying on a flat surface will report their
+      #  orientation as 'face up' or 'face down'.  In order to translate
+      #  gestures based on orientation, Calabash must have left, right, up, or
+      #  down orientation. To that end, if a device is lying flat, this method
+      #  will ***force*** a down orientation.  This will happen regardless of
+      #  the value of the `force_down` optional argument.
+      #
+      # @see #status_bar_orientation
+      # @see Calabash::Cucumber::RotationHelpers#rotate_home_button_to
+      #
+      # @param [Boolean] force_down if true, do rotations until a down
+      #  orientation is achieved
+      # @return [Symbol] Returns the device orientation as one of
+      #  `{:down, :up, :left, :right}`.
       def device_orientation(force_down=false)
         res = map(nil, :orientation, :device).first
 
@@ -25,17 +47,32 @@ module Calabash
         rotate_home_button_to(:down)
       end
 
+      # Returns the home button position relative to the status bar.
+      #
+      # @note You should always prefer to use this method over
+      #  `device_orientation`.
+      #
+      # @note This method works even if a status bar is not visible.
+      #
+      # @return [String] Returns the device orientation as one of
+      #  `{'down' | 'up' | 'left' | 'right'}`.
       def status_bar_orientation
         map(nil, :orientation, :status_bar).first
       end
 
-      # returns +true+ if orientation is portrait
+      # Is the device in the portrait orientation?
+      #
+      # @return [Boolean] Returns true if the device is in the 'up' or 'down'
+      #  orientation.
       def portrait?
         o = status_bar_orientation
         o.eql?('up') or o.eql?('down')
       end
 
-      # returns +true+ if orientation is landscape
+      # Is the device in the landscape orientation?
+      #
+      # @return [Boolean] Returns true if the device is in the 'left' or 'right'
+      #  orientation.
       def landscape?
         o = status_bar_orientation
         o.eql?('right') or o.eql?('left')

data/lib/calabash-cucumber/tests_helpers.rb

@@ -2,55 +2,78 @@ require 'calabash-cucumber/failure_helpers'
 
 module Calabash
   module Cucumber
-    module TestsHelpers #=> http
-      include Calabash::Cucumber::FailureHelpers
-
-      def navigation_path(*args)
 
-        #navigation_path(
-        #    [:a , 2],
-        #    [""],
-        #)
+    # A collection of methods to help you write tests.
+    module TestsHelpers
 
+      include Calabash::Cucumber::FailureHelpers
 
-      end
-
-      def query_map(uiquery,prop, *args)
-        query(uiquery,*args).map {|o| o[prop.to_s]}
-      end
-
+      # Returns the classes of all views matching `uiquery`
+      # @param {String} uiquery the query to execute
+      # @param {Array} args optional args to pass to `query`.
+      # @return {Array<String>} class names of views matching `uiquery`
       def classes(uiquery,*args)
         query_map(uiquery,:class,*args)
       end
 
+      # Returns true if no element matches query `uiquery`.
+      # @param {String} uiquery the query to execute
+      # @return {Boolean} `true` if no element matches query `uiquery`. `false` otherwise.
       def element_does_not_exist(uiquery)
         query(uiquery).empty?
       end
 
+      # Returns true if at least one element matches query `uiquery`.
+      # @param {String} uiquery the query to execute
+      # @return {Boolean} `true` if at least one element matches query `uiquery`. `false` otherwise.
       def element_exists(uiquery)
         not element_does_not_exist(uiquery)
       end
 
+      # Returns true if at least one element matches query `"* marked:'#{expected_mark}'"`
+      # @param {String} expected_mark the mark to search for
+      # @return {Boolean} `true` if at least one element matches query
+      #  `"* marked:'#{expected_mark}'". `false` otherwise.
       def view_with_mark_exists(expected_mark)
         element_exists("view marked:'#{expected_mark}'")
       end
 
+      # raises a Runtime error (and generates a screenshot) unless at least one element matches query `query`.
+      # @param {String} query the query to execute
+      # @return {nil} Returns nil if there is a match.
+      # @raise [RuntimeError] if no element matches `query`.
       def check_element_exists(query)
         if not element_exists(query)
           screenshot_and_raise "No element found for query: #{query}"
         end
       end
 
+      # raises a Runtime error (and generates a screenshot) if at least one element matches query `query`.
+      # @param {String} query the query to execute
+      # @return {nil} Returns nil if there is no match.
+      # @raise [RuntimeError] if an element matches `query`.
       def check_element_does_not_exist(query)
         if element_exists(query)
           screenshot_and_raise "Expected no elements to match query: #{query}"
         end
       end
 
+      # raises a Runtime error (and generates a screenshot) unless at least one element matches mark `expected_mark`.
+      # @param {String} expected_mark the mark to check for.
+      # @return {nil} Returns nil if there is a match.
+      # @raise [RuntimeError] if no element matches `view marked:'#{expected_mark}'`.
       def check_view_with_mark_exists(expected_mark)
         check_element_exists("view marked:'#{expected_mark}'")
       end
 
+      # Calls given block with each row and section (`yield(row, sec)`). Alternates between scrolling to each cell and
+      # yielding.
+      #
+      # @param {Hash} opts specifies details of the scroll
+      # @option opts {String} :query ('tableView') query specifying which table view to use
+      # @option opts {Numeric} :post_scroll (0.3) wait to be done after each scroll
+      # @option opts {Boolean} :animated (true) animate or not
+      #
       def each_cell(opts={:query => "tableView", :post_scroll => 0.3, :animate => true}, &block)
         uiquery = opts[:query] || "tableView"
         skip = opts[:skip_if]
@@ -68,6 +91,7 @@ module Calabash
         end
       end
 
+      # @!visibility private
       def each_cell_and_back(opts={:query => "tableView",
                                    :post_scroll => 0.3,
                                    :post_back => 0.5,
@@ -92,6 +116,11 @@ module Calabash
         end
       end
 
+      # @!visibility private
+      def query_map(uiquery,prop, *args)
+        query(uiquery,*args).map {|o| o[prop.to_s]}
+      end
+
     end
   end
 end

data/lib/calabash-cucumber/uia.rb

@@ -6,10 +6,16 @@ require 'calabash-cucumber/utils/logging'
 
 module Calabash
   module Cucumber
+    # Low-level module for interacting directly with UIA
+    # See also {https://developer.apple.com/library/ios/documentation/ToolsLanguages/Reference/UIAElementClassReference/UIAElement/UIAElement.html}
+    # Typically used to interact with System or remote views.
     module UIA
 
       include Calabash::Cucumber::Logging
 
+      # executes raw JavaScript in the UIAutomation environment (using `eval`).
+      # @param {String} command the JavaScript snipplet to execute
+      # @return {Object} the result returned by the UIA process
       def uia(command,options={})
         res = http({:method => :post, :path => 'uia'}, {:command => command}.merge(options))
         res = JSON.parse(res)
@@ -19,119 +25,195 @@ module Calabash
         res['results'].first
       end
 
+      # @!visibility private
       def uia_wait_tap(query, options={})
         res = http({:method => :post, :path => 'uia-tap'}, {:query => query}.merge(options))
         res = JSON.parse(res)
         if res['outcome'] != 'SUCCESS'
           raise "uia-tap action failed because: #{res['reason']}\n#{res['details']}"
         end
-        res['results'].first
+        res['results']
       end
 
+      # Invoke a Calabash query inside the UIAutomation Calabash engine
+      # Note that this traverses the UIA (accessibility) hierarchy.
+      # @example uia query equivalent of "button marked:'Hello'"
+      #   uia_query :button, marked:'Hello'
+      # @param {Array} queryparts array of segments in the query, e.g., `:button, {marked:'Hello'}`
+      # @return {Array<Hash>} UIAElements matching the query in serialized form.
       def uia_query(*queryparts)
         #TODO escape '\n etc in query
         uia_handle_command(:query, queryparts)
       end
 
+      # @!visibility private
       def uia_query_el(*queryparts)
         #TODO escape '\n etc in query
         uia_handle_command(:queryEl, queryparts)
       end
 
+      # Invoke a Calabash query inside the UIAutomation Calabash engine - includes all UIAWindows.
+      # Note that this traverses the UIA (accessibility) hierarchy.
+      # @example uia query equivalent of "button marked:'Hello'"
+      #   uia_query_windows :button
+      # @param {Array} queryparts array of segments in the query, e.g., `:button, {marked:'Hello'}`
+      # @return {Array<Hash>} UIAElements matching the query in serialized form.
       def uia_query_windows(*queryparts)
         #TODO escape '\n etc in query
         uia_handle_command(:queryWindows, queryparts)
       end
 
+      # Invoke a Calabash query inside the UIAutomation Calabash engine - includes all UIAWindows.
+      # Note that this traverses the UIA (accessibility) hierarchy.
+      # @example uia equivalent of `identifier "button"`
+      #   uia_names :button
+      #   # returns
+      #   [
+      #     "Browse",
+      #     "UINavigationBarBackIndicatorDefault.png",
+      #     "16h",
+      #     "reader postaction comment blue",
+      #     "16h",
+      #     "52",
+      #     "17h",
+      #     "10",
+      #     "Reader",
+      #     "Notifications",
+      #     "Me",
+      #     "New Post"
+      #   ]
+      # @param {Array} queryparts array of segments in the query, e.g., `:button, {marked:'Hello'}`
+      # @return {Array<String>} "names" (accessibilityIdentifier) of UIAElements matching the query.
       def uia_names(*queryparts)
         #TODO escape '\n etc in query
         uia_handle_command(:names, queryparts)
       end
 
+      # Advanced method used to invoke UIAutomation JavaScript methods on objects found via Calabash queries
+      # @see #uia_query
+      # @example Calling UIAButton.isVisible() - {https://developer.apple.com/library/ios/documentation/ToolsLanguages/Reference/UIAElementClassReference/UIAElement/UIAElement.html}
+      #   uia_call [:button, {marked:'New Post'}], :isVisible
+      # @example Advanced example that chains calls and uses arguments
+      #   uia_call [:view, marked:'New Post'], {withName:"New Post"}, :toString, {charAt:0}
+      #
+      # @param {Array} args_arr array describing the query, e.g., `[:button, {marked:'foo'}]`
+      # @param {Array} opts optional arguments specifying a chained sequence of method calls (see example)
+      def uia_call(args_arr, *opts)
+        uia_call_method(:queryEl, args_arr, *opts)
+      end
+
+      # Similar to `uia_call` but searches all windows
+      # @see #uia_call
+      def uia_call_windows(args_arr, *opts)
+        uia_call_method(:queryElWindows, args_arr, *opts)
+      end
+
+      # @!visibility private
       def uia_tap(*queryparts)
         uia_handle_command(:tap, queryparts)
       end
 
+      # @!visibility private
       def uia_tap_mark(mark)
         uia_handle_command(:tapMark, mark)
       end
 
+      # @!visibility private
       def uia_tap_offset(offset)
         uia_handle_command(:tapOffset, offset)
       end
 
+      # @!visibility private
       def uia_double_tap(*queryparts)
         uia_handle_command(:doubleTap, queryparts)
       end
 
+      # @!visibility private
       def uia_double_tap_mark(mark)
         uia_double_tap(:view, {:marked => mark})
       end
 
+      # @!visibility private
       def uia_double_tap_offset(offset)
         uia_handle_command(:doubleTapOffset, offset)
       end
 
+      # @!visibility private
       def uia_two_finger_tap(*queryparts)
         uia_handle_command(:twoFingerTap, queryparts)
       end
 
+      # @!visibility private
       def uia_two_finger_tap_offset(offset)
         uia_handle_command(:twoFingerTapOffset, offset)
       end
 
+      # @!visibility private
       def uia_flick_offset(from, to)
         uia_handle_command(:flickOffset, from, to)
       end
 
+      # @!visibility private
       def uia_touch_hold(duration, *queryparts)
         uia_handle_command(:touchHold, duration, queryparts)
       end
 
+      # @!visibility private
       def uia_touch_hold_offset(duration, offset)
         uia_handle_command(:touchHoldOffset, duration, offset)
       end
 
+      # @!visibility private
       def uia_pan(from_q, to_q)
         uia_handle_command(:pan, from_q, to_q)
       end
 
+      # @!visibility private
       def uia_pan_offset(from, to, options)
         uia_handle_command(:panOffset, from, to, options)
       end
 
+      # @!visibility private
       def uia_swipe(*queryparts)
         uia_handle_command(:swipe, queryparts)
       end
 
+      # @!visibility private
       def uia_swipe_offset(offset, options)
         uia_handle_command(:swipeOffset, offset, options)
       end
 
+      # @!visibility private
       def uia_pinch(*queryparts)
         uia_handle_command(:pinch, queryparts)
       end
 
+      # @!visibility private
       def uia_pinch_offset(in_or_out, offset, duration)
         uia_handle_command(:pinchOffset, in_or_out, offset, duration)
       end
 
+      # @!visibility private
       def uia_scroll_to(*queryparts)
         uia_handle_command(:scrollTo, queryparts)
       end
 
+      # @!visibility private
       def uia_element_exists?(*queryparts)
         uia_handle_command(:elementExists, queryparts)
       end
 
+      # @!visibility private
       def uia_element_does_not_exist?(*queryparts)
         uia_handle_command(:elementDoesNotExist, queryparts)
       end
 
+      # @!visibility private
       def uia_screenshot(name)
         uia_handle_command(:screenshot, name)
       end
 
+      # @!visibility private
       def uia_type_string(string, opt_text_before='', escape=true)
         if escape && string.index(/\\/)
           indexes = string.enum_for(:scan,/\\/).map { Regexp.last_match.begin(0) }
@@ -146,10 +228,12 @@ module Calabash
         status
       end
 
+      # @!visibility private
       def uia_enter
         uia_handle_command(:enter)
       end
 
+      # @!visibility private
       def uia_set_location(options)
         validate_hash_is_location!(options)
         if options[:place]
@@ -164,18 +248,12 @@ module Calabash
         uia_handle_command(:setLocation, loc_data)
       end
 
+      # @!visibility private
       def uia_send_app_to_background(secs)
         uia_handle_command(:deactivate, secs)
       end
 
-      def uia_call(args_arr, *opts)
-        uia_call_method(:queryEl, args_arr, *opts)
-      end
-
-      def uia_call_windows(args_arr, *opts)
-        uia_call_method(:queryElWindows, args_arr, *opts)
-      end
-
+      # @!visibility private
       def uia_call_method(cmd, args_arr, *opts)
         if opts.empty?
           return uia_handle_command(cmd, args_arr)
@@ -213,6 +291,7 @@ module Calabash
 
       end
 
+      # @!visibility private
       def uia_handle_command(cmd, *query_args)
         command = uia_serialize_command(cmd, *query_args)
         if debug_logging?
@@ -223,17 +302,20 @@ module Calabash
         uia_result(s)
       end
 
+      # @!visibility private
       def uia_serialize_command(cmd, *query_args)
         args = uia_serialize_arguments(query_args)
         %Q[uia.#{cmd}(#{args.join(', ')})]
       end
 
+      # @!visibility private
       def uia_serialize_arguments(args)
         args.map do |part|
           uia_serialize_argument(part)
         end
       end
 
+      # @!visibility private
       def uia_serialize_argument(part)
         if part.is_a?(String)
           "'#{escape_uia_string(part)}'"
@@ -242,6 +324,7 @@ module Calabash
         end
       end
 
+      # @!visibility private
       def escape_uia_string(string)
         #TODO escape '\n in query
         escape_quotes string
@@ -249,6 +332,7 @@ module Calabash
 
       # <b>DEPRECATED:</b> Use <tt>uia("...javascript..", options)</tt> instead.
       # deprecated because the method signature is poor
+      # @!visibility private
       def send_uia_command(opts ={})
 
         # TODO formally deprecate send_uia_command with _deprecated function