calabash-cucumber 0.10.0.pre1 → 0.10.0.pre2

data/lib/calabash-cucumber/environment_helpers.rb

@@ -5,134 +5,175 @@ require 'calabash-cucumber/utils/logging'
 module Calabash
   module Cucumber
 
-    # methods that describe the runtime environment
+    # Methods to expose the runtime environment and details about the device
+    # under test.
+    #
+    # @note
+    #  The `OS` environmental variable has been deprecated.  It should never
+    #  be set.
     module EnvironmentHelpers
 
       include Calabash::Cucumber::Logging
 
-      # returns +true+ if UIAutomation functions are available
+      # Are the uia* methods available?
       #
-      # UIAutomation is only available if the app has been launched with
-      # Instruments
+      # @note
+      #  UIAutomation is only available if the app has been launched with
+      #  instruments.
+      #
+      # @return [Boolean] Returns true if the app has been launched with
+      #  instruments.
       def uia_available?
         Calabash::Cucumber::Launcher.instruments?
       end
 
-      # returns +true+ if UIAutomation functions are not available
+      # Are the uia* methods un-available?
+      #
+      # @note
+      #  UIAutomation is only available if the app has been launched with
+      #  instruments.
       #
-      # UIAutomation is only available if the app has been launched with
-      # Instruments
+      # @return [Boolean] Returns true if the app has been not been launched with
+      #  instruments.
       def uia_not_available?
         not uia_available?
       end
 
-      # returns +true+ if cucumber is running in the test cloud
+      # Are we running in the Xamarin Test Cloud?
+      #
+      # @return [Boolean] Returns true if cucumber is running in the test cloud.
       def xamarin_test_cloud?
         ENV['XAMARIN_TEST_CLOUD'] == '1'
       end
 
-      # returns the default Device
+      # Returns the default Device that is connected the current launcher.
+      #
+      # @return [Calabash::Cucumber::Device] An instance of Device.
       def default_device
         l = Calabash::Cucumber::Launcher.launcher_if_used
         l && l.device
       end
 
-      # returns +true+ if the target device is an ipad
+      # Is the device under test an iPad?
       #
-      # raises an error if the server cannot be reached
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test is an iPad.
       def ipad?
         _default_device_or_create().ipad?
       end
 
-      # returns +true+ if the target device is an iphone
+      # Is the device under test an iPhone?
       #
-      # raises an error if the server cannot be reached
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test is an iPhone.
       def iphone?
         _default_device_or_create().iphone?
       end
 
-      # returns +true+ if the target device is an ipod
+      # Is the device under test an iPod?
       #
-      # raises an error if the server cannot be reached
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test is an iPod.
       def ipod?
         _default_device_or_create().ipod?
       end
-      
-      # returns +true+ if the target device is an iphone or ipod
+
+      # Is the device under test an iPhone or iPod?
       #
-      # raises an error if the server cannot be reached
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test is an iPhone or iPod.
       def device_family_iphone?
         iphone? or ipod?
       end
 
-      # returns +true+ if the target device is a simulator (not a physical device)
+      # Is the device under test a simulator?
       #
-      # raises an error if the server cannot be reached
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test is a simulator.
       def simulator?
         _default_device_or_create().simulator?
       end
 
-      # returns +true+ if the target device or simulator is a 4in model
-      #
-      # raises an error if the server cannot be reached
+      # @deprecated 0.9.168 replaced with `iphone_4in?`
+      # @see #iphone_4in?
       def iphone_5?
         _deprecated('0.9.168', "use 'iphone_4in?' instead", :warn)
         iphone_4in?
       end
 
-      # returns +true+ if the target device or simulator is a 4in model
+      # Does the device under test have 4in screen?
       #
-      # raises an error if the server cannot be reached
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test has a 4in screen.
       def iphone_4in?
         _default_device_or_create().iphone_4in?
       end
 
-      # returns +true+ if the OS major version is 5
+      # Is the device under test running iOS 5?
       #
-      # raises an error if the server cannot be reached
+      # @note
+      #  **WARNING:** The `OS` env variable has been deprecated and should
+      #  never be set.
       #
-      # WARNING: setting the +OS+ env variable will override the value returned
-      #          by querying the device
+      # @note
+      #  **WARNING:* Setting the `OS` env variable will override the value returned
+      #  by querying the device.
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test is running iOS 5
       def ios5?
         _OS_ENV.eql?(_canonical_os_version(:ios5)) || _default_device_or_create().ios5?
       end
 
-      # returns +true+ if the OS major version is 6
+      # Is the device under test running iOS 6?
       #
-      # raises an error if the server cannot be reached
+      # @note
+      #  **WARNING:** The `OS` env variable has been deprecated and should
+      #  never be set.
       #
-      # WARNING: setting the +OS+ env variable will override the value returned
-      #          by querying the device
+      # @note
+      #  **WARNING:* Setting the `OS` env variable will override the value returned
+      #  by querying the device.
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test is running iOS 6
       def ios6?
         _OS_ENV.eql?(_canonical_os_version(:ios6)) || _default_device_or_create().ios6?
       end
 
 
-      # returns +true+ if the OS major version is 7
+      # Is the device under test running iOS 7?
       #
-      # raises an error if the server cannot be reached
+      # @note
+      #  **WARNING:** The `OS` env variable has been deprecated and should
+      #  never be set.
       #
-      # WARNING: setting the +OS+ env variable will override the value returned
-      #          by querying the device
+      # @note
+      #  **WARNING:* Setting the `OS` env variable will override the value returned
+      #  by querying the device.
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if device under test is running iOS 7
       def ios7?
         _OS_ENV.eql?(_canonical_os_version(:ios7)) || _default_device_or_create().ios7?
       end
 
-      # returns +true+ if the app is an iphone app emulated on an ipad
+      # Is the app that is being tested an iPhone app emulated on an iPad?
+      #
+      # @see Calabash::Cucumber::IPad
       #
-      # raises an error if the server cannot be reached
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Boolean] true if app is being emulated on an iPad.
       def iphone_app_emulated_on_ipad?
         _default_device_or_create().iphone_app_emulated_on_ipad?
       end
 
       private
-      # returns the device that is currently being tested against
+      # @!visibility private
+      # Returns the device that is currently being tested against.
       #
-      # returns the +device+ attr of <tt>Calabash::Cucumber::Launcher</tt> if
-      # it is defined.  otherwise, creates a new <tt>Calabash::Cucumber::Device</tt>
+      # Returns the device attr of `Calabash::Cucumber::Launcher` if
+      # it is defined.  otherwise, creates a new `Calabash::Cucumber::Device`
       # by querying the server.
-      #
-      # raises an error if the server cannot be reached
+      # @raise [RuntimeError] if the server cannot be reached
+      # @return [Calabash::Cucumber::Device] an instance of Device
       def _default_device_or_create
         device = default_device
         if device.nil?
@@ -141,17 +182,21 @@ module Calabash
         device
       end
 
-      # returns the value of the environmental variable +OS+
+      # Returns the value of the environmental variable OS.
+      #
+      # @note
+      #  The `OS` env has been deprecated for some time.  It should never be set.
       def _OS_ENV
         ENV['OS']
       end
 
+      # @!visibility private
       CANONICAL_IOS_VERSIONS = {:ios5 => 'ios5',
                                 :ios6 => 'ios6',
                                 :ios7 => 'ios7'}
 
 
-      # returns the canonical value iOS versions as strings
+      # Returns the canonical value iOS versions as strings.
       def _canonical_os_version(key)
         CANONICAL_IOS_VERSIONS[key]
       end

data/lib/calabash-cucumber/failure_helpers.rb

@@ -2,8 +2,19 @@ require 'fileutils'
 
 module Calabash
   module Cucumber
+
+    # A collection of methods that help you handle Step failures.
     module FailureHelpers
 
+      # Generates a screenshot of the app UI and saves to a file (prefer `screenshot_embed`).
+      # Increments a global counter of screenshots and adds the count to the filename (to ensure uniqueness).
+      #
+      # @see #screenshot_embed
+      # @param {Hash} options to control the details of where the screenshot is stored.
+      # @option options {String} :prefix (ENV['SCREENSHOT_PATH']) a prefix to prepend to the filename (e.g. 'screenshots/foo-').
+      #   Uses ENV['SCREENSHOT_PATH'] if nil or '' if ENV['SCREENSHOT_PATH'] is nil
+      # @option options {String} :name ('screenshot') the base name and extension of the file (e.g. 'login.png')
+      # @return {String} path to the generated screenshot
       def screenshot(options={:prefix => nil, :name => nil})
         prefix = options[:prefix]
         name = options[:name]
@@ -27,17 +38,46 @@ module Calabash
         path
       end
 
+      # Generates a screenshot of the app UI and embeds the screenshots in all active cucumber reporters (using `embed`).
+      # Increments a global counter of screenshots and adds the count to the filename (to ensure uniqueness).
+      #
+      # @param {Hash} options to control the details of where the screenshot is stored.
+      # @option options {String} :prefix (ENV['SCREENSHOT_PATH']) a prefix to prepend to the filename (e.g. 'screenshots/foo-').
+      #   Uses ENV['SCREENSHOT_PATH'] if nil or '' if ENV['SCREENSHOT_PATH'] is nil
+      # @option options {String} :name ('screenshot') the base name and extension of the file (e.g. 'login.png')
+      # @option options {String} :label (uses filename) the label to use in the Cucumber reporters
+      # @return {String} path to the generated screenshot
       def screenshot_embed(options={:prefix => nil, :name => nil, :label => nil})
         path = screenshot(options)
         filename = options[:label] || File.basename(path)
         embed(path, 'image/png', filename)
       end
 
+      # Generates a screenshot of the app UI by calling screenshot_embed and raises an error.
+      # Increments a global counter of screenshots and adds the count to the filename (to ensure uniqueness).
+      #
+      # @see #screenshot_embed
+      # @param {String} msg the message to use for the raised RuntimeError.
+      # @param {Hash} options to control the details of where the screenshot is stored.
+      # @option options {String} :prefix (ENV['SCREENSHOT_PATH']) a prefix to prepend to the filename (e.g. 'screenshots/foo-').
+      #   Uses ENV['SCREENSHOT_PATH'] if nil or '' if ENV['SCREENSHOT_PATH'] is nil
+      # @option options {String} :name ('screenshot') the base name and extension of the file (e.g. 'login.png')
+      # @option options {String} :label (uses filename) the label to use in the Cucumber reporters
+      # @raise [RuntimeError] with `msg`
       def screenshot_and_raise(msg, options={:prefix => nil, :name => nil, :label => nil})
         screenshot_embed(options)
         raise(msg)
       end
 
+      # Calls `screenshot_and_raise(msg,options)`
+      # @see #screenshot_and_raise
+      # @param {String} msg the message to use for the raised RuntimeError.
+      # @param {Hash} options to control the details of where the screenshot is stored.
+      # @option options {String} :prefix (ENV['SCREENSHOT_PATH']) a prefix to prepend to the filename (e.g. 'screenshots/foo-').
+      #   Uses ENV['SCREENSHOT_PATH'] if nil or '' if ENV['SCREENSHOT_PATH'] is nil
+      # @option options {String} :name ('screenshot') the base name and extension of the file (e.g. 'login.png')
+      # @option options {String} :label (uses filename) the label to use in the Cucumber reporters
+      # @raise [RuntimeError] with `msg`
       def fail(msg='Error. Check log for details.', options={:prefix => nil, :name => nil, :label => nil})
         screenshot_and_raise(msg, options)
       end

data/lib/calabash-cucumber/http_helpers.rb

@@ -2,15 +2,20 @@ require 'httpclient'
 
 module Calabash
   module Cucumber
+
+    # @!visibility private
     module HTTPHelpers
 
+      # @!visibility private
       CAL_HTTP_RETRY_COUNT=3
+
+      # @!visibility private
       RETRYABLE_ERRORS = [HTTPClient::TimeoutError,
                           HTTPClient::KeepAliveDisconnected,
                           Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ECONNABORTED,
                           Errno::ETIMEDOUT]
 
-
+      # @!visibility private
       def http(options, data=nil)
         options[:uri] = url_for(options[:path])
         options[:method] = options[:method] || :get
@@ -26,7 +31,7 @@ module Calabash
         res
       end
 
-
+      # @!visibility private
       def url_for(verb)
         url = URI.parse(ENV['DEVICE_ENDPOINT']|| "http://localhost:37265")
         path = url.path
@@ -39,6 +44,7 @@ module Calabash
         url
       end
 
+      # @!visibility private
       def make_http_request(options)
         retryable_errors = options[:retryable_errors] || RETRYABLE_ERRORS
         CAL_HTTP_RETRY_COUNT.times do |count|
@@ -82,6 +88,7 @@ module Calabash
         end
       end
 
+      # @!visibility private
       def init_request(options={})
         http = HTTPClient.new
         http.connect_timeout = 30

data/lib/calabash-cucumber/ibase.rb

@@ -1,29 +1,119 @@
 require 'calabash-cucumber/core'
 require 'calabash-cucumber/operations'
 
+# The `IBase` class is a base class that can be used to easily implement page object classes on iOS (hence the I).
+# Delegates to the cucumber World object for missing methods (e.g. embed or puts).
+# Mixes in {Calabash::Cucumber::Operations}.
+# For Calabash Android there is a corresponding `ABase`.
+# For more detailed documentation on using the Page Object Pattern (POP) with Calabash, please see:
+# {http://developer.xamarin.com/guides/testcloud/calabash/xplat-best-practices/}.
+# Note we recommend using POP even if you're not targeting multiple platforms as it tends to lead to more maintainable
+# test suites.
 class Calabash::IBase
   include Calabash::Cucumber::Operations
 
-  attr_accessor :world, :transition_duration
+  # A reference to the Cucumber World variable.
+  # @!attribute [rw] world
+  # @return [Object] the Cucumber World instance
+  attr_accessor :world
 
+  # The number of seconds to allow for page complete animations _after_ this
+  # page trait becomes visible.
+  #
+  # @note By default, this value is _not_ used.  To use this additional
+  #  wait time, you need to include `:await_animation => true` in the options
+  #  hash that is passed the `await` and `transition` methods.
+  #
+  # @see #trait
+  # @see #await
+  # @see #transition
+  #
+  # @!attribute [rw] transition_duration
+  # @return [Number] the number of seconds to allow for page transitions
+  attr_accessor :transition_duration
+
+  # Create a new page object.
+  #
+  # @param [Object] world the cucumber World object
+  # @param [Number] transition_duration the number of seconds to for page
+  #  transitions
   def initialize(world, transition_duration=0.5)
     self.world = world
     self.transition_duration = transition_duration
   end
 
+  # Specifies a query that recognizes this page.
+  #
+  # @abstract
+  # @see #await
+  #
+  # In your subclass, you have two options to implement this abstract method.
+  #
+  # 1. Override the `trait` method.
+  # 2. Implement a `title` method.
+  #
+  # If you implement a `title` method, this method will return:
+  # `"navigationItemView marked:'#{self.title}'"`
+  #
+  # @note It is recommended that you override this method method in your in
+  #  your subclasses (option 1 below).  Relying on the UINavigationBar title is
+  #  risky because Apple's UINavigationBar API changes often.
+  #
+  # @example
+  #  "view marked:'home'"
+  #
+  # @example
+  #  "tableView marked:'playlist'"
+  #
+  # @example
+  #  "button marked:'login'"
+  #
+  # @return [String] a query string that identifies this page
+  # @raise [RuntimeError] if the subclass does not respond to `title` or
+  #  the subclass does not override the `trait` method
   def trait
     raise "You should define a trait method or a title method" unless respond_to?(:title)
     "navigationItemView marked:'#{self.title}'"
   end
 
+  # Returns true if the current view shows this page's `trait`.
+  # @see #trait
+  # @return [Boolean] true if `element_exists(trait)`
   def current_page?
     element_exists(trait)
   end
 
+  # A variant of {Calabash::Cucumber::Core#page} that works inside page objects.
+  #
+  # @note It is assumed that `clz` will be a subclass of Calabash::IBase or will
+  # behave as such.
+  #
+  # @see Calabash::Cucumber::Core#page
+  # @see Calabash::IBase
+  # @param {Class} clz the page object class to instantiate (passing the cucumber world and `args`)
+  # @param {Array} args optional additional arguments to pass to the page object constructor
+  # @return {Object} a fresh instance of `Class clz` which has been passed a reference to the cucumber World object.
   def page(clz, *args)
     clz.new(world, *args)
   end
 
+  # Waits for this page's `trait` to become visible.
+  #
+  # After this page appears, you can optionally wait for
+  # `self.transition_duration` more seconds.
+  #
+  # @see Calabash::Cucumber::WaitHelpers#wait_for_element_exists
+  # @see Calabash::Cucumber::WaitHelpers#wait_for
+  # @see #trait
+  # @see #transition_duration
+  #
+  # @param {Hash} wait_opts options hash to pass to `wait_for_element_exists`
+  #   (see {Calabash::Cucumber::WaitHelpers#wait_for} and
+  #   {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS}).
+  # @option wait_opts [Boolean] :await_animation (false)
+  #   if true, will wait for `self.transition_duration` after this page's
+  #   `trait` appears
+  # @return {IBase} self
   def await(wait_opts={})
     wait_for_elements_exist([trait], wait_opts)
     unless wait_opts.has_key?(:await_animation) && !wait_opts[:await_animation]
@@ -32,24 +122,53 @@ class Calabash::IBase
     self
   end
 
-  ##
-  # Performs a transition from receiver page to another by performing a +:tap+ gesture
-  # or a user specified +:action+.
-  # Caller must supply a hash of options +transition_options+ to describe the transition.
-  # Transition options may have the following keys
+  # Performs a transition from receiver page to another by performing a `tap`
+  # gesture or a user specified `action`.
+  #
+  # Callers must supply a hash of options `transition_options` to describe the
+  # transition.
+  #
+  # @note If a `tap` _and_ and `action` are defined, the `action` will be
+  #  ignored.
+  #
+  # @note If `transition_options[:page]` is defined, then it is assumed its
+  #   value will be a subclass of Calabash::IBase or will behave as such.
+  #
+  # @example Use this pattern to wait for `transition_duration` after the
+  #  the target page's trait becomes visible.
   #
-  # +:tap+: A uiquery used to perform a tap gesture to begin transition
-  # +:action+: A proc to use begin transition (either :tap or :action must be supplied)
-  # +:page+: A page object or page object class to transition to (target page). If a class is provided this
-  # is instantiated using the +page+ method of self. If no +:page+ is supplied, +self+ is used.
-  # +:await+: If specified and truthy will await the +:page+ after performing gesture (usually to wait
-  # for animation to finish)
-  # +:tap_options+: If +:tap+ is provided used to pass as options to touch
-  # +:wait_options+: When awaiting target page, pass these options to the +await+ method
+  #  opts = {:tap => "button marked:'login'",
+  #          :wait_options => {:await_animation => true},
+  #          :page => LoginPage}
+  #  transition(opts)
   #
-  # Returns the transition target page
+  # @param [Hash] transition_options options for controlling the transition
   #
-  # Note it is assumed that the target page is a Calabash::IBase (or acts accordingly)
+  # @option transition_options [String] :tap
+  #  A uiquery used to perform a tap gesture to begin transition.
+  #
+  # @option transition_options [Proc] :action
+  #  A proc to use begin transition.
+  #
+  # @option transition_options [IBase,Class,nil] :page
+  #  A page object or page object `class` to transition to (target page).
+  #  If a `class` is provided it is instantiated using the `self.page` method.
+  #  If no `page` is supplied, `self` is used.
+  #
+  # @option transition_options [Boolean] :await
+  #  If true the `page`'s await will be called after performing the transition
+  #  that triggers the transition.  This is useful for waiting for animations to
+  #  complete.  Defaults to `true`.
+  #
+  # @option transition_options [Hash] :tap_options if a `tap` gesture is defined
+  #  then these options will be passed to `touch`.
+  #
+  # @option transition_options [Hash] :wait_options if the :await key is true,
+  #  then these options are passed to the `page.await` method.
+  #
+  # @return [IBase] the page that is transitioned to
+  # @raise [RuntimeError] if `transition_options` does not include a non-nil
+  #  :tap or :action key
   def transition(transition_options={})
     uiquery = transition_options[:tap]
     action = transition_options[:action]
@@ -84,12 +203,12 @@ class Calabash::IBase
     page_obj
   end
 
+  # @!visibility private
   def await_screenshot(wait_opts={}, screenshot_opts={})
     await(wait_opts)
     screenshot_embed(screenshot_opts)
   end
 
-
   protected
   def method_missing(name, *args, &block)
     world.send(name, *args, &block)