calabash 2.0.0.pre2 → 2.0.0.pre3

data/lib/calabash/ios/conditions.rb

@@ -1,5 +1,8 @@
 module Calabash
   module IOS
+
+    # Methods for waiting for things to happen on iOS, like animations to
+    # complete.
     module Conditions
 
       # Waits for all elements to stop animating.

data/lib/calabash/ios/date_picker.rb

@@ -0,0 +1,412 @@
+require 'date'
+
+module Calabash
+  module IOS
+
+    # A collection of methods for interacting with UIDatePicker.
+    module DatePicker
+
+      # The API has been tested in various time zones and tested
+      # once while crossing the international date line (on a boat).
+      # With that said, the API makes some assumptions about locales
+      # and time zones.  It is possible to customize the ruby date
+      # format and Objective-C date format to get the behavior you
+      # need.  You will need to monkey patch the following methods:
+      #
+      #  * date_picker_ruby_date_format
+      #  * date_picker_objc_date_format
+      #
+      # Before going down this path, we recommend that you ask for
+      # advice on the Calabash support channels.
+
+      # @!visibility private
+      # Provided for monkey patching, but not part of the public API.
+      def date_picker_ruby_date_format
+        RUBY_DATE_AND_TIME_FMT
+      end
+
+      # @!visibility private
+      # Provided for monkey patching, but not part of the public API.
+      def date_picker_objc_date_format
+        OBJC_DATE_AND_TIME_FMT
+      end
+
+      # @!visibility private
+      # Returns the picker mode of the first UIDatePicker match by `query`.
+      #
+      # @see #time_mode?
+      # @see #date_mode?
+      # @see #date_and_time_mode?
+      # @see #countdown_mode?
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      # @return [String] Returns the picker mode which will be one of
+      #  `{'0', '1', '2', '3'}`
+      # @raise [RuntimeError] If no picker can be found.
+      # @raise [RuntimeError] If an unknown mode is returned.
+      # @raise [RuntimeError] If first view matched by query does not responde
+      #   to 'datePickerMode'.
+      def date_picker_mode(query)
+        Query.ensure_valid_query(query)
+
+        message = "Timed out waiting for picker with #{query}"
+        mode = nil
+
+        wait_for(message) do
+          result = query(query, :datePickerMode)
+          if result.empty?
+            false
+          else
+            mode = result.first
+            if [0, 1, 2, 3].include?(mode)
+              mode
+            else
+              if mode == '*****'
+                raise RuntimeError,
+                  "Query #{query} matched a view that does not respond 'datePickerMode'"
+              else
+                raise RuntimeError,
+                  "Query #{query} returned an unknown mode '#{mode}' for 'datePickerMode'"
+              end
+            end
+          end
+        end
+      end
+
+      # Is the date picker in time mode?
+      #
+      # @see #time_mode?
+      # @see #date_mode?
+      # @see #date_and_time_mode?
+      # @see #countdown_mode?
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      #
+      # @return [Boolean] True if the picker is in time mode.
+      #
+      # @raise [RuntimeError] If no picker can be found.
+      # @raise [RuntimeError] If an unknown mode is returned.
+      # @raise [RuntimeError] If first view matched by query does not responde
+      #   to 'datePickerMode'.
+      def time_mode?(query)
+        date_picker_mode(query) == UI_DATE_PICKER_MODE_TIME
+      end
+
+      # Is the date picker in date mode?
+      #
+      # @see #time_mode?
+      # @see #date_mode?
+      # @see #date_and_time_mode?
+      # @see #countdown_mode?
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      #
+      # @return [Boolean] True if the picker is in date mode.
+      #
+      # @raise [RuntimeError] If no picker can be found.
+      # @raise [RuntimeError] If an unknown mode is returned.
+      # @raise [RuntimeError] If first view matched by query does not responde
+      #   to 'datePickerMode'.
+      def date_mode?(query)
+        date_picker_mode(query) == UI_DATE_PICKER_MODE_DATE
+      end
+
+      # Is the date picker in date and time mode?
+      #
+      # @see #time_mode?
+      # @see #date_mode?
+      # @see #date_and_time_mode?
+      # @see #countdown_mode?
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      #
+      # @return [Boolean] True if the picker is in date and time mode.
+      #
+      # @raise [RuntimeError] If no picker can be found.
+      # @raise [RuntimeError] If an unknown mode is returned.
+      # @raise [RuntimeError] If first view matched by query does not responde
+      #   to 'datePickerMode'.
+      def date_and_time_mode?(query)
+        date_picker_mode(query) == UI_DATE_PICKER_MODE_DATE_AND_TIME
+      end
+
+      # Is the date picker in countdown mode?
+      #
+      # @see #time_mode?
+      # @see #date_mode?
+      # @see #date_and_time_mode?
+      # @see #countdown_mode?
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      #
+      # @return [Boolean] True if the picker is in countdown mode.
+      #
+      # @raise [RuntimeError] If no picker can be found.
+      # @raise [RuntimeError] If an unknown mode is returned.
+      # @raise [RuntimeError] If first view matched by query does not responde
+      #   to 'datePickerMode'.
+      def countdown_mode?(query)
+        date_picker_mode(query) == UI_DATE_PICKER_MODE_COUNT_DOWN_TIMER
+      end
+
+      # The maximum date for a picker.  If there is no maximum date, this
+      # method returns nil.
+      #
+      # @note
+      #  From the Apple docs:
+      #  `The property is an NSDate object or nil (the default)`.
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      #
+      # @return [DateTime] The maximum date on the picker or nil if no maximum
+      #  exists
+      #
+      # @raise [RuntimeError] If the picker is in countdown mode.
+      # @raise [RuntimeError] If no picker can be found.
+      # @raise [RuntimeError] If the date returned by the server cannot be
+      #   converted to a DateTime object.
+      def maximum_date_time_from_picker(query)
+        Query.ensure_valid_query(query)
+
+        wait_for_view(query)
+
+        if countdown_mode?(query)
+          fail('Countdown pickers do not have a maximum date.')
+        end
+
+        result = query(query, :maximumDate)
+
+        if result.empty?
+          fail("Expected '#{query}' to return a visible UIDatePicker")
+        else
+          if result.first.nil?
+            nil
+          else
+            date_str = result.first
+            begin
+              date_time = DateTime.parse(date_str)
+            rescue TypeError, ArgumentError => _
+              raise RuntimeError,
+                "Could not convert string '#{date_str}' into a valid DateTime object"
+            end
+            date_time
+          end
+        end
+      end
+
+      # The minimum date for a picker.  If there is no minimum date, this
+      # method returns nil.
+      #
+      # @note
+      #  From the Apple docs:
+      #  `The property is an NSDate object or nil (the default)`.
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      #
+      # @return [DateTime] The minimum date on the picker or nil if no minimum
+      #  exists
+      #
+      # @raise [RuntimeError] If the picker is in countdown mode.
+      # @raise [RuntimeError] If no picker can be found.
+      # @raise [RuntimeError] If the date returned by the server cannot be
+      #   converted to a DateTime object.
+      def minimum_date_time_from_picker(query)
+        Query.ensure_valid_query(query)
+
+        wait_for_view(query)
+
+        if countdown_mode?(query)
+          fail('Countdown pickers do not have a minimum date.')
+        end
+
+        result = query(query, :minimumDate)
+
+        if result.empty?
+          fail("Expected '#{query}' to return a visible UIDatePicker")
+        else
+          if result.first.nil?
+            nil
+          else
+            date_str = result.first
+            begin
+              date_time = DateTime.parse(date_str)
+            rescue TypeError, ArgumentError => _
+              raise RuntimeError,
+                "Could not convert string '#{date_str}' into a valid DateTime object"
+            end
+            date_time
+          end
+        end
+      end
+
+      # Returns the date and time from the picker as DateTime object.
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      #
+      # @return [DateTime] The date on the picker
+      #
+      # @raise [RuntimeError] If the picker is in countdown mode.
+      # @raise [RuntimeError] If no picker can be found.
+      # @raise [RuntimeError] If the date returned by the server cannot be
+      #   converted to a DateTime object.
+      def date_time_from_picker(query)
+        Query.ensure_valid_query(query)
+
+        wait_for_view(query)
+
+        if countdown_mode?(query)
+          fail('This method is available for pickers in countdown mode.')
+        end
+
+        result = query(query, :date)
+
+        if result.empty?
+          fail("Expected '#{query}' to return a visible UIDatePicker")
+        else
+          if result.first.nil?
+            nil
+          else
+            date_str = result.first
+            date_time = DateTime.parse(date_str)
+            if date_time.nil?
+              raise RuntimeError,
+                "Could not convert string '#{date_str}' into a valid DateTime object"
+            end
+            date_time
+          end
+        end
+      end
+
+      # Sets the date and time on the _first_ UIDatePicker matched by
+      # `query`.
+      #
+      # This method is not valid for UIDatePickers in _countdown_ mode.
+      #
+      # @param [DateTime] date_time The date and time you want to change to.
+      #
+      # @raise [RuntimeError] If `query` does match exactly one picker.
+      # @raise [RuntimeError] If `query` matches a picker in countdown mode.
+      # @raise [RuntimeError] If the target date is greater than the picker's
+      #  maximum date.
+      # @raise [RuntimeError] If the target date is less than the picker's
+      #  minimum date
+      # @raise [ArgumentError] If the target date is not a DateTime instance.
+      def picker_set_date_time(date_time)
+        picker_set_date_time_in("UIDatePicker index:0", date_time)
+      end
+
+      # Sets the date and time on the _first_ UIDatePicker matched by
+      # `query`.
+      #
+      # This method is not valid for UIDatePickers in _countdown_ mode.
+      #
+      # An error will be raised if more than on view is matched by `query`.
+      #
+      # To avoid matching more than one UIPickerView or subclass:
+      #  * Make the query more specific:    "UIPickerView marked:'alarm'"
+      #  * Use the index language feature:  "UIPickerView index:0"
+      #  * Query by custom class:           "view:'MyPickerView'"
+      #
+      # @param [String, Hash, Calabash::Query] query A query that can be used
+      #   to find UIDatePickers.
+      # @param [DateTime] date_time The date and time you want to change to.
+      #
+      # @raise [RuntimeError] If `query` does match exactly one picker.
+      # @raise [RuntimeError] If `query` matches a picker in countdown mode.
+      # @raise [RuntimeError] If the target date is greater than the picker's
+      #  maximum date.
+      # @raise [RuntimeError] If the target date is less than the picker's
+      #  minimum date
+      # @raise [ArgumentError] If the target date is not a DateTime instance.
+      def picker_set_date_time_in(query, date_time)
+        unless date_time.is_a?(DateTime)
+          raise ArgumentError,
+            "Date time argument '#{date_time}' must be a DateTime but found '#{date_time.class}'"
+        end
+
+        Query.ensure_valid_query(query)
+
+        message = "Timed out waiting for UIDatePicker with '#{query}'"
+
+        wait_for(message) do
+          result = query(query)
+          if result.length > 1
+            fail("Query '#{query}' matched more than on UIDatePicker")
+          else
+            !result.empty?
+          end
+        end
+
+        if countdown_mode?(query)
+          message =
+            [
+              "Query '#{query}' matched a picker in countdown mode.",
+              'Setting the date or time on a countdown picker is not supported'
+            ].join("\n")
+          fail(message)
+        end
+
+        minimum_date = minimum_date_time_from_picker(query)
+        if !minimum_date.nil? && minimum_date > date_time
+          message = [
+            "Cannot set the date on the picker matched by '#{query}'",
+            "Picker minimum date:  '#{minimum_date}'",
+            "  Date to change to:  '#{date_time}'",
+            "Target date comes before the minimum date."].join("\n")
+          fail(message)
+        end
+
+        maximum_date = maximum_date_time_from_picker(query)
+        if !maximum_date.nil? && maximum_date < date_time
+          message = [
+            "Cannot set the date on the picker matched by '#{query}'",
+            "Picker maximum date:  '#{maximum_date}'",
+            "  Date to change to:  '#{date_time}'",
+            "Target date comes after the maximum date."].join("\n")
+          fail(message)
+        end
+
+        ruby_format = date_picker_ruby_date_format
+        objc_format = date_picker_objc_date_format
+        target_date_string = date_time.strftime(ruby_format).squeeze(' ').strip
+
+        Device.default.map_route(query,
+                                 :changeDatePickerDate,
+                                 target_date_string,
+                                 objc_format,
+                                 # notify targets
+                                 true,
+                                 # animate
+                                 true)
+      end
+
+      private
+
+      # @!visibility private
+      OBJC_DATE_AND_TIME_FMT = 'yyyy_MM_dd_HH_mm'
+
+      # @!visibility private
+      RUBY_DATE_AND_TIME_FMT = '%Y_%m_%d_%H_%M'
+
+      # UIDatePicker modes
+
+      # @!visibility private
+      UI_DATE_PICKER_MODE_TIME = 0
+      # @!visibility private
+      UI_DATE_PICKER_MODE_DATE = 1
+      # @!visibility private
+      UI_DATE_PICKER_MODE_DATE_AND_TIME = 2
+      # @!visibility private
+      UI_DATE_PICKER_MODE_COUNT_DOWN_TIMER = 3
+    end
+  end
+end
+

data/lib/calabash/ios/defaults.rb

@@ -1,5 +1,6 @@
 module Calabash
   module IOS
+    # Runtime defaults for iOS.
     module Defaults
       # Sets up the default application based on the
       # environment, and the default device based on the default application

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

@@ -19,7 +19,7 @@ module Calabash
       include Calabash::IOS::UIAKeyboardMixin
       include Calabash::IOS::TextMixin
       include Calabash::IOS::UIAMixin
-
+      include Calabash::IOS::IPadMixin
       include Calabash::IOS::GesturesMixin
 
       attr_reader :run_loop
@@ -339,6 +339,10 @@ module Calabash
         else
           raise "Invalid application #{application} for iOS platform."
         end
+
+        # @todo Get the language code from the server!
+        ensure_ipad_emulation_1x
+
         {
            :device => self,
            :application => application,

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

@@ -0,0 +1,253 @@
+module Calabash
+  module IOS
+    # @!visibility private
+    # Contains methods for interacting with the iPad.
+    module IPadMixin
+
+      # @!visibility private
+      # Provides methods to interact with the 1x and 2x buttons that appear
+      # when an iPhone-only app is emulated on an iPad.  Calabash cannot
+      # interact with these apps in 2x mode because the touch coordinates
+      # cannot be reliably translated from normal iPhone dimensions to the
+      # emulated dimensions.
+      #
+      # On iOS < 7, an app _remembered_ its last 1x/2x scale so when it
+      # reopened the previous scale would be the same as when it closed.  This
+      # meant you could manually set the scale once to 1x and never have to
+      # interact with the scale button again.
+      #
+      # On iOS > 7, the default behavior is that all emulated apps open at 2x
+      # regardless of their previous scale.
+      #
+      # @note In order to use this class, you must allow Calabash to launch
+      #  your app with instruments.
+      class Emulation
+
+        # @!visibility private
+        #
+        # Maintainers:  when adding a localization, please notice that
+        # the keys and values are semantically reversed.
+        #
+        # you should read the hash as:
+        #
+        # ```
+        # :emulated_1x <= what button is showing when the app is emulated at 2X?
+        # :emulated_2x <= what button is showing when the app is emulated at 1X?
+        # ```
+        #
+        # @todo Once we have localizations wired up, we can use these keys
+        #
+        # These pull requests describe how to find a key/value pairs from the
+        # on-disk accessibility bundles for _keyboards_ but we can use the same
+        # strategy to look up the Zoom button localizations.
+        #
+        # * https://github.com/calabash/run_loop/pull/197
+        # * https://github.com/calabash/calabash-ios-server/pull/221
+        #
+        #
+        #  fullscreen.zoom => 2x => 'Switch to full screen mode'
+        #  normal.zoom => 1x => 'Switch to normal mode'
+        #
+        #  # We will still need query windows.
+        #  uia("UIATarget.localTarget().frontMostApp().windows()[2].elements()[0].label()")
+        IPAD_1X_2X_BUTTON_LABELS = {
+              :en => {:emulated_1x => '2X',
+                      :emulated_2x => '1X'}
+        }
+
+        # @!visibility private
+        # @!attribute [r] scale
+        # The current 1X or 2X scale represented as a Symbol.
+        #
+        # @return [Symbol] Returns this emulation's scale.  Will be one of
+        # `{:emulated_1x | :emulated_2x}`.
+        attr_reader :scale
+
+        # @!visibility private
+        # @!attribute [r] lang_code
+        # The Apple compatible language code for determining the accessibility
+        # label of the 1X and 2X buttons.
+        #
+        # @return [Symbol] Returns the language code of this emulation.
+        attr_reader :lang_code
+
+        # @!visibility private
+        # @!attribute [r] device
+        # A handle on the default device.
+        attr_reader :device
+
+        # @!visibility private
+        # A private instance variable for storing this emulation's 1X/2X button
+        # names.  The value will be set at runtime based on the language code
+        # that is passed the initializer.
+        @button_names_hash = nil
+
+        # @!visibility private
+        # Creates a new Emulation.
+        # @param [Symbol] lang_code an Apple compatible language code
+        # @return [Emulation] Returns an emulation that is ready for action!
+        def initialize (device, lang_code=:en)
+          @button_names_hash = IPAD_1X_2X_BUTTON_LABELS[lang_code]
+          if @button_names_hash.nil?
+            raise "could not find 1X/2X buttons for language code '#{lang_code}'"
+          end
+
+          @device = device
+          @lang_code = lang_code
+          @scale = _internal_ipad_emulation_scale
+        end
+
+        # @!visibility private
+        def tap_ipad_scale_button
+          key = @scale
+          name = @button_names_hash[key]
+
+          query_args =
+          [
+               [
+                 :view, {:marked => "#{name}"}
+               ]
+          ]
+
+          device.uia_query_then_make_javascript_calls(:queryElWindows, query_args, :tap)
+        end
+
+        private
+
+        # @!visibility private
+        def _internal_ipad_emulation_scale
+          hash = @button_names_hash
+          val = nil
+          hash.values.each do |button_name|
+            query_args =
+                  [
+                        :view, {:marked => button_name}
+                  ]
+
+            button_exists = device.uia_serialize_and_call(:queryElWindows,
+                                                          query_args)
+            if button_exists
+              result = device.uia_query_then_make_javascript_calls(:queryElWindows,
+                                                                   [query_args],
+                                                                   :name)
+              if result == button_name
+                val = button_name
+                break
+              end
+            end
+          end
+
+          if val.nil?
+            raise "Could not find iPad scale button with '#{hash.values}'"
+          end
+
+          if val == hash[:emulated_1x]
+            :emulated_1x
+          elsif val == hash[:emulated_2x]
+            :emulated_2x
+          else
+            raise "Unrecognized emulation scale '#{val}'"
+          end
+        end
+      end
+
+      # @!visibility private
+      # Ensures that iPhone apps emulated on an iPad are displayed at scale.
+      #
+      # @note It is recommended that clients call this `ensure_ipad_emulation_1x`
+      #  instead of this method.
+      #
+      # @note If this is not an iPhone app emulated on an iPad, then calling
+      #  this method has no effect.
+      #
+      # @note In order to use this method, you must allow Calabash to launch
+      #  your app with instruments.
+      #
+      # Starting in iOS 7, iPhone apps emulated on the iPad always launch at 2x.
+      # calabash cannot currently interact with such apps in 2x mode (trust us,
+      # we've tried).
+      #
+      # @see #ensure_ipad_emulation_1x
+      #
+      # @param [Symbol] scale the desired scale - must be `:emulated_1x` or
+      #  `:emulated_2x`
+      #
+      # @param [Hash] opts optional arguments to control the interaction with
+      #  the 1X/2X buttons
+      #
+      # @option opts [Symbol] :lang_code (:en) an Apple compatible
+      #  language code
+      # @option opts [Symbol] :wait_after_touch (0.4) how long to
+      #  wait _after_ the scale button is touched
+      #
+      # @return [void]
+      #
+      # @raise [RuntimeError] If the app was not launched with instruments.
+      # @raise [RuntimeError] If an invalid `scale` is passed.
+      # @raise [RuntimeError] If an unknown language code is passed.
+      # @raise [RuntimeError] If the scale button cannot be touched.
+      def ensure_ipad_emulation_scale(scale, opts={})
+        return unless iphone_app_emulated_on_ipad?
+
+        allowed = [:emulated_1x, :emulated_2x]
+        unless allowed.include?(scale)
+          raise "Scale '#{scale}' is not one of '#{allowed}' allowed args"
+        end
+
+        default_opts = {:lang_code => :en,
+                        :wait_after_touch => 0.4}
+        merged_opts = default_opts.merge(opts)
+
+        obj = Emulation.new(self, merged_opts[:lang_code])
+
+        actual_scale = obj.scale
+
+        if actual_scale != scale
+          obj.tap_ipad_scale_button
+        end
+
+        sleep(merged_opts[:wait_after_touch])
+      end
+
+      # @!visibility private
+      # Ensures that iPhone apps emulated on an iPad are displayed at `1X`.
+      #
+      # @note If this is not an iPhone app emulated on an iPad, then calling
+      #  this method has no effect.
+      #
+      # @note In order to use this method, you must allow Calabash to launch
+      #  your app with instruments.
+      #
+      # Starting in iOS 7, iPhone apps emulated on the iPad always launch at 2x.
+      # calabash cannot currently interact with such apps in 2x mode (trust us,
+      # we've tried).
+      #
+      # @param [Hash] opts optional arguments to control the interaction with
+      #  the 1X/2X buttons
+      #
+      # @option opts [Symbol] :lang_code (:en) an Apple compatible
+      #  language code
+      # @option opts [Symbol] :wait_after_touch (0.4) how long to
+      #  wait _after_ the scale button is touched
+      #
+      # @return [void]
+      #
+      # @raise [RuntimeError] If the app was not launched with instruments.
+      # @raise [RuntimeError] If an unknown language code is passed.
+      # @raise [RuntimeError] If the scale button cannot be touched.
+      def ensure_ipad_emulation_1x(opts={})
+        ensure_ipad_emulation_scale(:emulated_1x, opts)
+      end
+
+      private
+      # @!visibility private
+      # Ensures iPhone apps running on an iPad are emulated at 2X
+      #
+      # You should never need to call this function - Calabash cannot interact
+      # with iPhone apps emulated on the iPad in 2x mode.
+      def _ensure_ipad_emulation_2x(opts={})
+        ensure_ipad_emulation_scale(:emulated_2x, opts)
+      end
+    end
+  end
+end