calabash-cucumber 0.10.0.pre1 → 0.10.0.pre2

data/lib/calabash-cucumber/version.rb

@@ -1,9 +1,18 @@
 require 'calabash-cucumber/utils/logging'
+
 module Calabash
   module Cucumber
-    VERSION = '0.10.0.pre1'
+
+    # @!visibility public
+    # The Calabash iOS gem version.
+    VERSION = '0.10.0.pre2'
+
+    # @!visibility public
+    # The minimum required version of the calabash.framework or, for Xamarin
+    # users, the Calabash component.
     MIN_SERVER_VERSION = '0.10.0.pre1'
 
+    # @!visibility private
     def self.const_missing(const_name)
       if const_name == :FRAMEWORK_VERSION
         _deprecated('0.9.169', 'FRAMEWORK_VERSION has been deprecated - there is no replacement', :warn)
@@ -12,14 +21,58 @@ module Calabash
       raise(NameError, "uninitialized constant Calabash::Cucumber::#{const_name}")
     end
 
+    # A model of a release version that can be used to compare two version.
+    #
+    # Calabash tries very hard to comply with Semantic Versioning rules.
+    #
+    # However, our test workflow requires that we use `.pre` to denote
+    # pre-release versions instead of the recommended `-alpha`, `-beta`, or, `-pre`.
+    #
+    # Calabash version numbers will be in the form `<major>.<minor>.<patch>[.pre<N>]`.
+    #
+    # @see http://semver.org/
     class Version
 
+      # @!attribute [rw] major
+      #   @return [Integer] the major version
       attr_accessor :major
+
+      # @!attribute [rw] minor
+      #   @return [Integer] the minor version
       attr_accessor :minor
+
+      # @!attribute [rw] patch
+      #   @return [Integer] the patch version
       attr_accessor :patch
+
+      # @!attribute [rw] pre
+      #   @return [Boolean] true if this is a pre-release version
       attr_accessor :pre
+
+      # @!attribute [rw] pre_version
+      #   @return [Integer] if this is a pre-release version, returns the
+      #     pre-release version; otherwise this is nil
       attr_accessor :pre_version
 
+      # Creates a new Version instance with all the attributes set.
+      #
+      # @example
+      #  version = Version.new(0.10.1)
+      #  version.major       => 0
+      #  version.minor       => 10
+      #  version.patch       => 1
+      #  version.pre         => false
+      #  version.pre_release => nil
+      #
+      # @example
+      #  version = Version.new(1.6.3.pre5)
+      #  version.major       => 1
+      #  version.minor       => 6
+      #  version.patch       => 3
+      #  version.pre         => true
+      #  version.pre_release => 5
+      #
+      # @param [String] version the version string to parse.
       def initialize(version)
         tokens = version.split('.')
         count = tokens.count
@@ -32,36 +85,64 @@ module Calabash
         @major, @minor, @patch = version.split('.').map(&:to_i)
       end
 
+      # Returns an string representation of this version.
+      # @return [String] a string in the form `<major>.<minor>.<patch>[.pre<N>]`
       def to_s
         str = [@major, @minor, @patch].join('.')
         str = "#{str}.#{@pre}" if @pre
         str
       end
 
+      # Compare this version to another for equality.
+      # @param [Version] other the version to compare against
+      # @return [Boolean] true if this Version is the same as `other`
       def == (other)
         compare(self, other) == 0
       end
 
+      # Compare this version to another for inequality.
+      # @param [Version] other the version to compare against
+      # @return [Boolean] true if this Version is not the same as `other`
       def != (other)
         compare(self, other) != 0
       end
 
+      # Is this version less-than another version?
+      # @param [Version] other the version to compare against
+      # @return [Boolean] true if this Version is less-than `other`
       def < (other)
         compare(self, other) < 0
       end
 
+      # Is this version greater-than another version?
+      # @param [Version] other the version to compare against
+      # @return [Boolean] true if this Version is greater-than `other`
       def > (other)
         compare(self, other) > 0
       end
 
+      # Is this version less-than or equal to another version?
+      # @param [Version] other the version to compare against
+      # @return [Boolean] true if this Version is less-than or equal `other`
       def <= (other)
         compare(self, other) <= 0
       end
 
+      # Is this version greater-than or equal to another version?
+      # @param [Version] other the version to compare against
+      # @return [Boolean] true if this Version is greater-than or equal `other`
       def >= (other)
         compare(self, other) >= 0
       end
 
+      # Compare version `a` to version `b`.
+      #
+      # @example
+      #   compare Version.new(0.10.0), Version.new(0.9.0)  =>  1
+      #   compare Version.new(0.9.0),  Version.new(0.10.0) => -1
+      #   compare Version.new(0.9.0),  Version.new(0.9.0)  =>  0
+      #
+      # @return [Integer] an integer `(-1, 1)`
       def compare(a, b)
 
         if a.major != b.major
@@ -93,12 +174,20 @@ module Calabash
   end
 end
 
+# These are unit tests.
+#
+# $ ruby lib/calabash-cucumber/version.rb
+#
+# todo move to rspec
 if __FILE__ == $0
   require 'test/unit'
 
+  # @!visibility private
+  # Unit testing of Version class
   class LocalTest < Test::Unit::TestCase
     include Calabash::Cucumber
 
+    # @!visibility private
     def test_version
       a = Version.new('0.9.169')
       assert_equal(0, a.major)
@@ -108,18 +197,21 @@ if __FILE__ == $0
       assert_nil(a.pre_version)
     end
 
+    # @!visibility private
     def test_unnumbered_prerelease
       a = Version.new('0.9.169.pre')
       assert_equal('pre', a.pre)
       assert_nil(a.pre_version)
     end
 
+    # @!visibility private
     def test_numbered_prerelease
       a = Version.new('0.9.169.pre1')
       assert_equal('pre1', a.pre)
       assert_equal(1, a.pre_version)
     end
 
+    # @!visibility private
     def test_compare_equal
       a = Version.new('0.9.169')
       b = Version.new('0.9.169')
@@ -135,12 +227,12 @@ if __FILE__ == $0
 
     end
 
+    # @!visibility private
     def test_compare_not_equal
       a = Version.new('0.9.168')
       b = Version.new('0.9.169')
       assert(a != b)
 
-
       a = Version.new('0.9.169')
       b = Version.new('0.9.169.pre1')
       assert(a != b)
@@ -154,6 +246,7 @@ if __FILE__ == $0
       assert(a != b)
     end
 
+    # @!visibility private
     def test_compare_lt
       a = Version.new('0.9.168')
       b = Version.new('0.9.169')
@@ -172,6 +265,7 @@ if __FILE__ == $0
       assert(a < b)
     end
 
+    # @!visibility private
     def test_compare_gt
       a = Version.new('0.9.169')
       b = Version.new('0.9.168')
@@ -190,6 +284,7 @@ if __FILE__ == $0
       assert(a > b)
     end
 
+    # @!visibility private
     def test_compare_lte
       a = Version.new('0.9.168')
       b = Version.new('0.9.169')
@@ -198,6 +293,7 @@ if __FILE__ == $0
       assert(a <= b)
     end
 
+    # @!visibility private
     def test_compare_gte
       a = Version.new('0.9.169')
       b = Version.new('0.9.168')

data/lib/calabash-cucumber/wait_helpers.rb

@@ -5,28 +5,81 @@ require 'calabash-cucumber/utils/logging'
 
 module Calabash
   module Cucumber
+
+    # A collection of methods that help you wait for things.
     module WaitHelpers
       include Calabash::Cucumber::Logging
       include Calabash::Cucumber::Core
       include Calabash::Cucumber::TestsHelpers
 
+      # @!visibility private
       CLIENT_TIMEOUT_ADDITION = 5
 
+      # `WaitError` is the error type raised
+      # when a timeout occurs during a wait.
+      # To handle a timeout without causing test failure use
+      # @example
+      #   begin
+      #     ...
+      #   rescue Calabash::Cucumber::WaitHelpers::WaitError => e
+      #     ...
+      #   end
+      #
       class WaitError < RuntimeError
       end
 
-      CALABASH_CONDITIONS = {:none_animating => "NONE_ANIMATING",
-                             :no_network_indicator => "NO_NETWORK_INDICATOR"}
+      # Currently two conditions that can be
+      # waited for using `wait_for_condition`: `:none_animating` no UIKit object is animating
+      # and `:no_network_indicator` status bar network indicator not showing.
+      CALABASH_CONDITIONS = {:none_animating => 'NONE_ANIMATING',
+                             :no_network_indicator => 'NO_NETWORK_INDICATOR'}
 
-      # 'post_timeout' is the time to wait after a wait function returns true
+      # The default options used in the "wait*" methods
       DEFAULT_OPTS = {
-        :timeout => 30,
-        :retry_frequency => 0.3,
-        :post_timeout => 0,
-        :timeout_message => 'Timed out waiting...',
-        :screenshot_on_error => true
+            # default upper limit on how long to wait
+            :timeout => 30,
+            # default polling frequency for waiting
+            :retry_frequency => 0.3,
+            # default extra wait after the condition becomes true
+            :post_timeout => 0,
+            # default message if timeout occurs
+            :timeout_message => 'Timed out waiting...',
+            # Calabash will generate a screenshot by default if waiting times out
+            :screenshot_on_error => true
       }.freeze
 
+      # Waits for a condition to be true. The condition is specified by a given block that is called repeatedly.
+      # If the block returns a 'trueish' value the condition is considered true and
+      # `wait_for` immediately returns.
+      # There is a `:timeout` option that specifies a maximum number of seconds to wait.
+      # If the given block doesn't return a 'trueish' value before the `:timeout` seconds has elapsed,
+      # the waiting fails and raises a {Calabash::Cucumber::WaitHelpers::WaitError} error.
+      #
+      # The `options` hash
+      # controls the details of waiting (see `options_or_timeout` below).
+      # {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} specifies the default waiting options.
+      #
+      # `wait_for` is a low-level building-block for waiting and often there are higher-level
+      # waiting methods what use `wait_for` in their implementation (e.g. `wait_for_element_exists`).
+      # @see #wait_for_element_exists
+      #
+      # @example Waiting for an element (see also `wait_for_element_exists`)
+      #   wait_for(timeout: 60,
+      #            timeout_message: "Could not find 'Sign in' button") do
+      #     element_exists("button marked:'Sign in'")
+      #   end
+      # @param [Hash] options_or_timeout options for controlling the details of the wait.
+      #   Note for backwards compatibility with old Calabash versions can also be a number which is
+      #   then interpreted as a timeout.
+      # @option options_or_timeout [Numeric] :timeout (30) upper limit on how long to wait (in seconds)
+      # @option options_or_timeout [Numeric] :retry_frequency (0.3) how often to poll (i.e., call the given block)
+      # @option options_or_timeout [Numeric] :post_timeout (0) if positive, an extra wait is made after the condition
+      #   is satisfied
+      # @option options_or_timeout [String] :timeout_message the error message to use if condition is not satisfied
+      #   in time
+      # @option options_or_timeout [Boolean] :screenshot_on_error generate a screenshot on error
+      # @return [nil] when the condition is satisfied
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] when the timeout is exceeded
       def wait_for(options_or_timeout=DEFAULT_OPTS, &block)
         #note Hash is preferred, number acceptable for backwards compat
         default_timeout = 30
@@ -54,29 +107,45 @@ module Calabash
         rescue WaitError => e
           msg = timeout_message || e
           if screenshot_on_error
-           sleep(retry_frequency)
-           return screenshot_and_retry(msg, &block)
+            sleep(retry_frequency)
+            return screenshot_and_retry(msg, &block)
           else
-           raise wait_error(msg)
-         end
+            raise wait_error(msg)
+          end
         rescue Exception => e
           handle_error_with_options(e, nil, screenshot_on_error)
         end
       end
 
-      def screenshot_and_retry(msg, &block)
-        path  = screenshot
-        res = yield
-        # Validate after taking screenshot
-        if res
-          FileUtils.rm_f(path)
-          return res
-        else
-          embed(path, 'image/png', msg)
-          raise wait_error(msg)
-        end
-      end
-
+      # Repeatedly runs an action (for side-effects) until a condition is satisfied.
+      # Similar to `wait_for` but specifies both a condition to wait for and an action to repeatedly perform
+      # to make the condition true (e.g. scrolling). The return value of the action is ignored.
+      #
+      # The block represents the action and options :until or :until_exists specify the condition to wait for.
+      # Same options as `wait_for` can be provided.
+      #
+      # @see #wait_for
+      #
+      # @example Scrolling until we find an element
+      #   wait_poll(timeout: 10,
+      #             timeout_message: 'Unable to find "Example"',
+      #             until_exists: "* marked:'Example'") do
+      #     scroll("tableView", :down)
+      #   end
+      #
+      # @example Win the battle
+      #   wait_poll(timeout: 60,
+      #             timeout_message: 'Defeat!',
+      #             until: lambda { enemy_defeated? }) do
+      #     launch_the_missiles!
+      #   end
+      # @param [Hash] opts options for controlling the details of the wait in addition to the options specified below,
+      #   all options in {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} also apply and can be overridden.
+      # @option opts [Proc] :until if specified this lambda/Proc becomes the condition to wait for.
+      # @option opts [String] :until_exists if specified, a calabash query to wait for. Exactly one of `:until` and
+      #   `:until_exists` must be specified
+      # @return [nil] when the condition is satisfied
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] when the timeout is exceeded
       def wait_poll(opts, &block)
         test = opts[:until]
         if test.nil?
@@ -94,17 +163,72 @@ module Calabash
         end
       end
 
-      #options for wait_for apply
+      # Waits for a Calabash query to return a non-empty result (typically a UI element to be visible).
+      # Uses `wait_for`.
+      # @see #wait_for
+      # @see Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS
+      #
+      # @example Waiting for an element to be visible
+      #   wait_for_element_exists("button marked:'foo'", timeout: 60)
+      # @param [String] element_query a Calabash query to wait for (i.e. `element_exists(element_query)`)
+      # @param [Hash] options options for controlling the details of the wait.
+      #   The same options as {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} apply.
+      # @return [nil] when the condition is satisfied
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] when the timeout is exceeded
+      def wait_for_element_exists(element_query, options={})
+        options[:timeout_message] = options[:timeout_message] || "Timeout waiting for element: #{element_query}"
+        wait_for(options) { element_exists(element_query) }
+      end
+
+      # Waits for one or more Calabash queries to all return non-empty results (typically a UI elements to be visible).
+      # Uses `wait_for`.
+      # @see #wait_for
+      # @see #wait_for_element_exists
+      # @see Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS
+      #
+      # @param [Array<String>] elements_arr an Array of Calabash queries to wait for (i.e. `element_exists(element_query)`)
+      # @param [Hash] options options for controlling the details of the wait.
+      #   The same options as {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} apply.
+      # @return [nil] when the condition is satisfied
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] when the timeout is exceeded
       def wait_for_elements_exist(elements_arr, options={})
         if elements_arr.is_a?(String)
           elements_arr = [elements_arr]
         end
-        options[:timeout_message] = options[:timeout_message] || "Timeout waiting for elements: #{elements_arr.join(",")}"
+        options[:timeout_message] = options[:timeout_message] || "Timeout waiting for elements: #{elements_arr.join(',')}"
         wait_for(options) do
           elements_arr.all? { |q| element_exists(q) }
         end
       end
-      #options for wait_for apply
+
+      # Waits for a Calabash query to return an empty result (typically a UI element to disappear).
+      # Uses `wait_for`.
+      # @see #wait_for
+      # @see #wait_for_element_exists
+      # @see Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS
+      #
+      # @param [String] element_query a Calabash query to be empty (i.e. `element_does_not_exist(element_query)`)
+      # @param [Hash] options options for controlling the details of the wait.
+      #   The same options as {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} apply.
+      # @return [nil] when the condition is satisfied
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] when the timeout is exceeded
+      def wait_for_element_does_not_exists(element_query, options={})
+        options[:timeout_message] = options[:timeout_message] || "Timeout waiting for element to not exist: #{element_query}"
+        wait_for(options) { element_does_not_exist(element_query) }
+      end
+
+      # Waits for one or more Calabash queries to all return empty results (typically a UI elements to disappear).
+      # Uses `wait_for`.
+      # @see #wait_for
+      # @see #wait_for_element_exists
+      # @see #wait_for_element_does_not_exists
+      # @see Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS
+      #
+      # @param [Array<String>] elements_arr an Array of Calabash queries to be empty (i.e. `element_does_not_exist(element_query)`)
+      # @param [Hash] options options for controlling the details of the wait.
+      #   The same options as {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} apply.
+      # @return [nil] when the condition is satisfied
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] when the timeout is exceeded
       def wait_for_elements_do_not_exist(elements_arr, options={})
         if elements_arr.is_a?(String)
           elements_arr = [elements_arr]
@@ -115,6 +239,7 @@ module Calabash
         end
       end
 
+      # @!visibility private
       def wait_for_condition(options = {})
         timeout = options[:timeout]
         unless timeout && timeout > 0
@@ -142,13 +267,13 @@ module Calabash
 
         begin
           Timeout::timeout(timeout+CLIENT_TIMEOUT_ADDITION, WaitError) do
-              res = http({:method => :post, :path => 'condition'},
-                         options)
-              res = JSON.parse(res)
-              unless res['outcome'] == 'SUCCESS'
-                raise WaitError.new(res['reason'])
-              end
-              sleep(options[:post_timeout]) if options[:post_timeout] > 0
+            res = http({:method => :post, :path => 'condition'},
+                       options)
+            res = JSON.parse(res)
+            unless res['outcome'] == 'SUCCESS'
+              raise WaitError.new(res['reason'])
+            end
+            sleep(options[:post_timeout]) if options[:post_timeout] > 0
           end
         rescue WaitError => e
           msg = timeout_message || e
@@ -168,75 +293,83 @@ module Calabash
         end
       end
 
+      # Waits for all elements to stop animating (EXPERIMENTAL).
+      # @param [Hash] options options for controlling the details of the wait.
+      # @option options [Numeric] :timeout (30) maximum time to wait
+      # @return [nil] when the condition is satisfied
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] when the timeout is exceeded
       def wait_for_none_animating(options = {})
         options[:condition] = CALABASH_CONDITIONS[:none_animating]
         wait_for_condition(options)
       end
 
+      # Waits for the status-bar network indicator to stop animating (network activity done).
+      # @param [Hash] options options for controlling the details of the wait.
+      # @option options [Numeric] :timeout (30) maximum time to wait
+      # @return [nil] when the condition is satisfied
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] when the timeout is exceeded
       def wait_for_no_network_indicator(options = {})
         options[:condition] = CALABASH_CONDITIONS[:no_network_indicator]
         wait_for_condition(options)
       end
 
-      #may be called with a string (query) or an array of strings
+      # Combines waiting for elements and waiting for animations.
+      # @param [Array] done_queries Calabash queries to wait for (one or more).
+      # @param [Hash]  check_options ({}) options used for `wait_for_elements_exists(done_queries, check_options)`
+      # @param [Hash]  animation_options ({}) options used for `wait_for_none_animating(animation_options)`
       def wait_for_transition(done_queries, check_options={},animation_options={})
         done_queries = [*done_queries]
         wait_for_elements_exist(done_queries,check_options)
         wait_for_none_animating(animation_options)
       end
 
+      # Combines touching an element and `wait_for_transition`
+      # @see #wait_for_transition
+      # @param [String] touch_q the Calabash query to touch
+      # @param [Array] done_queries passed to `wait_for_transition`
+      # @param [Hash]  check_options ({}) passed to `wait_for_transition`
+      # @param [Hash]  animation_options ({}) passed to `wait_for_transition`
       def touch_transition(touch_q, done_queries,check_options={},animation_options={})
         touch(touch_q)
         wait_for_transition(done_queries,check_options,animation_options)
       end
 
-      def handle_error_with_options(ex, timeout_message, screenshot_on_error)
-        msg = (timeout_message || ex)
-        if ex
-          msg = "#{msg} (#{ex.class})"
-        end
-        if screenshot_on_error
-          screenshot_and_raise msg
-        else
-          raise msg
-        end
-      end
-
-      def wait_error(msg)
-        (msg.is_a?(String) ? WaitError.new(msg) : msg)
-      end
-
       # Performs a lambda action until the element (a query string) appears.
-      # The default action is to do nothing.
+      # The default action is to do nothing. Similar to `wait_poll`.
+      #
+      # Raises an error if no uiquery is specified.
       #
-      # Raises an error if no uiquery is specified. Same options as wait_for
-      # which are timeout, retry frequency, post_timeout, timeout_message, and 
-      # screenshot on error.
+      # @see #wait_poll
       #
-      # Example usage: 
-      # until_element_exists("Button", :action => lambda { swipe("up") })
+      # @example
+      #   until_element_exists("button", :action => lambda { swipe("up") })
+      # @param [String] uiquery the Calabash query to wait for
+      # @param [Hash] opts options for controlling the details of the wait.
+      #   The same options as {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} apply.
       def until_element_exists(uiquery, opts = {})
-        extra_opts = { :until_exists => uiquery, :action => lambda { ; } }
+        extra_opts = { :until_exists => uiquery, :action => lambda {} }
         opts = DEFAULT_OPTS.merge(extra_opts).merge(opts)
-        wait_poll(opts) do 
+        wait_poll(opts) do
           opts[:action].call
         end
       end
 
       # Performs a lambda action until the element (a query string) disappears.
-      # The default action is to do nothing. 
+      # The default action is to do nothing.
       #
-      # Raises an error if no uiquery is specified. Same options as wait_for
-      # which are timeout, retry frequency, post_timeout, timeout_message, and
-      # screenshot on error.
+      # Raises an error if no uiquery is specified.
       #
-      # Example usage: 
-      # until_element_does_not_exist("Button", :action => lambda { swipe("up") })
+      # @example
+      #   until_element_does_not_exist("button", :action => lambda { swipe("up") })
+      # @see #wait_poll
+      # @param [String] uiquery the Calabash query to wait for disappearing.
+      # @param [Hash] opts options for controlling the details of the wait.
+      #   The same options as {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} apply.
       def until_element_does_not_exist(uiquery, opts = {})
-        condition = lambda { element_exists(uiquery) ? false : true }
-        extra_opts = { :until => condition, :action => lambda { ; } }
+        condition = lambda {element_does_not_exist(uiquery)}
+        extra_opts = { :until => condition, :action => lambda {} }
         opts = DEFAULT_OPTS.merge(extra_opts).merge(opts)
-        wait_poll(opts) do 
+        wait_poll(opts) do
           opts[:action].call
         end
       end
@@ -244,16 +377,63 @@ module Calabash
       # Performs a lambda action once the element exists.
       # The default behavior is to touch the specified element.
       #
-      # Raises an error if no uiquery is specified. Same options as wait_for
-      # which are timeout, retry frequency, post_timeout, timeout_message, and
-      # screenshot on error.
+      # Raises an error if no uiquery is specified.
       #
-      # Example usage: when_element_exists("Button", :timeout => 10)
+      # @example
+      #   when_element_exists("button", :timeout => 10)
+      # @see #wait_for
+      # @param [String] uiquery the Calabash query to wait for.
+      # @param [Hash] opts options for controlling the details of the wait.
+      #   The same options as {Calabash::Cucumber::WaitHelpers::DEFAULT_OPTS} apply.
       def when_element_exists(uiquery, opts = {})
-        action = { :action => lambda { touch uiquery } }
-        opts = DEFAULT_OPTS.merge(action).merge(opts)
-        wait_for_elements_exist([uiquery], opts)
-        opts[:action].call
+        action = opts[:action] || lambda { touch(uiquery) }
+        wait_for_element_exists(uiquery, opts)
+        action.call
+      end
+
+      # @!visibility private
+      def screenshot_and_retry(msg, &block)
+        path  = screenshot
+        res = yield
+        # Validate after taking screenshot
+        if res
+          FileUtils.rm_f(path)
+          return res
+        else
+          embed(path, 'image/png', msg)
+          raise wait_error(msg)
+        end
+      end
+
+      # @!visibility private
+      # raises an error by raising a exception and conditionally takes a
+      # screenshot based on the value of +screenshot_on_error+.
+      # @param [Exception,nil] ex an exception to raise
+      # @param [String,nil] timeout_message the message of the raise
+      # @param [Boolean] screenshot_on_error if true takes a screenshot before
+      #  raising an error
+      # @return [nil]
+      # @raise RuntimeError based on +ex+ and +timeout_message+
+      def handle_error_with_options(ex, timeout_message, screenshot_on_error)
+        msg = (timeout_message || ex)
+        if ex
+          msg = "#{msg} (#{ex.class})"
+        end
+        if screenshot_on_error
+          screenshot_and_raise msg
+        else
+          raise msg
+        end
+      end
+
+      # @private
+      # if +msg+ is a String, a new WaitError is returned. Otherwise +msg+
+      # itself is returned.
+      # @param [String,Object] msg a message to raise
+      # @return [WaitError] if +msg+ is a String, returns a new WaitError
+      # @return [Object] if +msg+ is anything else, returns +msg+
+      def wait_error(msg)
+        (msg.is_a?(String) ? WaitError.new(msg) : msg)
       end
 
     end