calabash 2.0.0.pre1 → 2.0.0.prelegacy2

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/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/text.rb

@@ -73,43 +73,6 @@ module Calabash
         Device.default.split_keyboard_visible?
       end
 
-      # Returns true if there is a visible keyboard.
-      #
-      # @return [Boolean] Returns true if there is a visible keyboard.
-      def keyboard_visible?
-        docked_keyboard_visible? || undocked_keyboard_visible? || split_keyboard_visible?
-      end
-
-      # Waits for a keyboard to appear.
-      #
-      # @see Calabash::Wait.default_options
-      #
-      # @param [Number] timeout How long to wait for the keyboard.
-      # @raise [Calabash::Wait::TimeoutError] Raises error if no keyboard
-      #  appears.
-      def wait_for_keyboard(timeout=nil)
-        keyboard_timeout = keyboard_wait_timeout(timeout)
-        message = "Timed out after #{keyboard_timeout} seconds waiting for the keyboard to appear"
-        wait_for(message, timeout: keyboard_timeout) do
-          keyboard_visible?
-        end
-      end
-
-      # Waits for the keyboard to disappear.
-      #
-      # @see Calabash::Wait.default_options
-      #
-      # @param [Number] timeout How log to wait for the keyboard to disappear.
-      # @raise [Calabash::Wait::TimeoutError] Raises error if any keyboard is
-      #  visible after the `timeout`.
-      def wait_for_no_keyboard(timeout=nil)
-        keyboard_timeout = keyboard_wait_timeout(timeout)
-        message = "Timed out after #{keyboard_timeout} seconds waiting for the keyboard to disappear"
-        wait_for(message, timeout: keyboard_timeout) do
-          !keyboard_visible?
-        end
-      end
-
       # Touches the keyboard action key.
       #
       # The action key depends on the keyboard.  Some examples include:
@@ -137,6 +100,11 @@ module Calabash
         Device.default.uia_route("uia.keyboard().typeString('#{char_sequence}')")
       end
 
+      # @!visibility private
+      def _keyboard_visible?
+        docked_keyboard_visible? || undocked_keyboard_visible? || split_keyboard_visible?
+      end
+
       # Touches the keyboard delete key.
       #
       # The 'delete' key difficult to find and touch because its behavior
@@ -242,14 +210,6 @@ module Calabash
               #'International' => nil,
               #'More' => nil,
           }
-
-      def keyboard_wait_timeout(timeout)
-        if timeout.nil?
-          Calabash::Gestures::DEFAULT_GESTURE_WAIT_TIMEOUT
-        else
-          timeout
-        end
-      end
     end
   end
 end

data/lib/calabash/legacy.rb

@@ -0,0 +1,7 @@
+module Calabash
+  class Application
+    def md5_checksum
+      'samplechecksum'
+    end
+  end
+end

data/lib/calabash/lib/skeleton/config/cucumber.yml

@@ -1,6 +1,4 @@
 # config/cucumber.yml
 ##YAML Template
 ---
-# Platform
-android: PLATFORM=android -r features
-ios: PLATFORM=ios -r features
+default: -r features

data/lib/calabash/lib/skeleton/features/support/env.rb

@@ -1,7 +1,21 @@
 require 'calabash'
+require 'calabash/android/application'
+require 'calabash/ios/application'
 
 platform = ENV['PLATFORM']
 
+unless platform
+  application = Calabash::Application.default_from_environment
+
+  if application.android_application?
+    platform = 'android'
+  elsif application.ios_application?
+    platform = 'ios'
+  else
+    raise "Application '#{application}' is neither an Android app or an iOS app"
+  end
+end
+
 case platform
   when 'android'
     require 'calabash/android'
@@ -26,7 +40,7 @@ case platform
         [
             'ERROR! Unable to start the cucumber test:',
             message,
-            "Use the profile 'android' or 'ios', or run cucumber using $ calabash run"
+            "Run cucumber with the ENV variable 'CAL_APP', or run cucumber using $ calabash run"
         ]
 
     Calabash::Logger.error(failure_messages.join("\n"))

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/query_result.rb

@@ -61,6 +61,10 @@ module Calabash
 
     # @!visibility private
     def ensure_in_bounds(index)
+      unless index.is_a?(Numeric)
+        return true
+      end
+
       if empty?
         raise IndexError, "Query result is empty"
       end

data/lib/calabash/text.rb

@@ -93,6 +93,45 @@ module Calabash
       Text.escape_single_quotes(string)
     end
 
+    # Returns true if there is a visible keyboard.
+    # On Android, if a physical keyboard is connected, this method will always
+    # return true.
+    #
+    # @return [Boolean] Returns true if there is a visible keyboard.
+    def keyboard_visible?
+      _keyboard_visible?
+    end
+
+    # Waits for a keyboard to appear.
+    #
+    # @see Calabash::Wait.default_options
+    #
+    # @param [Number] timeout How long to wait for the keyboard.
+    # @raise [Calabash::Wait::TimeoutError] Raises error if no keyboard
+    #  appears.
+    def wait_for_keyboard(timeout=nil)
+      keyboard_timeout = keyboard_wait_timeout(timeout)
+      message = "Timed out after #{keyboard_timeout} seconds waiting for the keyboard to appear"
+      wait_for(message, timeout: keyboard_timeout) do
+        keyboard_visible?
+      end
+    end
+
+    # Waits for the keyboard to disappear.
+    #
+    # @see Calabash::Wait.default_options
+    #
+    # @param [Number] timeout How log to wait for the keyboard to disappear.
+    # @raise [Calabash::Wait::TimeoutError] Raises error if any keyboard is
+    #  visible after the `timeout`.
+    def wait_for_no_keyboard(timeout=nil)
+      keyboard_timeout = keyboard_wait_timeout(timeout)
+      message = "Timed out after #{keyboard_timeout} seconds waiting for the keyboard to disappear"
+      wait_for(message, timeout: keyboard_timeout) do
+        !keyboard_visible?
+      end
+    end
+
     # @!visibility private
     def _enter_text(text)
       abstract_method!
@@ -118,9 +157,23 @@ module Calabash
       abstract_method!
     end
 
+    # @!visibility private
+    def _keyboard_visible?
+      abstract_method!
+    end
+
     # @!visibility private
     def self.escape_single_quotes(string)
       string.gsub("'", "\\\\'")
     end
+
+    # @!visibility private
+    def keyboard_wait_timeout(timeout)
+      if timeout.nil?
+        Calabash::Gestures::DEFAULT_GESTURE_WAIT_TIMEOUT
+      else
+        timeout
+      end
+    end
   end
 end

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