calabash 2.0.0.pre2 → 2.0.0.pre3

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

@@ -110,6 +110,7 @@ module Calabash
         end.call(self)
       end
 
+      # @!visibility private
       def query_for_keyboard
         keyboard_waiter.query(KEYBOARD_QUERY)
       end
@@ -120,6 +121,7 @@ module Calabash
         keyboard_waiter.query(KEYBOARD_KEY_QUERY)
       end
 
+      # @!visibility private
       def query_for_text_of_first_responder(query)
         result = keyboard_waiter.query("#{query} isFirstResponder:1", :text)
         if result.empty?

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

@@ -4,6 +4,7 @@ module Calabash
     # @!visibility private
     module RotationMixin
 
+      # @!visibility private
       def rotate(direction)
         # If we are in the console, we want to be able to rotate without
         # calling start_app.  However, if the Device in the console has not

data/lib/calabash/ios/device/routes/condition_route_mixin.rb

@@ -5,6 +5,7 @@ module Calabash
       # @!visibility private
       module ConditionRouteMixin
 
+        # @!visibility private
         def condition_route(condition, timeout, query)
           request = make_condition_request(condition, timeout, query)
           response = route_post_request(request)

data/lib/calabash/ios/device/routes/map_route_mixin.rb

@@ -5,6 +5,7 @@ module Calabash
       # @!visibility private
       module MapRouteMixin
 
+        # @!visibility private
         def map_route(query, method_name, *method_args)
           request = make_map_request(query, method_name, *method_args)
           response = route_post_request(request)

data/lib/calabash/ios/device/routes/response_parser.rb

@@ -6,6 +6,7 @@ module Calabash
       # @!visibility private
       module ResponseParser
 
+        # @!visibility private
         def parse_response_body(response)
           body = response.body
           begin

data/lib/calabash/ios/device/routes/uia_route_mixin.rb

@@ -9,6 +9,7 @@ module Calabash
         require 'run_loop'
         require 'edn'
 
+        # @!visibility private
         def uia_route(command)
           unless run_loop
             if defined?(IRB)
@@ -49,6 +50,49 @@ module Calabash
           end
         end
 
+        # @!visibility private
+        def uia_serialize_and_call(uia_command, *query_args)
+          command = uia_serialize_command(uia_command, *query_args)
+          result = uia_route(command)
+          result.first
+        end
+
+        # @!visibility private
+        # @todo Extract argument consing and unit test
+        def uia_query_then_make_javascript_calls(uia_command, query_parts, *javascript_parts)
+          if javascript_parts.empty?
+            uia_serialize_and_call(uia_command, *query_parts)
+          else
+            javascript_command = uia_serialize_command(uia_command, *query_parts)
+
+            javascript_args = []
+            javascript_parts.each do |invocation|
+              javascript_args << case invocation
+                when Symbol
+                  "#{invocation}()"
+                when Hash
+                  method = invocation.keys.first
+                  method_args = invocation[method]
+
+                  if method_args.is_a?(Array)
+                    serialized_args = (method_args.map &:to_json).join(',')
+                  else
+                    serialized_args = method_args.to_json
+                  end
+
+                  "#{method}(#{serialized_args})"
+                else
+                  raise Calabash::IOS::RouteError,
+                        "Invalid invocation spec #{invocation}"
+              end
+            end
+            command = "#{javascript_command}.#{javascript_args.join('.')}"
+
+            result = uia_route(command)
+            result.first
+          end
+        end
+
         private
 
         UIA_STRATEGIES = [:preferences, :host, :shared_element]
@@ -159,12 +203,6 @@ module Calabash
           end
         end
 
-        def uia_serialize_and_call(uia_command, *query_args)
-          command = uia_serialize_command(uia_command, *query_args)
-          result = uia_route(command)
-          result.first
-        end
-
         # @todo Verify this is the correct way to escape '\n in string
         def uia_escape_string(string)
           Calabash::Text.escape_single_quotes(string).gsub("\n", "\\\\n")

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

@@ -3,6 +3,7 @@ module Calabash
     # @!visibility private
     module TextMixin
 
+      # @!visibility private
       def enter_text(text)
         wait_for_keyboard(Calabash::Wait.default_options[:timeout])
         existing_text = text_from_keyboard_first_responder
@@ -10,6 +11,7 @@ module Calabash
         uia_type_string(text, options)
       end
 
+      # @!visibility private
       def _enter_text_in(query, text)
         _tap(query)
         enter_text(text)

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

@@ -43,6 +43,7 @@ module Calabash
 
       private
 
+      # @!visibility private
       def uia_type_string_handler(string, escaped_string, existing_text, result, logger)
         UIATypeStringHandler.new(string,
                                  escaped_string,
@@ -73,6 +74,7 @@ module Calabash
           @logger = logger
         end
 
+        # @!visibility private
         def self.escape_backslashes_in_string(string)
           return string if string.index(/\\/)
 
@@ -95,10 +97,12 @@ module Calabash
           result['value']
         end
 
+        # @!visibility private
         def log(message)
           logger.log(Color.blue(message), :info)
         end
 
+        # @!visibility private
         def log_preamble
           log('When typing:')
           log("   raw string: #{string}")
@@ -106,6 +110,7 @@ module Calabash
           log("existing text: #{existing_text}")
         end
 
+        # @!visibility private
         def log_epilogue
           log("       result: #{result}")
           log('')
@@ -113,6 +118,7 @@ module Calabash
           log('https://github.com/calabash/calabash-ios/issues/374')
         end
 
+        # @!visibility private
         def handle_result
           the_status = status
           if the_status == 'error'
@@ -130,6 +136,7 @@ module Calabash
           end
         end
 
+        # @!visibility private
         def handle_error
           log_preamble
           if result.has_key? 'value'
@@ -161,6 +168,7 @@ module Calabash
           end
         end
 
+        # @!visibility private
         def handle_success_with_incident
           log_preamble
           if value.nil?
@@ -176,6 +184,7 @@ module Calabash
           false
         end
 
+        # @!visibility private
         def handle_unknown_status
           log_preamble
           log("receive response with an unknown value for 'status' key: '#{status}'")

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

@@ -4,6 +4,7 @@ module Calabash
     # @!visibility private
     module UIAMixin
 
+      # @!visibility private
       def evaluate_uia(script)
         uia_route(script)
       end

data/lib/calabash/ios/device.rb

@@ -18,6 +18,7 @@ module Calabash
     require 'calabash/ios/device/uia_keyboard_mixin'
     require 'calabash/ios/device/text_mixin'
     require 'calabash/ios/device/uia_mixin'
+    require 'calabash/ios/device/ipad_1x_2x_mixin'
     require 'calabash/ios/device/device_implementation'
 
   end

data/lib/calabash/ios/interactions.rb

@@ -1,7 +1,36 @@
 module Calabash
   module IOS
-    # @!visibility private
+
+    # Interactions with your app that are specific to iOS
     module Interactions
+
+      # @!visibility private
+      # Sends app to background. Simulates pressing the home button.
+      #
+      # @note Cannot be more than 60 seconds.
+      #
+      # @param [Numeric] seconds The number of seconds to keep the app
+      #   in the background
+      # @raise [ArgumentError] If number of seconds is less than 1 and more
+      #   than 60 seconds.
+      def _send_current_app_to_background(seconds)
+        unless (1..60).member?(seconds)
+          raise ArgumentError,
+            "Number of seconds: '#{seconds}' must be between 1 and 60"
+        end
+
+        javascript = %Q(
+          var x = target.deactivateAppForDuration(#{seconds});
+          var MAX_RETRY=5, retry_count = 0;
+          while (!x && retry_count < MAX_RETRY) {
+            x = target.deactivateAppForDuration(#{seconds});
+            retry_count += 1
+          };
+          x
+        )
+        uia(javascript)
+      end
+
       # @!visibility private
       def _evaluate_javascript_in(query, javascript)
         query(query, calabashStringByEvaluatingJavaScript: javascript)

data/lib/calabash/ios/runtime.rb

@@ -63,6 +63,14 @@ module Calabash
       end
 
       # Is the device under test an iPhone 3.5in?
+      #
+      # @note If the app under test is an iPhone app emulated on an iPad then
+      #  the form factor will _always_ be 'iphone 3.5.in'.  If you need to
+      #  branch on the actual device the app is running on, use the #ipad?
+      #  method.
+      #
+      # @see #iphone_app_emulated_on_ipad?
+      # @see #ipad?
       def iphone_35in?
         Calabash::IOS::Device.default.form_factor == 'iphone 3.5in'
       end

data/lib/calabash/ios.rb

@@ -31,6 +31,7 @@ module Calabash
     require 'calabash/ios/runtime'
     require 'calabash/ios/gestures'
     require 'calabash/ios/slider'
+    require 'calabash/ios/date_picker'
 
     include Calabash::IOS::Conditions
     include Calabash::IOS::Orientation
@@ -41,6 +42,7 @@ module Calabash
     include Calabash::IOS::Runtime
     include Calabash::IOS::Gestures
     include Calabash::IOS::Slider
+    include Calabash::IOS::DatePicker
 
   end
 end

data/lib/calabash/life_cycle.rb

@@ -1,4 +1,12 @@
 module Calabash
+
+  # Methods for managing an app's life cycle.
+  #
+  # The life cycle of an app includes:
+  #  * installing / uninstalling
+  #  * stopping / starting
+  #  * clearing the application data
+  #  * sending the application to background and resuming it
   module LifeCycle
     # Start the given application (and its test-server) on the port of
     # {Calabash::Defaults#default_server Calabash.default_server}.
@@ -122,11 +130,20 @@ module Calabash
     end
 
     # Sends the current app to the background and resumes it after
-    # `for_seconds`. This should not exceed 60 seconds for iOS.
+    # `for_seconds`.
+    #
+    # On iOS, `for_seconds` must be between 1 and 60 seconds.
+    #
+    # On iOS the _current app_ is the app under test (your app).
     #
-    # On Android you can control the app lifecycle more granularly using
+    # On Android you can control the app lifecycle more granularity using
     # {Calabash::Android::Interactions#go_home \#go_home} and
     # {Calabash::Android::LifeCycle#resume_app \#resume_app}.
+    #
+    # @param [Numeric] for_seconds How long to keep the app to the background.
+    #
+    # @raise [ArgumentError] On iOS, if number of seconds is less than 1 and
+    # more than 60 seconds.
     def send_current_app_to_background(for_seconds = 10)
       _send_current_app_to_background(for_seconds)
 

data/lib/calabash/location.rb

@@ -1,6 +1,8 @@
 require 'geocoder'
 
 module Calabash
+
+  # An API for setting the location of your app.
   module Location
     # Simulates gps location of the device/simulator.
     # @note Seems UIAutomation is broken here on physical devices on iOS 7.1

data/lib/calabash/page.rb

@@ -1,8 +1,17 @@
 module Calabash
+
+  # A base class for the Page Object Model (POM) or Page Object Pattern.
+  #
+  # We recommend the POM for testing cross-platform apps.
+  #
+  # We have a great examples of using the POM in the Calabash 2.0 repository.
+  #   * https://github.com/calabash/calabash/tree/develop/samples/wordpress
+  #   * https://github.com/calabash/calabash/tree/develop/samples/shared-page-logic
   class Page
     # For auto-completion
     include Calabash
 
+    # @!visibility private
     def self.inherited(subclass)
       # Define the page into global scope
       full_name = subclass.name
@@ -49,14 +58,18 @@ module Calabash
 
     private_class_method :new
 
+    # @!visibility private
     def initialize(world)
       @world = world
     end
 
+    # A query that distinguishes your page.
+    # @return [String, Hash, Calabash::Query] A query.
     def trait
       raise 'Implement your own trait'
     end
 
+    # Waits for the page trait to appear.
     def await(options={})
       wait_for_view(trait, options)
     end

data/lib/calabash/patch.rb

@@ -3,6 +3,7 @@ module Calabash
   module Patch
     require 'calabash/patch/array'
 
+    # @!visibility private
     def self.apply_patches!
       modules = Patch.constants(false)
 

data/lib/calabash/utility.rb

@@ -5,6 +5,7 @@ module Calabash
 
   end
 
+  # Utility methods for testing.
   module Utility
 
     # @!visibility private
@@ -39,17 +40,16 @@ module Calabash
     alias_method :pct, :percent
 
     # A convenience method for creating a coordinate hash that that can be
-    # passed to gestures.
+    # passed to the tap_coordinate gesture.
     #
     # @example
     #  # These are equivalent.
-    #  tap(query, offset: coordinate(20, 50))
-    #  tap(query, offset: {x: 20, y: 50})
+    #  tap_coordinate(coordinate(20, 50)
+    #  tap_coordinate({x: 20, y: 50})
     #
     # @param [Number] x The value of the x.
     # @param [Number] y The value of the y.
     # @return [Hash] Representing the given values.
-    # @!visibility private
     def coordinate(x, y)
       {x: x, y: y}
     end

data/lib/calabash/version.rb

@@ -1,5 +1,5 @@
 module Calabash
 
   # @!visibility private
-  VERSION = '2.0.0.pre2'
+  VERSION = '2.0.0.pre3'
 end

data/lib/calabash/wait.rb

@@ -27,10 +27,14 @@ module Calabash
             screenshot_on_error: true
         }
 
+    # Returns the default wait options.
+    # @return [Hash] Key/value pairs describing the wait options.
     def self.default_options
       @@default_options
     end
 
+    # Sets the default wait options.
+    # @param [Hash] value The new default wait options.
     def self.default_options=(value)
       @@default_options = value
     end

data/lib/calabash.rb

@@ -241,6 +241,7 @@ module Calabash
       @@has_set_embedding_context
     end
 
+    # @!visibility private
     def self.new_embed_method(method)
       define_method(:embed) do |*args|
         method.call(*args)
@@ -249,6 +250,7 @@ module Calabash
       @@has_set_embedding_context = true
     end
 
+    # @!visibility private
     def embed(*_)
       Logger.warn 'Embed is not available in this context. Will not embed.'
     end
@@ -264,9 +266,9 @@ unless Object.const_defined?(:IOS)
 end
 
 if Calabash::Environment::DEBUG_CALLED_METHODS
-  $stdout.puts "#{Calabash::Color.red("Will print every Calabash method called!")}"
-  $stdout.puts "#{Calabash::Color.red("Warning: This might slow down your test drastically")}"
-  $stdout.puts "#{Calabash::Color.red("and is an experimental feature.")}"
+  $stdout.puts "#{Calabash::Color.red('Will print every Calabash method called!')}"
+  $stdout.puts "#{Calabash::Color.red('Warning: This might slow down your test drastically')}"
+  $stdout.puts "#{Calabash::Color.red('and is an experimental feature.')}"
 
   calabash_file = Calabash.method(:extended).source_location.first
   $__calabash_dir_name = File.dirname(calabash_file)
@@ -274,7 +276,7 @@ if Calabash::Environment::DEBUG_CALLED_METHODS
   trace_func = lambda do |event, file, line, id, binding, classname|
     if event == 'call'
       if classname.to_s.split('::').first == 'Calabash'
-        binding_caller_locations = binding.eval("caller_locations")
+        binding_caller_locations = binding.eval('caller_locations')
         files = binding_caller_locations[3..-1].map(&:path)
 
         calabash_not_in_stacktrace = files.none? do |file|