wait.rb in calabash-2.0.0.pre1

- old
+ new

@@ -1,9 +1,8 @@
 module Calabash
 
   # A public API for waiting for things to happen.
-  # @!visibility private
   module Wait
     # @!visibility private
     class TimeoutError < RuntimeError
     end
 
@@ -139,13 +138,19 @@
       end
     end
 
     # Waits for `query` to match one or more views.
     #
-    # @param [String] query Query to match view
+    # @example
+    #  wait_for_view({marked: 'mark'})
+    #
+    # @example
+    #  text = wait_for_view("myview")['text']
+    #
+    # @param [String, Hash, Calabash::Query] query Query to match view
     # @see Calabash::Wait#with_timeout for options
-    # @return [Object] The first view matching `query`.
+    # @return [Hash] The first view matching `query`.
     def wait_for_view(query, options={})
       if query.nil?
         raise ArgumentError, 'Query cannot be nil'
       end
 
@@ -167,11 +172,13 @@
       end.first
     end
 
     # Waits for all `queries` to simultaneously match at least one view.
     #
-    # @param [Array<String>, String] queries List of queries or a query.
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query.
+    #
     # @see Calabash::Wait#with_timeout for options
     # @return [void] The return value for this method is undefined.
     def wait_for_views(*queries, **options)
       if queries.nil? || queries.any?(&:nil?)
         raise ArgumentError, 'Query cannot be nil'
@@ -198,11 +205,11 @@
       true
     end
 
     # Waits for `query` not to match any views
     #
-    # @param [String] query Query to match view
+    # @param [String, Hash, Calabash::Query] query Query to match view
     # @see Calabash::Wait#with_timeout for options
     def wait_for_no_view(query, options={})
       if query.nil?
         raise ArgumentError, 'Query cannot be nil'
       end
@@ -224,11 +231,13 @@
       end
     end
 
     # Waits for all `queries` to simultaneously match no views
     #
-    # @param [Array<String>, String] queries List of queries or a query.
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query.
+    #
     # @see Calabash::Wait#with_timeout for options
     def wait_for_no_views(*queries, **options)
       if queries.nil? || queries.any?(&:nil?)
         raise ArgumentError, 'Query cannot be nil'
       end
@@ -250,11 +259,11 @@
       end
     end
 
     # Does the given `query` match at least one view?
     #
-    # @param [String] query Query to match view
+    # @param [String, Hash, Calabash::Query] query Query to match view
     # @return [Object] Returns truthy if the `query` matches at least one view
     # @raise [ArgumentError] If given an invalid `query`
     def view_exists?(query)
       if query.nil?
         raise ArgumentError, 'Query cannot be nil'
@@ -269,11 +278,13 @@
       end
     end
 
     # Does the given `queries` all match at least one view?
     #
-    # @param [Array<String>, String] queries List of queries or a query
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query
+    #
     # @return Returns truthy if the `queries` all match at least one view
     # @raise [ArgumentError] If given an invalid list of queries
     def views_exist?(*queries)
       if queries.nil? || queries.any?(&:nil?)
         raise ArgumentError, 'Query cannot be nil'
@@ -289,11 +300,11 @@
     end
 
     # Expect `query` to match at least one view. Raise an exception if it does
     # not.
     #
-    # @param [String] query Query to match view
+    # @param [String, Hash, Calabash::Query] query Query to match a view
     # @raise [ArgumentError] If given an invalid `query`
     # @raise [ViewNotFoundError] If `query` does not match at least one view
     def expect_view(query)
       if query.nil?
         raise ArgumentError, 'Query cannot be nil'
@@ -301,18 +312,21 @@
 
       unless view_exists?(query)
         raise ViewNotFoundError,
               "No view matched #{parse_query_list(query)}"
       end
+
+      true
     end
 
     alias_method :view_should_exist, :expect_view
 
     # Expect `queries` to each match at least one view. Raise an exception if
     # they do not.
     #
-    # @param [String] queries List of queries or a query
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query.
     # @raise [ArgumentError] If given an invalid list of queries
     # @raise [ViewNotFoundError] If `queries` do not all match at least one
     #   view.
     def expect_views(*queries)
       if queries.nil? || queries.any?(&:nil?)
@@ -321,33 +335,39 @@
 
       unless views_exist?(*queries)
         raise ViewNotFoundError,
               "Not all queries #{parse_query_list(queries)} matched a view"
       end
+
+      true
     end
 
     alias_method :views_should_exist, :expect_views
 
     # Expect `query` to match no views. Raise an exception if it does.
     #
+    # @param [String, Hash, Calabash::Query] query Query to match a view
     # @raise [ArgumentError] If given an invalid `query`
     # @raise [ViewFoundError] If `query` matches any views.
     def do_not_expect_view(query)
       if query.nil?
         raise ArgumentError, 'Query cannot be nil'
       end
 
       if view_exists?(query)
         raise ViewFoundError, "A view matched #{parse_query_list(query)}"
       end
+
+      true
     end
 
     alias_method :view_should_not_exist, :do_not_expect_view
 
     # Expect `queries` to each match no views. Raise an exception if they do.
     #
-    # @param [Array<String>, String] queries List of queries or a query
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query.
     # @raise [ArgumentError] If given an invalid list of queries
     # @raise [ViewFoundError] If one of `queries` matched any views
     def do_not_expect_views(*queries)
       if queries.nil? || queries.any?(&:nil?)
         raise ArgumentError, 'Query cannot be nil'
@@ -355,9 +375,11 @@
 
       if queries.map{|query| view_exists?(query)}.any?
         raise ViewFoundError,
               "Some views matched #{parse_query_list(queries)}"
       end
+
+      true
     end
 
     alias_method :views_should_not_exist, :do_not_expect_views
 
     # Waits for a view containing `text`.