calabash 1.2.1 → 1.9.9.pre1

data/lib/calabash/ios/scroll.rb

@@ -0,0 +1,504 @@
+module Calabash
+  module IOS
+
+    # Scrolling gestures for UIScrollView, UITableView, MKMapView, UIWebView,
+    # WKWebView, and UICollectionView.
+    #
+    # Starting iOS, Apple's official UIAutomation API has been broken on the
+    # iOS Simulators for these methods:
+    #
+    #  * dragInsideWithOptions
+    #  * flickInsideWithOptions
+    #
+    # The result is that gestures like swipe and flick do not work on
+    # iOS Simulators.
+    #
+    # Calabash iOS implements several scrolling methods that allow you to work
+    # around these bugs.
+    #
+    # @see Calabash::Gestures#pan
+    # @see Calabash::Gestures#flick
+    module Scroll
+
+      # Scrolls the first view matching `query` in `direction`.
+      #
+      # View are scrolled half of their frame size.
+      #
+      # If `query` matches a view that is not a  UIScrollView or a subclass, an
+      # error will be raised. UITableView, MKMapView, UIWebView, WKWebView, and
+      # UICollectionView are all examples of subclasses of UIScrollView.
+      #
+      # An error will be raised if more than on view is matched by `query`.
+      #
+      # To avoid matching more than one UIScrollView (or subclass):
+      #  * Make the query more specific: "UITableView marked:'table'"
+      #  * Use the index language feature:  "UIScrollView index:0"
+      #
+      # @example
+      #   scroll("UITableView", :down)
+      #
+      # @note This is implemented by calling the Objective-C
+      #  `setContentOffset:animated:` method and can do things users cannot.
+      #
+      # This is the only alternative for `pan` and `flick` which do not work
+      # on iOS Simulators starting with iOS 7.
+      #
+      # @see Calabash::Gestures#pan
+      # @see Calabash::Gestures#flick
+      #
+      # @param [String,Query,Hash] query A query describing the view to scroll.
+      # @param [Symbol] direction The direction to scroll. Valid directions are:
+      #   'up', 'down', 'left', and 'right'
+      #
+      # @raise [ArgumentError] If direction is invalid.
+      # @raise [ArgumentError] If query is invalid.
+      # @raise [ViewNotFoundError] If query matches no views.
+      # @raise [RuntimeError] If query matches more than one view.
+      # @raise [RuntimeError] If query matches a view that is not a UIScrollView.
+      def scroll(query, direction)
+        allowed_directions = [:up, :down, :left, :right]
+        dir_symbol = direction.to_sym
+        unless allowed_directions.include?(dir_symbol)
+          raise ArgumentError,
+                "Expected '#{direction}' to be one of #{allowed_directions.join(',')}"
+        end
+
+        Query.ensure_valid_query(query)
+
+        begin
+          view_to_scroll = _wait_for_exactly_one_scroll_view(query)
+        rescue RuntimeError => e
+          raise RuntimeError, e
+        end
+
+        results = Device.default.map_route(query, :scroll, direction)
+
+        if results.first.nil?
+          fail("Expected '#{query}' to match a UIScrollView or a subclass")
+        end
+
+        Calabash::QueryResult.create([view_to_scroll], query)
+      end
+
+      # Scroll the UITableView matching `query` to `row` in `section`.
+      #
+      # If `query` matches a view that is not a UITableView or a subclass, an
+      # error will be raised.
+      #
+      # An error will be raised if more than on view is matched by `query`.
+      #
+      # To avoid matching more than one UITableView (or subclass):
+      #  * Make the query more specific:  "UITableView marked:'table'"
+      #  * Use the index language feature:  "UITableView index:1"
+      #
+      # Row and section are zero indexed.  The first row is row 0.
+      #
+      # @example
+      #  # Scroll to the 5th row in the first section.
+      #  > scroll_to_row("UITableView", 5)
+      #
+      #  # Scroll to the 3rd row, in the 5th section
+      #  > scroll_to_row("UITableView", 3, 5)
+      #
+      # @note This is implement by calling the Objective-C
+      #  `scrollToRowAtIndexPath:atScrollPosition:animated:` method and can do
+      #   things that users cannot.
+      #
+      # This is the only alternative for `pan` and `flick` which do not work
+      # on iOS Simulators starting with iOS 7.
+      #
+      # @see Calabash::Gestures#pan
+      # @see Calabash::Gestures#flick
+      #
+      # @param [String,Query,Hash] query A query describing the table to scroll.
+      # @param [Numeric] row The row number to scroll to.
+      # @param [Numeric] section The section number to scroll to.
+      # @param [Hash] options Options to control the scroll behavior.
+      # @option options [Symbol] :scroll_position (:middle) The final position
+      #  of the row in the view.  Can be :top, :middle, :bottom
+      # @option options [Boolean] :animate (true)  Should the scrolling be
+      #  animated?
+      #
+      # @raise [ArgumentError] If the :scroll_position is invalid.
+      # @raise [ArgumentError] If the :animate key is not a Boolean.
+      # @raise [ArgumentError] If query is invalid.
+      # @raise [ViewNotFoundError] If query matches no views.
+      # @raise [RuntimeError] If query matches more than one view.
+      # @raise [RuntimeError] If query matches a view that is not a UITableView.
+      # @raise [RuntimeError] If the row and section are invalid for the table.
+      def scroll_to_row(query, row, section=0, **options)
+        default_options = {
+          :scroll_position => :middle,
+          :animate => true
+        }
+
+        merged_options = default_options.merge(options)
+
+        begin
+          _expect_valid_scroll_options(VALID_TABLE_SCROLL_POSITIONS, merged_options)
+        rescue ArgumentError => e
+          raise ArgumentError, e
+        end
+
+        Query.ensure_valid_query(query)
+
+        begin
+          view_to_scroll = _wait_for_exactly_one_scroll_view(query)
+        rescue RuntimeError => e
+          raise RuntimeError, e
+        end
+
+        position = merged_options[:scroll_position].to_sym
+        animate = merged_options[:animate]
+
+        results = Device.default.map_route(query, :scrollToRow, row.to_i,
+                                          section.to_i, position, animate)
+
+        if results.first.nil?
+          message = [
+                "Could not scroll table to row '#{row}' and section '#{section}'.",
+                "Either query '#{query}' did not match a UITableView or",
+                "the row '#{row}' in section '#{section}' does not exist."
+          ].join("\n")
+          fail(message)
+        end
+
+        Calabash::QueryResult.create([view_to_scroll], query)
+      end
+
+      # Scroll the UITableView matching `query` to the row with `mark`.  This
+      # method is particularly useful when testing tables with dynamic content.
+      #
+      # An error will be raised If `query` matches a view that is not a
+      # UITableView or a subclass.
+      #
+      # To avoid matching more than one UITableView (or subclass):
+      #  * Make the query more specific:  "UITableView marked:'table'"
+      #  * Use the index language feature:  "UITableView index:1"
+      #
+      # The `mark` can be on any subview in a UITableViewCell or the cell
+      # itself.  If no cell with `mark` can be found, an error will be raised.
+      #
+      # @example
+      #  > scroll_to_row_with_mark("UITableView", "apples")
+      #
+      # @note This is implement by calling the Objective-C
+      #  `scrollToRowAtIndexPath:atScrollPosition:animated:` method and can do
+      #   things that users cannot.  The implementation generates a new cell
+      #   for every index path in your table.  This can cause performance
+      #   issues if your table is very large.
+      #
+      # This is the only alternative for `pan` and `flick` which do not work
+      # on iOS Simulators starting with iOS 7.
+      #
+      # @see Calabash::Gestures#pan
+      # @see Calabash::Gestures#flick
+      #
+      # @param [String,Query,Hash] query A query describing the table to scroll.
+      # @param [String] mark The cell identifier.
+      # @param [Hash] options Options to control the scroll behavior.
+      # @option options [Symbol] :scroll_position (:middle) The final position
+      #  of the row in the view.  Can be :top, :middle, :bottom
+      # @option options [Boolean] :animate (true)  Should the scrolling be
+      #  animated?
+      #
+      # @raise [ArgumentError] If mark is nil or the empty string.
+      # @raise [ArgumentError] If the :scroll_position is invalid.
+      # @raise [ArgumentError] If the :animate key is not a Boolean.
+      # @raise [ArgumentError] If query is invalid.
+      # @raise [ViewNotFoundError] If query matches no views.
+      # @raise [RuntimeError] If query matches more than one view.
+      # @raise [RuntimeError] If query matches a view that is not a UITableView.
+      # @raise [RuntimeError] If no cell with `mark` is found.
+      def scroll_to_row_with_mark(query, mark, options={})
+        default_options = {
+              :scroll_position => :middle,
+              :animate => true
+        }
+
+        merged_options = default_options.merge(options)
+
+        begin
+          _expect_valid_scroll_options(VALID_TABLE_SCROLL_POSITIONS, merged_options)
+          _expect_valid_scroll_mark(mark)
+        rescue ArgumentError => e
+          raise ArgumentError, e
+        end
+
+        Query.ensure_valid_query(query)
+
+        begin
+          view_to_scroll = _wait_for_exactly_one_scroll_view(query)
+        rescue RuntimeError => e
+          raise RuntimeError e
+        end
+
+        position = merged_options[:scroll_position].to_sym
+        animate = merged_options[:animate]
+
+        results = Device.default.map_route(query, :scrollToRowWithMark, mark,
+                                          position, animate)
+
+        if results.first.nil?
+          message = [
+                "Could not scroll table to row with mark: '#{mark}'",
+                "Either the '#{query}' did not match a UITableView or",
+                "there is no cell with mark '#{mark}'."
+          ].join("\n")
+          fail(message)
+        end
+
+        Calabash::QueryResult.create([view_to_scroll], query)
+      end
+
+      # Scrolls the UICollectionView matching `query` to `item` in `section`.
+      #
+      # If `query` matches a view that is not a UICollectionView or a subclass,
+      # an error will be raised.
+      #
+      # An error will be raised if more than on view is matched by `query`.
+      #
+      # To avoid matching more than one UICollectionView (or subclass):
+      #  * Make the query more specific:  "UICollectionView marked:'gallery'"
+      #  * Use the index language feature:  "UICollectionView index:1"
+      #
+      #
+      # Item and section are zero indexed.  The first item is 0.
+      #
+      # @example
+      #  # Scroll to the 5th item in the first section.
+      #  > scroll_to_item("UICollectionView", 5)
+      #
+      #  # Scroll to the 3rd row, in the 5th section
+      #  > scroll_to_item("UICollectionView", 3, 5)
+      #
+      # @example The following are the allowed :scroll_position values.
+      #  :top, :center_vertical, :bottom, :left, :center_horizontal, :right
+      #
+      # @note This is implement by calling the Objective-C
+      #  `scrollToItemAtIndexPath:atScrollPosition:animated:` method and can do
+      #   things that users cannot.
+      #
+      # This is the only alternative for `pan` and `flick` which do not work
+      # on iOS Simulators starting with iOS 7.
+      #
+      # @see Calabash::Gestures#pan
+      # @see Calabash::Gestures#flick
+      #
+      # @param [String,Query,Hash] query A query describing the table to scroll.
+      # @param [Numeric] item The item number to scroll to.
+      # @param [Numeric] section The section number to scroll to.
+      # @param [Hash] options Options to control the scroll behavior.
+      # @option options [Symbol] :scroll_position (:top) The final position
+      #  of the row in the view.  See the examples for valid positions.
+      # @option options [Boolean] :animate (true)  Should the scrolling be
+      #  animated?
+      #
+      # @raise [ArgumentError] If the :scroll_position is invalid.
+      # @raise [ArgumentError] If the :animate key is not a Boolean.
+      # @raise [ArgumentError] If query is invalid.
+      # @raise [ViewNotFoundError] If query matches no views.
+      # @raise [RuntimeError] If query matches more than one view.
+      # @raise [RuntimeError] If query matches a view that is not a
+      #   UICollectionView.
+      # @raise [RuntimeError] If the item and section are not valid for
+      #   the collection.
+      def scroll_to_item(query, item, section=0, **options)
+        default_options = {
+              :scroll_position => :top,
+              :animate => true
+        }
+
+        merged_options = default_options.merge(options)
+
+        begin
+          _expect_valid_scroll_options(VALID_COLLECTION_SCROLL_POSITIONS, merged_options)
+        rescue ArgumentError => e
+          raise ArgumentError, e
+        end
+
+        Query.ensure_valid_query(query)
+
+        begin
+          view_to_scroll = _wait_for_exactly_one_scroll_view(query)
+        rescue RuntimeError => e
+          raise RuntimeError e
+        end
+
+        position = merged_options[:scroll_position].to_sym
+        animate = merged_options[:animate]
+
+        results = Device.default.map_route(query, :collectionViewScroll,
+                                           item.to_i, section.to_i,
+                                           position, animate)
+        if results.first.nil?
+          message = [
+                "Could not scroll collection to item '#{item}' and section '#{section}'.",
+                "Either query '#{query}' did not match a UICollectionView or",
+                "the item '#{item}' in section '#{section}' does not exist."
+          ].join("\n")
+          fail(message)
+        end
+
+        Calabash::QueryResult.create([view_to_scroll], query)
+      end
+
+      # Scroll the UICollectionView matching `query` to the row with `mark`.
+      # This method is particularly useful when testing collections with dynamic
+      # content.
+      #
+      # An error will be raised If `query` matches a view that is not a
+      # UICollectionView or a subclass.
+      #
+      # To avoid matching more than one UICollectionView (or subclass):
+      #  * Make the query more specific:  "UICollectionView marked:'gallery'"
+      #  * Use the index language feature:  "UICollectionView index:1"
+      #
+      # The `mark` can be on any subview in a UICollectionViewCell or the cell
+      # itself.  If no cell with `mark` can be found, an error will be raised.
+      #
+      # @example
+      #  > scroll_to_item_with_mark("UICollectionView", "mom")
+      #
+      # @example The following are the allowed :scroll_position values.
+      #  :top, :center_vertical, :bottom, :left, :center_horizontal, :right
+      #
+      # @note This is implement by calling the Objective-C
+      #  `scrollToRowAtIndexPath:atScrollPosition:animated:` method and can do
+      #   things that users cannot.  The implementation generates a new item
+      #   for every index path in your collection.  This can cause performance
+      #   issues if your collection is very large.
+      #
+      # This is the only alternative for `pan` and `flick` which do not work
+      # on iOS Simulators starting with iOS 7.
+      #
+      # @see Calabash::Gestures#pan
+      # @see Calabash::Gestures#flick
+      #
+      # @param [String,Query,Hash] query A query describing the collection to
+      #   scroll.
+      # @param [String] mark The cell identifier.
+      # @param [Hash] options Options to control the scroll behavior.
+      # @option options [Symbol] :scroll_position (:top) The final position
+      #  of the row in the view.  See the examples for valid positions.
+      # @option options [Boolean] :animate (true)  Should the scrolling be
+      #  animated?
+      #
+      # @raise [ArgumentError] If mark is nil or the empty string.
+      # @raise [ArgumentError] If the :scroll_position is invalid.
+      # @raise [ArgumentError] If the :animate key is not a Boolean.
+      # @raise [ArgumentError] If query is invalid.
+      # @raise [ViewNotFoundError] If query matches no views.
+      # @raise [RuntimeError] If query matches more than one view.
+      # @raise [RuntimeError] If query matches a view that is not a
+      #   UICollectionView.
+      # @raise [RuntimeError] If no item with `mark` is found.
+      def scroll_to_item_with_mark(query, mark, options={})
+        default_options = {
+              :scroll_position => :top,
+              :animate => true,
+        }
+
+        merged_options = default_options.merge(options)
+
+        begin
+          _expect_valid_scroll_options(VALID_COLLECTION_SCROLL_POSITIONS, merged_options)
+          _expect_valid_scroll_mark(mark)
+        rescue ArgumentError => e
+          raise ArgumentError, e
+        end
+
+        Query.ensure_valid_query(query)
+
+        begin
+          view_to_scroll = _wait_for_exactly_one_scroll_view(query)
+        rescue RuntimeError => e
+          raise RuntimeError e
+        end
+
+        position = merged_options[:scroll_position].to_sym
+        animate = merged_options[:animate]
+
+        results = Device.default.map_route(query,
+                                           :collectionViewScrollToItemWithMark,
+                                           mark, position, animate)
+
+        if results.first.nil?
+          message = [
+                "Could not scroll collection to item with mark: '#{mark}'",
+                "Either the '#{query}' did not match a UICollectionView or",
+                "there is no item with mark '#{mark}'."
+          ].join("\n")
+          fail(message)
+        end
+
+        Calabash::QueryResult.create([view_to_scroll], query)
+      end
+
+      private
+
+      # !@visibility private
+      VALID_TABLE_SCROLL_POSITIONS = [:top, :middle, :bottom]
+
+      # !@visibility private
+      VALID_COLLECTION_SCROLL_POSITIONS = [:top, :center_vertical, :bottom,
+                                           :left, :center_horizontal, :right]
+
+      # !@visibility private
+      def _wait_for_exactly_one_scroll_view(query)
+
+        results = []
+
+        found_none = "Expected '#{query}' to match exactly one view, but found no matches."
+        query_object = Query.new(query)
+        wait_for(found_none) do
+          results = query(query_object)
+          if results.length > 1
+            message = [
+                  "Expected '#{query}' to match exactly one view, but found '#{results.length}'",
+                  results.join("\n")
+            ].join("\n")
+            fail(message)
+          else
+            results.length == 1
+          end
+        end
+        results.first
+      end
+
+      # !@visibility private
+      def _expect_valid_scroll_positions(valid_positions, position)
+        unless valid_positions.include?(position.to_sym)
+          raise ArgumentError,
+                "Expected '#{position}' to be one of #{valid_positions.join(', ')}"
+        end
+      end
+
+      # !@visibility private
+      def _expect_valid_scroll_animate(animate)
+        unless [true, false].include?(animate)
+          raise ArgumentError,
+                "Expected '#{animate}' to be a Boolean true or false"
+        end
+      end
+
+      # !@visibility private
+      def _expect_valid_scroll_options(valid_positions, options)
+        _expect_valid_scroll_positions(valid_positions, options[:scroll_position])
+        _expect_valid_scroll_animate(options[:animate])
+      end
+
+      # !@visibility private
+      def _expect_valid_scroll_mark(mark)
+        if mark.nil? || mark == ''
+          raise ArgumentError,
+                if mark.nil?
+                  'Mark cannot be nil.'
+                else
+                  'Mark cannot be an empty string.'
+                end
+        end
+      end
+    end
+  end
+end