calabash 1.2.1 → 1.9.9.pre1

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

@@ -0,0 +1,167 @@
+module Calabash
+  module IOS
+    # @!visibility private
+    #
+    # Gestures should wait for the views involved before performing the
+    # gesture.
+    #
+    # 1. Wait for the view or views.
+    # 2. Find the absolute coordinates of the gesture.
+    # 3. Pass the coordinates to the Calabash UIA offset API.
+    # 4. Return the views involved in the gesture as QueryResults.
+    #
+    # @todo Needs unit tests.
+    module GesturesMixin
+
+      def _tap(query, options={})
+        view_to_touch = _gesture_waiter.wait_for_view(query, options)
+
+        offset = uia_center_of_view(view_to_touch)
+
+        uia_serialize_and_call(:tapOffset, offset, options)
+
+        Calabash::QueryResult.create([view_to_touch], query)
+      end
+
+      def _double_tap(query, options={})
+        view_to_touch = _gesture_waiter.wait_for_view(query, options)
+
+        offset = uia_center_of_view(view_to_touch)
+
+        uia_serialize_and_call(:doubleTapOffset, offset, options)
+
+        Calabash::QueryResult.create([view_to_touch], query)
+      end
+
+      def _long_press(query, options={})
+
+        begin
+          _expect_valid_duration(options)
+        rescue ArgumentError => e
+          raise ArgumentError e
+        end
+
+        view_to_touch = _gesture_waiter.wait_for_view(query, options)
+
+        offset = uia_center_of_view(view_to_touch)
+
+        uia_serialize_and_call(:touchHoldOffset, options[:duration], offset)
+
+        Calabash::QueryResult.create([view_to_touch], query)
+      end
+
+      def _pan_between(query_from, query_to, options={})
+
+        begin
+          _expect_valid_duration(options)
+        rescue ArgumentError => e
+          raise ArgumentError e
+        end
+
+        from_view = _gesture_waiter.wait_for_view(query_from, options)
+        to_view = _gesture_waiter.wait_for_view(query_to, options)
+
+        from_offset = uia_center_of_view(from_view)
+        to_offset = uia_center_of_view(to_view)
+
+        uia_serialize_and_call(:panOffset, from_offset, to_offset, options)
+
+        {
+          :from => Calabash::QueryResult.create([from_view], query_from),
+          :to => Calabash::QueryResult.create([to_view], query_to)
+        }
+      end
+
+      # The default to and from for the pan_* methods are not good for iOS.
+      #
+      # * from: {x: 90, y: 50}
+      # *   to: {x: 10, y: 50}
+      #
+      # If the view has a UINavigationBar or UITabBar, the defaults will
+      # cause vertical gestures to start and/or end on one of these bars.
+      #
+      # dragInsideWithOptions broke in iOS 7, so the condition should really be
+      # `Device.default.simulator? && !Device.ios6?`, but I haven't checked on
+      # iOS 9 yet, so I will leave the condition out.
+      def _pan(query, from, to, options={})
+        if Device.default.simulator?
+          message = [
+                "Apple's UIAutomation `dragInsideWithOptions` API is broken for iOS > 7",
+                'If you are trying to scroll on a UITableView or UICollectionView, try using the scroll_* methods'
+          ].join("\n")
+
+          raise message
+        end
+
+        begin
+          _expect_valid_duration(options)
+        rescue ArgumentError => e
+          raise ArgumentError e
+        end
+
+        view_to_pan = _gesture_waiter.wait_for_view(query, options)
+
+        rect = view_to_pan['rect']
+
+        from_x = rect['width'] * (from[:x]/100.0)
+        from_y = rect['height'] * (from[:y]/100.0)
+        from_offset = percent(from_x, from_y)
+
+        to_x = rect['width'] * (to[:x]/100.0)
+        to_y = rect['height'] * (to[:y]/100.0)
+        to_offset = percent(to_x, to_y)
+
+        uia_serialize_and_call(:panOffset, from_offset, to_offset)
+
+        Calabash::QueryResult.create([view_to_pan], query)
+      end
+
+      private
+
+      # !@visibility private
+      #
+      # Unlike the Calabash Android server, the iOS server does not wait
+      # before gestures, so the client must do the waiting.  The _gesture_waiter
+      # allows access to query, wait, etc. without having to include all of
+      # Calabash in this module.
+      #
+      # @todo Replace with waiting on the iOS Server
+      def _gesture_waiter
+        lambda do |reference_to_self|
+          Class.new do
+            # world_for_device will return a copy of the module Calabash::IOS,
+            # which has redefined Calabash.default_device to reference this
+            # device. We should not keep a reference to gesture_waiter
+            # because of this, as the user might change a constant or class
+            # variable in Calabash.
+            include reference_to_self.send(:world_for_device)
+
+            define_method(:query) do |query, *args|
+              reference_to_self.map_route(query, :query, *args)
+            end
+
+            def to_s
+              '#<Calabash::IOS::GestureWaiter>'
+            end
+
+            def inspect
+              to_s
+            end
+          end.new
+        end.call(self)
+      end
+
+      def _expect_valid_duration(options)
+        duration = options[:duration].to_f
+        if duration < 0.5 || duration > 60
+          message = [
+                "Expected :duration 0.5 <= '#{duration}' <= 60",
+                'On iOS, gesture durations must be between 0.5 and 60 seconds.',
+                'This is a limitation enforced by the UIAutomation API.'
+          ].join("\n")
+          raise ArgumentError, message
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+module Calabash
+  module IOS
+
+    # @!visibility private
+    module KeyboardMixin
+
+      # Returns true if a docked keyboard is visible.
+      #
+      # A docked keyboard is pinned to the bottom of the view.
+      #
+      # Keyboards on the iPhone and iPod are docked.
+      def docked_keyboard_visible?
+        query_result = query_for_keyboard
+        return false if query_result.empty?
+
+        return true if device_family_iphone?
+
+        # iPad
+        rect = query_result.first['rect']
+        orientation = status_bar_orientation.to_sym
+        case orientation
+          when :left then
+            rect['center_x'] == 592 && rect['center_y'] == 512
+          when :right then
+            rect['center_x'] == 176 && rect['center_y'] == 512
+          when :up then
+            rect['center_x'] == 384 && rect['center_y'] == 132
+          when :down then
+            rect['center_x'] == 384 && rect['center_y'] == 892
+          else
+            false
+        end
+      end
+
+      # Returns true if an undocked keyboard is visible.
+      #
+      # A undocked keyboard is floats in the middle of the view.
+      #
+      # Only iPad keyboards can be undocked.
+      def undocked_keyboard_visible?
+        return false if device_family_iphone?
+
+        return false if query_for_keyboard.empty?
+
+        not docked_keyboard_visible?
+      end
+
+      # Returns true if a split keyboard is visible.
+      #
+      # A split keyboard is floats in the middle of the view and is split to
+      # allow faster thumb typing
+      #
+      # Only iPad keyboards can be split.
+      def split_keyboard_visible?
+        return false if device_family_iphone?
+        query_for_keyboard_keys.count > 0 && query_for_keyboard.empty?
+      end
+
+      # Returns true if there is a visible keyboard.
+      def keyboard_visible?
+        docked_keyboard_visible? || undocked_keyboard_visible? || split_keyboard_visible?
+      end
+
+      # Returns the the text in the first responder.
+      #
+      # The first responder will be the UITextField or UITextView instance
+      # that is associated with the visible keyboard.
+      #
+      # Returns empty string if no textField or textView elements are found to be
+      # the first responder.  Otherwise, it will return the text in the
+      # UITextField or UITextField that is associated with the keyboard.
+      def text_from_keyboard_first_responder
+        raise 'There must be a visible keyboard.' unless keyboard_visible?
+
+        text = ''
+        ['textField', 'textView'].each do |ui_class|
+          text = query_for_text_of_first_responder(ui_class)
+          if text.nil?
+            text = ''
+          else
+            break
+          end
+        end
+        text
+      end
+
+      private
+
+      # @!visibility private
+      # Returns a query string for detecting a keyboard.
+      KEYBOARD_QUERY = "view:'UIKBKeyplaneView'"
+      KEYBOARD_KEY_QUERY = "view:'UIKBKeyView'"
+
+      def device_family_iphone?
+        family = device_family
+        family == 'iPhone'
+      end
+
+      # Unlike the Calabash Android server, the iOS server does not wait
+      # before gestures.  We need to do this in the client for now.
+      # @todo Replace with waiting on the iOS Server
+      def keyboard_waiter
+        @keyboard_waiter ||= lambda do |reference_to_self|
+          Class.new do
+            include Calabash::Wait
+            define_method(:query) do |query, *args|
+              reference_to_self.map_route(query, :query, *args)
+            end
+          end.new
+        end.call(self)
+      end
+
+      def query_for_keyboard
+        keyboard_waiter.query(KEYBOARD_QUERY)
+      end
+
+      # When the split keyboard is showing, KEYBOARD_QUERY will return no
+      # results.  UIKBKeyView are the individual key views on the keyboard.
+      def query_for_keyboard_keys
+        keyboard_waiter.query(KEYBOARD_KEY_QUERY)
+      end
+
+      def query_for_text_of_first_responder(query)
+        result = keyboard_waiter.query("#{query} isFirstResponder:1", :text)
+        if result.empty?
+          nil
+        else
+          result.first
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,266 @@
+module Calabash
+  module IOS
+
+    # @!visibility private
+    # A mixin for IOS::Device that provides methods that users can override
+    # to use a third-party tool like `ideviceinstaller` or `ios-deploy` to
+    # manage apps on physical devices.
+    #
+    #
+    # Calabash cannot manage apps on physical devices.  There are third-party
+    # tools you can use to manage apps on devices.  Two popular tools are
+    # ideviceinstaller and ios-deploy.  Both can be installed using homebrew.
+    #
+    # To integrate these tools, Calabash provides several methods for you to
+    # override in your project.  In your `features/support/` directory, you
+    # can patch Calabash::IOS::Device with your own implementation of these
+    # methods.  The five methods to override are:
+    #
+    # 1. app_installed_on_physical_device?
+    # 2. install_app_on_physical_device
+    # 3. ensure_app_installed_on_physical_device
+    # 4. clear_app_data_on_physical_device
+    # 5. uninstall_app_on_physical_device
+    #
+    #
+    # ```
+    #  # features/support/ideviceinstaller.rb
+    #
+    #  require 'fileutils'
+    #  class Calabash::IOS::Device
+    #
+    #    def app_installed_on_physical_device?(application, device_udid)
+    #      out = `/usr/local/bin/ideviceinstaller --udid #{device_udid} --list-apps`
+    #      out.split(/\s/).include? application.identifier
+    #    end
+    #
+    #    def install_app_on_physical_device(application, device_udid)
+    #
+    #      if app_installed_on_physical_device?(application, device_udid)
+    #        uninstall_app_on_physical_device(application, device_udid)
+    #      end
+    #
+    #      args =
+    #            [
+    #                  '--udid', device_udid,
+    #                  '--install', application.path
+    #            ]
+    #
+    #      log = FileUtils.touch('./ideviceinstaller.log')
+    #      system('/usr/local/bin/ideviceinstaller', *args, {:out => log})
+    #
+    #      exit_code = $?
+    #      unless exit_code == 0
+    #        raise "Could not install the app (#{exit_code}).  See #{File.expand_path(log)}"
+    #      end
+    #      true
+    #    end
+    #
+    #    def uninstall_app_on_physical_device(application, device_udid)
+    #
+    #      if app_installed_on_physical_device?(application, device_udid)
+    #
+    #        args =
+    #              [
+    #                    '--udid', device_udid,
+    #                    '--uninstall', application.identifier
+    #              ]
+    #
+    #        log = FileUtils.touch('./ideviceinstaller.log')
+    #        system('/usr/local/bin/ideviceinstaller', *args, {:out => log})
+    #
+    #        exit_code = $?
+    #        unless exit_code == 0
+    #          raise "Could not uninstall the app (#{exit_code}).  See #{File.expand_path(log)}"
+    #        end
+    #      end
+    #      true
+    #    end
+    #
+    #    def ensure_app_installed_on_physical_device(application, device_udid)
+    #      unless app_installed_on_physical_device?(application, device_udid)
+    #        install_app_on_physical_device(application, device_udid)
+    #      end
+    #      true
+    #    end
+    #
+    #    # The only way to clear the data is to uninstall the app.
+    #    def clear_app_data_on_physical_device(application, device_udid)
+    #      if app_installed_on_physical_device?(application, device_udid)
+    #        install_app_on_physical_device(application, device_udid)
+    #      end
+    #      true
+    #    end
+    #  end
+    # ```
+    #
+    # For a real-world example of a ruby wrapper around the ideviceinstaller
+    # command-line tool, see https://github.com/calabash/ios-smoke-test-app.
+    #
+    # @see #app_installed_on_physical_device?
+    # @see #install_app_on_physical_device
+    # @see #ensure_app_installed_on_physical_device
+    # @see #clear_app_data_on_physical_device
+    # @see #uninstall_app_on_physical_device
+    #
+    # @see http://brew.sh/
+    # @see https://github.com/libimobiledevice/ideviceinstaller
+    # @see https://github.com/phonegap/ios-deploy
+    # @see https://github.com/calabash/ios-smoke-test-app/blob/master/CalSmokeApp/features/support/ideviceinstaller.rb
+    # @see https://github.com/blueboxsecurity/idevice
+    #
+    # For an real-world example of a ruby wrapper around the ideviceinstaller
+    # tool, see /blob/master/CalSmokeApp/features/support/ideviceinstaller.rb
+    module PhysicalDeviceMixin
+
+      # Install an app on physical device.  To fit into Calabash's app lifecycle
+      # model, implementations of this method must follow these rules:
+      #
+      # 1. If the app is installed, uninstall it, and then install it.
+      # 2. If the app cannot be uninstalled or installed, raise a StandardError.
+      #
+      # param [Calabash::IOS::Application] application The application to
+      #  to install.  The important methods on application are `path` and
+      #  `identifier`.
+      # @param [String] device_udid The identifier of the device to install the
+      #  application on.
+      #
+      # @return [Boolean] If the app was installed ont the device.
+      #
+      # @raise [Calabash::AbstractMethodError] If this method is not implemented
+      #  by the user.
+      def install_app_on_physical_device(application, device_udid)
+        logger.log('To install an ipa on a physical device, you must extend', :info)
+        logger.log('Calabash::IOS::Device and implement the #install_app_on_physical_device', :info)
+        logger.log('method that using a third-party tool to interact with physical devices.', :info)
+        logger.log('For an example of an implementation using ideviceinstaller, see:', :info)
+        logger.log('https://github.com/calabash/ios-smoke-test-app.', :info)
+        raise Calabash::AbstractMethodError,
+              'Device install_app_on_physical_device must be implemented by you.'
+      end
+
+      # Ensures that `application` is installed on a physical device.  To fit
+      # into Calabash's app lifecycle model, implementations of this method must
+      # follow these rules:
+      #
+      # 1. If the app is not installed, install it.
+      # 2. If the app is installed, return true
+      # 3. If the app cannot be installed, raise a StandardError.
+      #
+      # @param [Calabash::IOS::Application] application The application to
+      #  to install.  The important methods on application are `path` and
+      #  `identifier`.
+      # @param [String] device_udid The identifier of the device to install the
+      #  application on.
+      #
+      # @return [Boolean] If the app is installed on the physical_device.
+      #
+      # @raise [Calabash::AbstractMethodError] If this method is not implemented
+      #  by the user.
+      def ensure_app_installed_on_physical_device(application, device_udid)
+        logger.log('To check if an app installed on a physical device, you must extend', :info)
+        logger.log('Calabash::IOS::Device and implement the #ensure_app_installed_on_device', :info)
+        logger.log('method that using a third-party tool to interact with physical devices.', :info)
+        logger.log('For an example of an implementation using ideviceinstaller, see:', :info)
+        logger.log('https://github.com/calabash/ios-smoke-test-app.', :info)
+        raise Calabash::AbstractMethodError,
+              'Device ensure_app_installed_on_device must be implemented by you.'
+      end
+
+      # Clears the application's data from a physical device.  To fit into
+      # Calabash's app lifecycle model, implementations of this method must
+      # follow these rules:
+      #
+      # 1. The data in the applications sandbox must be reset to a good known
+      #    state.  What that means for your application is up to you to
+      #    decide.  Generally, this means you should remove _all_ files from
+      #    the application's sandbox.
+      # 2. If the data has been reset, return true.
+      # 3. If the app data cannot be cleared, raise a StandardError.
+      #
+      # Some kinds of user data are very difficult to clear.  For example,
+      # values stored in NSUserDefaults are not removed when an app is
+      # uninstalled.  The same is true for values stored in the Keychain.
+      #
+      # You might need to add logic in your Cucumber Before hooks to clear
+      # such data.
+      #
+      # @param [Calabash::IOS::Application] application The application to
+      #  to install.  The important methods on application are `path` and
+      #  `identifier`.
+      # @param [String] device_udid The identifier of the device to install the
+      #  application on.
+      #
+      # @return [Boolean] Return true if the application data was cleared.
+      #
+      # @raise [Calabash::AbstractMethodError] If this method is not implemented
+      #  by the user.
+      def clear_app_data_on_physical_device(application, device_udid)
+        logger.log('To clear app data on a physical device, you must extend', :info)
+        logger.log('Calabash::IOS::Device and implement the #clear_app_data_on_physical_device', :info)
+        logger.log('method using a third-party tool to interact with physical devices.', :info)
+        logger.log('For an example of an implementation using ideviceinstaller, see:', :info)
+        logger.log('https://github.com/calabash/ios-smoke-test-app.', :info)
+        raise Calabash::AbstractMethodError,
+              'Device clear_app_data_on_physical_device must be implemented by you.'
+      end
+
+      # Returns true if the application is installed on a physical device. To
+      # fit into Calabash's app lifecycle model, implementations of this method
+      # must follow these rules:
+      #
+      # 1. If the app is installed, this method must return true.
+      # 2. If the app is not installed, this method must return false.
+      # 3. If the state of the app on the device cannot be determined, raise
+      #    a RuntimeError.
+      #
+      # @param [Calabash::IOS::Application] application The application to
+      #  to install.  The important methods on application are `path` and
+      #  `identifier`.
+      # @param [String] device_udid The identifier of the device to install the
+      #  application on.
+      #
+      # @return [Boolean] Return true if the application is installed on the
+      #  device.
+      #
+      # @raise [Calabash::AbstractMethodError] If this method is not implemented
+      #  by the user.
+      def app_installed_on_physical_device?(application, device_udid)
+        logger.log('To determine if an app is installed on a physical device, you must extend', :info)
+        logger.log('Calabash::IOS::Device and implement the #app_installed_on_physical_device', :info)
+        logger.log('method using a third-party tool to interact with physical devices.', :info)
+        logger.log('For an example of an implementation using ideviceinstaller, see:', :info)
+        logger.log('https://github.com/calabash/ios-smoke-test-app.', :info)
+        raise Calabash::AbstractMethodError,
+              'Device app_installed_on_physical_device? must be implemented by you.'
+      end
+
+      # Uninstalls an application from a physical device. To fit into Calabash's
+      # app lifecycle model, implementations of this method must follow these
+      # rules:
+      #
+      # 1. Return true if the app was uninstalled.
+      # 2. Raise an error if the app cannot be uninstalled.
+      #
+      # @param [Calabash::IOS::Application] application The application to
+      #  to install.  The important methods on application are `path` and
+      #  `identifier`.
+      # @param [String] device_udid The identifier of the device to install the
+      #  application on.
+      #
+      # @return [Boolean] Return true if the application was uninstalled.
+      #
+      # @raise [Calabash::AbstractMethodError] If this method is not implemented
+      #  by the user.
+      def uninstall_app_on_physical_device(application, device_udid)
+        logger.log('To uninstall an ipa on a physical device, you must extend', :info)
+        logger.log('Calabash::IOS::Device and implement the #uninstall_app_on_physical_device', :info)
+        logger.log('method that using a third-party tool to interact with physical devices.', :info)
+        logger.log('For an example of an implementation using ideviceinstaller, see:', :info)
+        logger.log('https://github.com/calabash/ios-smoke-test-app.', :info)
+        raise Calabash::AbstractMethodError,
+              'Device uninstall_app_on_physical_device must be implemented by you.'
+      end
+    end
+  end
+end