calabash-cucumber 0.10.0.pre1 → 0.10.0.pre2

data/lib/calabash-cucumber/date_picker.rb

@@ -2,6 +2,8 @@ require 'date'
 
 module Calabash
   module Cucumber
+
+    # A collection of methods for interacting with UIDatePicker
     module DatePicker
       include Calabash::Cucumber::Core
 
@@ -9,15 +11,38 @@ module Calabash
       # we convert DateTime object to a string
       # and pass the format that objc can use
       # to convert the string into NSDate
+
+      # @!visibility private
       RUBY_DATE_AND_TIME_FMT = '%Y_%m_%d_%H_%M'
+
+      # @!visibility private
       OBJC_DATE_AND_TIME_FMT = 'yyyy_MM_dd_HH_mm'
 
       # picker 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
 
+      # @!visibility private
+      # Returns the picker mode of the UIDatePicker.
+      #
+      # @see #time_mode?
+      # @see #date_mode?
+      # @see #date_and_time_mode?
+      # @see #countdown_mode?
+      #
+      # @param [String] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, then the first UIDatePicker that is
+      #  found will be queried.
+      # @return [String] Returns the picker mode which will be one of
+      #  `{'0', '1', '2', '3'}`
+      # @raise [RuntimeError] if no picker can be found
       def date_picker_mode(picker_id=nil)
         query_str = should_see_date_picker picker_id
         res = query(query_str, :datePickerMode)
@@ -27,28 +52,87 @@ module Calabash
         res.first
       end
 
+      # Is the date picker in time mode?
+      #
+      # @see #time_mode?
+      # @see #date_mode?
+      # @see #date_and_time_mode?
+      # @see #countdown_mode?
+      #
+      # @param [String] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, then the first UIDatePicker that is
+      #  found will be queried.
+      # @return [Boolean] true if the picker is in time mode
+      # @raise [RuntimeError] if no picker can be found
       def time_mode?(picker_id=nil)
         date_picker_mode(picker_id) == 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] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, then the first UIDatePicker that is
+      #  found will be queried.
+      # @return [Boolean] true if the picker is in date mode
+      # @raise [RuntimeError] if no picker can be found
       def date_mode?(picker_id=nil)
         date_picker_mode(picker_id) == 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] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, then the first UIDatePicker that is
+      #  found will be queried.
+      # @return [Boolean] true if the picker is in date and time mode
+      # @raise [RuntimeError] if no picker can be found
       def date_and_time_mode?(picker_id=nil)
         date_picker_mode(picker_id) == 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] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, then the first UIDatePicker that is
+      #  found will be queried.
+      # @return [Boolean] true if the picker is in countdown mode
+      # @raise [RuntimeError] if no picker can be found
       def countdown_mode?(picker_id=nil)
         date_picker_mode(picker_id) == UI_DATE_PICKER_MODE_COUNT_DOWN_TIMER
       end
 
-      # ensuring picker is visible
-
+      # @!visibility private
+      # Returns a query string for a date picker.
+      #
+      # @param [String] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, a query that looks for any UIDatePicker
+      #  will be constructed.
+      # @return [String] a query-ready string for finding a UIDatePicker
       def query_string_for_picker (picker_id = nil)
         picker_id.nil? ? 'datePicker' : "datePicker marked:'#{picker_id}'"
       end
 
+      # Asserts that a date picker is visible.
+      #
+      # @param [String] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, any visible date picker will satisfy the
+      #  assertion.
+      # @raise [RuntimeError] if a matching date picker is not visible
       def should_see_date_picker (picker_id=nil)
         query_str = query_string_for_picker picker_id
         if query(query_str).empty?
@@ -57,10 +141,20 @@ module Calabash
         query_str
       end
 
-
-      # minimum and maximum dates
-      # appledoc ==> The property is an NSDate object or nil (the default),
-      # which means no maximum date.
+      # 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] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, then the first UIDatePicker that is
+      #  found will be queried.
+      # @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 the picker cannot be found
       def maximum_date_time_from_picker (picker_id = nil)
         if countdown_mode? picker_id
           screenshot_and_raise 'method is not available for pickers that are not in date or date time mode'
@@ -75,8 +169,20 @@ module Calabash
         DateTime.parse(res.first)
       end
 
-      # appledoc ==> The property is an NSDate object or nil (the default),
-      # which means no minimum date.
+      # 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] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, then the first UIDatePicker that is
+      #  found will be queried.
+      # @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 the picker cannot be found
       def minimum_date_time_from_picker (picker_id = nil)
         if countdown_mode? picker_id
           screenshot_and_raise 'method is not available for pickers that are not in date or date time mode'
@@ -91,7 +197,14 @@ module Calabash
         DateTime.parse(res.first)
       end
 
-      # date time from picker
+      # Returns the date and time from the picker.
+      #
+      # @param [String] picker_id The accessibility label or id of the picker
+      #  you are looking for.  If nil, then the first UIDatePicker that is
+      #  found will be queried.
+      # @return [DateTime] the date on the picker
+      # @raise [RuntimeError] if the picker is in countdown mode
+      # @raise [RuntimeError] if the picker cannot be found
       def date_time_from_picker (picker_id=nil)
         if countdown_mode? picker_id
           screenshot_and_raise 'method is not available for pickers that are not in date or date time mode'
@@ -104,8 +217,9 @@ module Calabash
         DateTime.parse(res.first)
       end
 
-
-      # changing picker date time
+      # @!visibility private
+      # @todo replace with a `merge` inside the calling function
+      # -1 @jmoody for ruby noob-ness
       def args_for_change_date_on_picker(options)
         args = []
         if options.has_key?(:notify_targets)
@@ -122,27 +236,32 @@ module Calabash
         args
       end
 
-
-      # sets the date and time on picker identified by <tt>options[:picker_id]</tt>
-      # using the DateTime +target_dt+
-      #
-      # valid options are:
+      # Sets the date and time on picker.
       #
-      #        :animate - animate the change - default is +true+
-      #      :picker_id - the id (or mark) of the date picker - default is +nil+ which
-      #                   will target the first visible date picker
-      # :notify_targets - notify all objc targets that the date picker has changed
-      #                   default is +true+
+      # @note
+      #  When `:notify_targets => true` this operation iterates through the
+      #  target/action pairs on the objc `UIDatePicker` instance and calls
+      # `performSelector:<action> object:<target>`.  This has the effect of
+      #  generating `UIEvents`.
       #
-      # when <tt>:notify_targets = true</tt> this operation iterates through the
-      # target/action pairs on the objc +UIDatePicker+ instance and calls
-      # <tt>performSelector:<action> object:<target></tt> to simulate a +UIEvent+
+      # @param [DateTime] target_dt the date and time you want to change to
+      # @param [Hash] options controls the behavior of this method
+      # @option options [Boolean] :animate (true) animate the date change
+      # @option options [String]  :picker_id (nil) The accessibility id or label
+      #  of the date picker you are looking for.  If nil, the first UIDatePicker
+      #  that is found will have the date and time applied.
+      # @option options [Boolean] :notify_target (true) If true, all the date
+      #  picker's target/action pairs will be called.  This is necessary to
+      #  generate UIEvents.  If false, no UIEvents will be generated and it is
+      #  likely that your UI will not update correctly.
       #
-      # raises an error if
-      # * no UIDatePicker can be found
-      # * the target date is greater than the picker's maximum date
-      # * the target date is less than the picker's minimum date
-      # * the target date is not a DateTime object
+      # @raise [RuntimeError] if no date picker can be found
+      # @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 [RuntimeError] if the target date is not a DateTime instance
+      # @todo replace `args_for_change_date_on_picker` with hash table `merge`
       def picker_set_date_time (target_dt, options = {:animate => true,
                                                       :picker_id => nil,
                                                       :notify_targets => true})

data/lib/calabash-cucumber/device.rb

@@ -3,28 +3,128 @@ require 'calabash-cucumber/utils/logging'
 
 module Calabash
   module Cucumber
-    # Class device encapsulates information about the device or devices we are
-    # interacting with during a test.
+
+    # Device encapsulates information about the device or simulator that the
+    # app is running on.  It also includes the following information about the
+    # app that is running on the current device.
+    #
+    # * The version of the embedded Calabash server.
+    # * Whether or not the app is an iPhone-only app that is being emulated on
+    #   an iPad.
     class Device
 
       include Calabash::Cucumber::Logging
 
+      # @!visibility private
       GESTALT_IPHONE = 'iPhone'
+
+      # @!visibility private
       GESTALT_IPAD = 'iPad'
+
+      # @!visibility private
       GESTALT_IPHONE5 = '4-inch'
+
+      # @!visibility private
       GESTALT_SIM_SYS = 'x86_64'
+
+      # @!visibility private
       GESTALT_IPOD = 'iPod'
 
+      # @!attribute [r] endpoint
+      # The http address of this device.
+      # @example
+      #  http://192.168.0.2:37265
+      # @return [String] an ip address with port number.
       attr_reader :endpoint
+
+      # The device family of this device.
+      #
+      # @note Also know as the form factor.
+      #
+      # @example
+      #  # will be one of
+      #  iPhone
+      #  iPod
+      #  iPad
+      #
+      # @!attribute [r] device_family
+      # @return [String] the device family
       attr_reader :device_family
-      attr_reader :simulator_details, :ios_version
+
+      # @!visibility private
+      # @attribute [r] simulator_details
+      # @return [String] Additional details about the simulator.  If this device
+      #  is a physical device, returns nil.
+      attr_reader :simulator_details
+
+      # The `major.minor.[.patch]` version of iOS that is running on this device.
+      #
+      # @example
+      #  7.1
+      #  6.1.2
+      #  5.1.1
+      #
+      # @attribute [r] ios_version
+      # @return [String] the version of the iOS that is running on this device
+      attr_reader :ios_version
+
+      # The hardware architecture of this device.  Also known as the chip set.
+      #
+      # @example
+      #  # simulator
+      #  i386
+      #  x86_64
+      #
+      # @example
+      #  # examples from physical devices
+      #  armv6
+      #  armv7s
+      #  arm64
+      #
+      # @attribute [r] system
+      # @return [String] the hardware architecture of this device.
+      #  this device.
       attr_reader :system
+
+      # The version of the embedded Calabash server that is running in the
+      # app under test on this device.
+      #
+      # @example
+      #  0.9.168
+      #  0.10.0.pre1
+      #
+      # @attribute [r] server_version
+      # @return [String] the major.minor.patch[.pre\d] version of the embedded
+      #  Calabash server
       attr_reader :server_version
+
+      # Indicates whether or not the app under test on this device is an
+      #  iPhone-only app that is being emulated on an iPad.
+      #
+      # @note If the `1x` or `2x` button is visible, then the app is being
+      #  emulated.
+      #
+      # @attribute [r] iphone_app_emulated_on_ipad
+      # @return [Boolean] `true` if the app under test is emulated
       attr_reader :iphone_app_emulated_on_ipad
+
+      # Indicates whether or not this device has a 4in screen.
+      # @attribute [r] iphone_4in
+      # @return [Boolean] `true` if this device has a 4in screen.
       attr_reader :iphone_4in
 
+      # @deprecated 0.10.0 no replacement
+      # @!attribute [rw] udid
+      # @return [String] The udid of this device.
       attr_accessor :udid
 
+      # Creates a new instance of Device.
+      #
+      # @see Calabash::Cucumber::Core#server_version
+      #
+      # @param [String] endpoint the http address of this device
+      # @param [Hash] version_data the output of the `server_version` function
+      # @return [Device] a new Device instance
       def initialize (endpoint, version_data)
         simulator_device = version_data['simulator_device']
         @endpoint = endpoint
@@ -37,35 +137,53 @@ module Calabash
         @iphone_4in = version_data['4inch']
       end
 
+      # Is this device a simulator or physical device?
+      # @return [Boolean] true if this device is a simulator
       def simulator?
         system.eql?(GESTALT_SIM_SYS)
       end
 
+      # Is this device a device or simulator?
+      # @return [Boolean] true if this device is a physical device
       def device?
         not simulator?
       end
 
+      # Is this device an iPhone?
+      # @return [Boolean] true if this device is an iphone
       def iphone?
         device_family.eql? GESTALT_IPHONE
       end
 
+      # Is this device an iPod?
+      # @return [Boolean] true if this device is an ipod
       def ipod?
         device_family.eql? GESTALT_IPOD
       end
 
+      # Is this device an iPad?
+      # @return [Boolean] true if this device is an ipad
       def ipad?
         device_family.eql? GESTALT_IPAD
       end
 
+      # Is this device a 4in iPhone?
+      # @return [Boolean] true if this device is a 4in iphone
       def iphone_4in?
         @iphone_4in
       end
 
+      # @deprecated 0.9.168 replaced with iphone_4in?
+      # @see #iphone_4in?
+      # Is this device an iPhone 5?
+      # @note Deprecated because the iPhone 5S reports as an iPhone6,*.
+      # @return [Boolean] true if this device is an iPhone 5
       def iphone_5?
         _deprecated('0.9.168', "use 'iphone_4in?' instead", :warn)
         iphone_4in?
       end
 
+      # @!visibility private
       def version_hash (version_str)
         tokens = version_str.split(/[,.]/)
         {:major_version => tokens[0],
@@ -73,37 +191,76 @@ module Calabash
          :bug_version => tokens[2]}
       end
 
+      # The major iOS version of this device.
+      # @return [String] the major version of the OS
       def ios_major_version
         version_hash(ios_version)[:major_version]
       end
 
+      # Is this device running iOS 7?
+      # @return [Boolean] true if the major version of the OS is 7
       def ios7?
         ios_major_version.eql?('7')
       end
 
+      # Is this device running iOS 6?
+      # @return [Boolean] true if the major version of the OS is 6
       def ios6?
         ios_major_version.eql?('6')
       end
 
+      # Is this device running iOS 5?
+      # @return [Boolean] true if the major version of the OS is 5
       def ios5?
         ios_major_version.eql?('5')
       end
 
+      # The screen size of the device.
+      #
+      # @note These values are not dynamically computed; they are constants.
+      #
+      # @note These values are for portrait or upside orientations
+      #
+      # @return [Hash] representation of the screen size as a hash with keys
+      #  `:width` and `:height`
       def screen_size
         return { :width => 768, :height => 1024 } if ipad?
         return { :width => 320, :height => 568 } if iphone_4in?
         { :width => 320, :height => 480 }
       end
 
+      # Is the app that is running an iPhone-only app emulated on an iPad?
+      #
+      # @note If the app is running in emulation mode, there will be a 1x or 2x
+      #   scale button visible on the iPad.
+      #
+      # @return [Boolean] true if the app running on this devices is an
+      #   iPhone-only app emulated on an iPad
       def iphone_app_emulated_on_ipad?
         iphone_app_emulated_on_ipad
       end
 
+      # The version of the embedded Calabash server running in the app under
+      # test on this device.
+      # @deprecated 0.9.169 replaced with `server_version`
+      # @see #server_version
+      # @return [String] the version of the embedded Calabash server
       def framework_version
         _deprecated('0.9.169', "use 'server_version', instead", :warn)
         @server_version
       end
 
+      # @deprecated 0.10.0 no replacement
+      def udid
+        _deprecated('0.10.0', 'no replacement', :warn)
+        @udid
+      end
+
+      # @deprecated 0.10.0 no replacement
+      def udid=(value)
+        _deprecated('0.10.0', 'no replacement', :warn)
+        @udid = value
+      end
     end
   end
 end