calabash-cucumber 0.19.2 → 0.20.0

data/lib/calabash-cucumber/device_agent.rb

@@ -0,0 +1,346 @@
+module Calabash
+  module Cucumber
+
+    # An interface to the DeviceAgent Query and Gesture API.
+    #
+    # Unlike Calabash or UIA gestures, all DeviceAgent gestures wait for the
+    # uiquery to match a view.  This behavior match the Calabash 2.0 and
+    # Calabash 0.x Android behavior.
+    #
+    # This API is work in progress.  There are several methods that are
+    # experimental and several methods that will probably removed soon.
+    #
+    # Wherever possible use Core#query and the gestures defined in Core.
+    #
+    # TODO Screenshots
+    class DeviceAgent < BasicObject
+
+      # @!visibility private
+      #
+      # @param [RunLoop::DeviceAgent::Client] client The DeviceAgent client.
+      # @param [Cucumber::World] world The Cucumber World.
+      def initialize(client, world)
+        @client = client
+        @world = world
+      end
+
+      # @!visibility private
+      #
+      # @example
+      #  query({id: "login", :type "Button"})
+      #
+      #  query({marked: "login"})
+      #
+      #  query({marked: "login", type: "TextField"})
+      #
+      #  query({type: "Button", index: 2})
+      #
+      #  query({text: "Log in"})
+      #
+      #  query({id: "hidden button", :all => true})
+      #
+      #  # Escaping single quote is not necessary, but supported.
+      #  query({text: "Karl's problem"})
+      #  query({text: "Karl\'s problem"})
+      #
+      #  # Escaping double quote is not necessary, but supported.
+      #  query({text: "\"To know is not enough.\""})
+      #  query({text: %Q["To know is not enough."]})
+      #
+      # Querying for text with newlines is not supported yet.
+      #
+      # The query language supports the following keys:
+      # * :marked - accessibilityIdentifier, accessibilityLabel, text, and value
+      # * :id - accessibilityIdentifier
+      # * :type - an XCUIElementType shorthand, e.g. XCUIElementTypeButton =>
+      #   Button. See the link below for available types.  Note, however that
+      #   some XCUIElementTypes are not available on iOS.
+      # * :index - Applied after all other specifiers.
+      # * :all - Filter the result by visibility. Defaults to false. See the
+      #   discussion below about visibility.
+      #
+      # ### Visibility
+      #
+      # The rules for visibility are:
+      #
+      # 1. If any part of the view is visible, the visible.
+      # 2. If the view has alpha 0, it is not visible.
+      # 3. If the view has a size (0,0) it is not visible.
+      # 4. If the view is not within the bounds of the screen, it is not visible.
+      #
+      # Visibility is determined using the "hitable" XCUIElement property.
+      # XCUITest, particularly under Xcode 7, is not consistent about setting
+      # the "hitable" property correctly.  Views that are not "hitable" will
+      # still respond to gestures. For this reason, gestures use the
+      # element["rect"] for computing the touch point.
+      #
+      # Regarding rule #1 - this is different from the Calabash iOS and Android
+      # definition of visibility which requires the mid-point of the view to be
+      # visible.
+      #
+      # Please report visibility problems.
+      #
+      # ### Results
+      #
+      # Results are returned as an Array of Hashes.  The key/value pairs are
+      # similar to those returned by the Calabash iOS Server, but not exactly
+      # the same.
+      #
+      # ```
+      # [
+      #  {
+      #    "enabled": true,
+      #    "id": "mostly hidden button",
+      #    "hitable": true,
+      #    "rect": {
+      #      "y": 459,
+      #      "x": 24,
+      #      "height": 25,
+      #      "width": 100
+      #    },
+      #    "label": "Mostly Hidden",
+      #    "type": "Button",
+      #    "hit_point": {
+      #      "x": 25,
+      #      "y": 460
+      #    },
+      #  }
+      # ]
+      # ```
+      #
+      # @see http://masilotti.com/xctest-documentation/Constants/XCUIElementType.html
+      # @param [Hash] uiquery A hash describing the query.
+      # @return [Array<Hash>] An array of elements matching the `uiquery`.
+      def query(uiquery)
+        client.query(uiquery)
+      end
+
+      # Query for the center of a view.
+      #
+      # @see #query
+      #
+      # This method waits for the query to match at least one element.
+      #
+      # @param uiquery See #query
+      # @return [Hash] The center of first view matched by query.
+      #
+      # @raise [RuntimeError] if no view matches the uiquery after waiting.
+      def query_for_coordinate(uiquery)
+        fail_with_screenshot { client.query_for_coordinate(uiquery) }
+      end
+
+      # Perform a touch on the center of the first view matched the uiquery.
+      #
+      # This method waits for the query to match at least one element.
+      #
+      # @see #query
+      #
+      # @param [Hash] uiquery See #query for examples.
+      # @return [Array<Hash>] The view that was touched.
+      #
+      # @raise [RuntimeError] if no view matches the uiquery after waiting.
+      def touch(uiquery)
+        fail_with_screenshot { client.touch(uiquery) }
+      end
+
+      # Perform a touch at a coordinate.
+      #
+      # This method does not wait; the touch is performed immediately.
+      #
+      # @param [Hash] coordinate The coordinate to touch.
+      def touch_coordinate(coordinate)
+        client.touch_coordinate(coordinate)
+      end
+
+      # Perform a touch at a point.
+      #
+      # This method does not wait; the touch is performed immediately.
+      #
+      # @param [Hash] x the x coordinate
+      # @param [Hash] y the y coordinate
+      def touch_point(x, y)
+        client.touch_point(x, y)
+      end
+
+      # Perform a double tap on the center of the first view matched the uiquery.
+      #
+      # @see #query
+      #
+      # This method waits for the query to match at least one element.
+      #
+      # @param uiquery See #query
+      # @return [Array<Hash>] The view that was touched.
+      #
+      # @raise [RuntimeError] if no view matches the uiquery after waiting.
+      def double_tap(uiquery)
+        fail_with_screenshot { client.double_tap(uiquery) }
+      end
+
+      # Perform a two finger tap on the center of the first view matched the uiquery.
+      #
+      # @see #query
+      #
+      # This method waits for the query to match at least one element.
+      #
+      # @param uiquery See #query
+      # @return [Array<Hash>] The view that was touched.
+      #
+      # @raise [RuntimeError] if no view matches the uiquery after waiting.
+      def two_finger_tap(uiquery)
+        fail_with_screenshot { client.two_finger_tap(uiquery) }
+      end
+
+      # Perform a long press on the center of the first view matched the uiquery.
+      #
+      # @see #query
+      #
+      # This method waits for the query to match at least one element.
+      #
+      # @param uiquery See #query
+      # @param [Numeric] duration How long to press.
+      # @return [Array<Hash>] The view that was touched.
+      #
+      # @raise [RuntimeError] if no view matches the uiquery after waiting.
+      def long_press(uiquery, duration)
+        fail_with_screenshot { client.long_press(uiquery, {:duration => duration}) }
+      end
+
+      # Returns true if there is a keyboard visible.
+      #
+      # Scheduled for removal in 0.21.0.  Use Core#keyboard_visible?. If you
+      # find an example where Core#keyboard_visible? does not find visible
+      # keyboard, please report it.
+      #
+      # @deprecated 0.21.0 Use Core#keyboard_visible?
+      def keyboard_visible?
+        client.keyboard_visible?
+      end
+
+      # Enter text into the UITextInput view that is the first responder.
+      #
+      # The first responder is the view that is attached to the keyboard.
+      #
+      # Scheduled for removal in 0.21.0. Use Core#enter_text. If you find an
+      # example where Core#enter_text does not work, please report it.
+      #
+      # @param [String] text the text to enter
+      #
+      # @raise [RuntimeError] if there is no visible keyboard.
+      # @deprecated 0.21.0 Use Core#enter_text
+      def enter_text(text)
+        fail_with_screenshot { client.enter_text(text) }
+      end
+
+      # Enter text into the first view matched by uiquery.
+      #
+      # This method waits for the query to match at least one element and for
+      # the keyboard to appear.
+      #
+      # Scheduled for removal in 0.21.0. Use Core#enter_text_in. If you find an
+      # example where Core#enter_text_in does not work, please report it.
+      #
+      # @raise [RuntimeError] if no view matches the uiquery after waiting.
+      # @raise [RuntimeError] if the touch does not cause a keyboard to appear.
+      #
+      # @deprecated 0.21.0 Use Core#enter_text
+      def enter_text_in(uiquery, text)
+        fail_with_screenshot do
+          client.touch(uiquery)
+          client.wait_for_keyboard
+          client.enter_text(text)
+        end
+      end
+
+      # EXPERIMENTAL: This API may change.
+      #
+      # Is an alert generated by your Application visible?
+      #
+      # This does not detect SpringBoard alerts.
+      #
+      # @see #springboard_alert
+      #
+      # @see #springboard_alert
+      def app_alert_visible?
+        client.alert_visible?
+      end
+
+      # EXPERIMENTAL: This API may change.
+      #
+      # Queries for an alert generate by your Application.
+      #
+      # This does not detect SpringBoard alerts.
+      #
+      # @see #spring_board_alert
+      #
+      # @return [Array<Hash>] The view that was touched.
+      def app_alert
+        client.alert
+      end
+
+      # EXPERIMENTAL: This API may change.
+      #
+      # Is an alert generated by SpringBoard visible?
+      #
+      # This does not detect alerts generated by your Application.
+      #
+      # Examples of SpringBoard alerts are:
+      # * Privacy Alerts generated by requests for access to protected iOS
+      #   services like Contacts and Location,
+      # * "No SIM card"
+      # * iOS Update available
+      #
+      # @see #alert
+      def springboard_alert_visible?
+        client.springboard_alert_visible?
+      end
+
+      # EXPERIMENTAL: This API may change.
+      #
+      # Queries for an alert generated by SpringBoard.
+      #
+      # This does not detect alerts generated by your Application.
+      #
+      # Examples of SpringBoard alerts are:
+      # * Privacy Alerts generated by requests for access to protected iOS
+      #   services like Contacts and Location,
+      # * "No SIM card"
+      # * iOS Update available
+      #
+      # @see #alert
+      def springboard_alert
+        client.springboard_alert
+      end
+
+=begin
+PROTECTED
+=end
+      protected
+
+      # @!visibility private
+      def method_missing(name, *args, &block)
+        if world.respond_to?(name)
+          world.send(name, *args, &block)
+        else
+          super
+        end
+      end
+
+=begin
+PRIVATE
+=end
+      private
+
+      # @!visibility private
+      attr_reader :client, :world
+
+      # @!visibility private
+      def fail_with_screenshot(&block)
+        begin
+          block.call
+        rescue => e
+          world.send(:fail, e.message)
+        end
+      end
+    end
+  end
+end

data/lib/calabash-cucumber/dot_dir.rb

@@ -4,6 +4,7 @@ module Calabash
     module DotDir
       require "run_loop"
 
+      # @!visibility private
       def self.directory
         home = RunLoop::Environment.user_home_directory
         dir = File.join(home, ".calabash")

data/lib/calabash-cucumber/environment.rb

@@ -1,5 +1,6 @@
 module Calabash
   module Cucumber
+    # @!visibility private
     module Environment
 
       require "run_loop"

data/lib/calabash-cucumber/environment_helpers.rb

@@ -1,6 +1,3 @@
-require 'calabash-cucumber/device'
-require 'calabash-cucumber/launcher'
-
 module Calabash
   module Cucumber
 
@@ -12,6 +9,8 @@ module Calabash
     #  be set.
     module EnvironmentHelpers
 
+      require "calabash-cucumber/device"
+
       # Are the uia* methods available?
       #
       # @note
@@ -47,6 +46,7 @@ module Calabash
       #
       # @return [Calabash::Cucumber::Device] An instance of Device.
       def default_device
+        require "calabash-cucumber/launcher"
         l = Calabash::Cucumber::Launcher.launcher_if_used
         l && l.device
       end
@@ -133,6 +133,7 @@ module Calabash
       # @raise [RuntimeError] If the server cannot be reached.
       # @return [RunLoop::Version] The version of the iOS running on the device.
       def ios_version
+        require "run_loop/version"
         RunLoop::Version.new(_default_device_or_create.ios_version)
       end
 

data/lib/calabash-cucumber/http/http.rb

@@ -15,12 +15,15 @@ module Calabash
       def self.ping_app
         endpoint = Calabash::Cucumber::Environment.device_endpoint
         url = URI.parse(endpoint)
-
+        path = url.path
         http = Net::HTTP.new(url.host, url.port)
+        if url.scheme == "https"
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
         response = http.start do |sess|
-          sess.request(Net::HTTP::Get.new("version"))
+          sess.request(Net::HTTP::Get.new("#{path}version"))
         end
-
         body = nil
         success = response.is_a?(Net::HTTPSuccess)
         if success
@@ -112,4 +115,3 @@ If your app is crashing at launch, find a crash report to determine the cause.
     end
   end
 end
-

data/lib/calabash-cucumber/keyboard_helpers.rb

@@ -1,83 +1,21 @@
-require 'calabash-cucumber/core'
-require 'calabash-cucumber/tests_helpers'
-require 'calabash-cucumber/environment_helpers'
-
 module Calabash
   module Cucumber
 
-    # Raised when there is a problem involving a keyboard mode.  There are
-    # three keyboard modes:  docked, split, and undocked.
-    #
-    # All iPads support these keyboard modes, but the user can disable them
-    # in Settings.app.
-    #
-    # The iPhone 6+ family also supports keyboard modes, but Calabash does
-    # support keyboard modes on these devices.
-    class KeyboardModeError < StandardError; ; end
-
     # Collection of methods for interacting with the keyboard.
     #
     # We've gone to great lengths to provide the fastest keyboard entry possible.
-    #
-    # If you are having trouble with skipped or are receiving JSON octet
-    # errors when typing, you might be able to resolve the problems by slowing
-    # down the rate of typing.
-    #
-    # Example:  Use keyboard_enter_char + :wait_after_char.
-    #
-    # ```
-    # str.each_char do |char|
-    #   # defaults to 0.05 seconds
-    #   keyboard_enter_char(char, `{wait_after_char:0.5}`)
-    # end
-    # ```
-    #
-    # Example:  Use keyboard_enter_char + POST_ENTER_KEYBOARD
-    #
-    # ```
-    # $ POST_ENTER_KEYBOARD=0.1 bundle exec cucumber
-    # str.each_char do |char|
-    #   # defaults to 0.05 seconds
-    #   keyboard_enter_char(char)
-    # end
-    # ```
-    #
-    # @note
-    #  We have an exhaustive set of keyboard related test.s  The API is reasonably
-    #  stable.  We are fighting against known bugs in Apple's UIAutomation. You
-    #  should only need to fall back to the examples below in unusual situations.
     module KeyboardHelpers
 
-      include Calabash::Cucumber::TestsHelpers
-
-      # @!visibility private
-      KEYPLANE_NAMES = {
-          :small_letters => 'small-letters',
-          :capital_letters => 'capital-letters',
-          :numbers_and_punctuation => 'numbers-and-punctuation',
-          :first_alternate => 'first-alternate',
-          :numbers_and_punctuation_alternate => 'numbers-and-punctuation-alternate'
-      }
-
-      # @!visibility private
-      # noinspection RubyStringKeysInHashInspection
-      UIA_SUPPORTED_CHARS = {
-            'Delete' => '\b',
-            'Return' => '\n'
-            # these are not supported yet and I am pretty sure that they
-            # cannot be touched by passing an escaped character and instead
-            # the must be found using UIAutomation calls.  -jmoody
-            #'Dictation' => nil,
-            #'Shift' => nil,
-            #'International' => nil,
-            #'More' => nil,
-      }
+      # This module is expected to be included in Calabash::Cucumber::Core.
+      # Core includes necessary methods from:
+      #
+      # StatusBarHelpers
+      # EnvironmentHelpers
+      # WaitHelpers
+      # FailureHelpers
+      # UIA
 
-      # @!visibility private
-      # Returns a query string for detecting a keyboard.
-      def _qstr_for_keyboard
-        "view:'UIKBKeyplaneView'"
-      end
+      require "calabash-cucumber/map"
 
       # Returns true if a docked keyboard is visible.
       #
@@ -87,21 +25,21 @@ module Calabash
       #
       # @return [Boolean] if a keyboard is visible and docked.
       def docked_keyboard_visible?
-        res = query(_qstr_for_keyboard).first
+        keyboard = _query_for_keyboard
 
-        return false if res.nil?
+        return false if keyboard.nil?
 
         return true if device_family_iphone?
 
-        orientation = status_bar_orientation.to_sym
-        keyboard_height = res['rect']['height']
-        keyboard_y = res['rect']['y']
-        scale = screen_dimensions[:scale]
+        keyboard_height = keyboard['rect']['height']
+        keyboard_y = keyboard['rect']['y']
+        dimensions = screen_dimensions
+        scale = dimensions[:scale]
 
-        if orientation == :left || orientation == :right
-          screen_height = screen_dimensions[:width]/scale
+        if landscape?
+          screen_height = dimensions[:width]/scale
         else
-          screen_height = screen_dimensions[:height]/scale
+          screen_height = dimensions[:height]/scale
         end
 
         screen_height - keyboard_height == keyboard_y
@@ -116,10 +54,10 @@ module Calabash
       def undocked_keyboard_visible?
         return false if device_family_iphone?
 
-        res = query(_qstr_for_keyboard).first
-        return false if res.nil?
+        keyboard = _query_for_keyboard
+        return false if keyboard.nil?
 
-        not docked_keyboard_visible?
+        !docked_keyboard_visible?
       end
 
       # Returns true if a split keyboard is visible.
@@ -131,15 +69,26 @@ module Calabash
       # keyboards on the Phone and iPod are docked and not split.
       def split_keyboard_visible?
         return false if device_family_iphone?
-        query("view:'UIKBKeyView'").count > 0 and
-              element_does_not_exist(_qstr_for_keyboard)
+        _query_for_split_keyboard && !_query_for_keyboard
       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? or undocked_keyboard_visible? or split_keyboard_visible?
+        # Order matters!
+        docked_keyboard_visible? ||
+          undocked_keyboard_visible? ||
+          split_keyboard_visible?
+      end
+
+      # @!visibility private
+      # Raises an error ir the keyboard is not visible.
+      def expect_keyboard_visible!
+        if !keyboard_visible?
+          screenshot_and_raise "Keyboard is not visible"
+        end
+        true
       end
 
       # Waits for a keyboard to appear and once it does appear waits for
@@ -148,608 +97,47 @@ module Calabash
       # @see Calabash::Cucumber::WaitHelpers#wait_for for other options this
       #  method can handle.
       #
-      # @param [Hash] opts controls the `wait_for` behavior
+      # @param [Hash] options controls the `wait_for` behavior
       # @option opts [String] :timeout_message ('keyboard did not appear')
       #  Controls the message that appears in the error.
       # @option opts [Number] :post_timeout (0.3) Controls how long to wait
       #  _after_ the keyboard has appeared.
       #
       # @raise [Calabash::Cucumber::WaitHelpers::WaitError] if no keyboard appears
-      def wait_for_keyboard(opts={})
-        default_opts = {:timeout_message => 'keyboard did not appear',
-                        :post_timeout => 0.3}
-        opts = default_opts.merge(opts)
-        wait_for(opts) do
+      def wait_for_keyboard(options={})
+        default_opts = {
+          :timeout_message => "Keyboard did not appear",
+          :post_timeout => 0.3
+        }
+
+        merged_opts = default_opts.merge(options)
+        wait_for(merged_opts) do
           keyboard_visible?
         end
+        true
       end
 
-      # @!visibility private
-      # returns an array of possible ipad keyboard modes
-      def _ipad_keyboard_modes
-        [:docked, :undocked, :split]
-      end
-
-      # Returns the keyboard mode.
-      #
-      # @example How to use in a wait_* function.
-      #  wait_for do
-      #   ipad_keyboard_mode({:raise_on_no_visible_keyboard => false}) == :split
-      #  end
-      #
-      # ```
-      #                   keyboard is pinned to bottom of the view #=> :docked
-      #             keyboard is floating in the middle of the view #=> :undocked
-      #                             keyboard is floating and split #=> :split
-      #     no keyboard and :raise_on_no_visible_keyboard == false #=> :unknown
-      # ```
-      #
-      # @raise [RuntimeError] if the device under test is not an iPad.
+      # Waits for a keyboard to disappear.
       #
-      # @raise [RuntimeError] if `:raise_on_no_visible_keyboard` is truthy and
-      #  no keyboard is visible.
-      # @param [Hash] opts controls the runtime behavior.
-      # @option opts [Boolean] :raise_on_no_visible_keyboard (true) set to false
-      #  if you don't want to raise an error.
-      # @return [Symbol] Returns one of `{:docked | :undocked | :split | :unknown}`
-      def ipad_keyboard_mode(opts = {})
-        raise 'the keyboard mode does not exist on the iphone or ipod' if device_family_iphone?
-
-        default_opts = {:raise_on_no_visible_keyboard => true}
-        merged_opts = default_opts.merge(opts)
-        if merged_opts[:raise_on_no_visible_keyboard]
-          screenshot_and_raise 'there is no visible keyboard' unless keyboard_visible?
-          return :docked if docked_keyboard_visible?
-          return :undocked if undocked_keyboard_visible?
-          :split
-        else
-          return :docked if docked_keyboard_visible?
-          return :undocked if undocked_keyboard_visible?
-          return :split if split_keyboard_visible?
-          :unknown
-        end
-      end
-
-      # @!visibility private
-      # Ensures that there is a keyboard to enter text.
-      #
-      # @note
-      # *IMPORTANT* will always raise an error when the keyboard is split and
-      # there is no `run_loop`; i.e. UIAutomation is not available.
-      #
-      # @param [Hash] opts controls screenshot-ing and error raising conditions
-      # @option opts [Boolean] :screenshot (true) raise with a screenshot if
-      #  a keyboard cannot be ensured
-      # @option opts [Boolean] :skip (false) skip any checking (a nop) - used
-      #  when iterating over keyplanes for keys
-      def _ensure_can_enter_text(opts={})
-        default_opts = {:screenshot => true,
-                        :skip => false}
-        opts = default_opts.merge(opts)
-        return if opts[:skip]
-
-        screenshot = opts[:screenshot]
-        if !keyboard_visible?
-          msg = "No visible keyboard."
-          if screenshot
-            screenshot_and_raise msg
-          else
-            raise msg
-          end
-        end
-      end
-
-      # Use keyboard to enter a character.
-      #
-      # @note
-      #  IMPORTANT: Use the `POST_ENTER_KEYBOARD` environmental variable
-      #  to slow down the typing; adds a wait after each character is touched.
-      #  this can fix problems where the typing is too fast and characters are
-      #  skipped.
-      #
-      # @note
-      #  There are several special 'characters', some of which do not appear on
-      #  all keyboards; e.g. `Delete`, `Return`.
-      #
-      # @note
-      #  Since 0.9.163, this method accepts a Hash as the second parameter.  The
-      #  previous second parameter was a Boolean that controlled whether or not
-      #  to screenshot on errors.
-      #
-      # @see #keyboard_enter_text
-      #
-      # @note
-      #  You should prefer to call `keyboard_enter_text`.
-      #
-      # @raise [RuntimeError] if there is no visible keyboard
-      # @raise [RuntimeError] if the keyboard (layout) is not supported
-      #
-      # @param [String] chr the character to type
-      # @param [Hash] opts options to control the behavior of the method
-      # @option opts [Boolean] :should_screenshot (true) whether or not to
-      #  screenshot on errors
-      # @option opts [Float] :wait_after_char ('POST_ENTER_KEYBOARD' or 0.05)
-      #  how long to wait after a character is typed.
-      def keyboard_enter_char(chr, opts={})
-        default_opts = {:should_screenshot => true,
-                        # introduce a small wait to avoid skipping characters
-                        # keep this as short as possible
-                        :wait_after_char => (ENV['POST_ENTER_KEYBOARD'] || 0.05).to_f}
-
-        opts = default_opts.merge(opts)
-
-        should_screenshot = opts[:should_screenshot]
-        _ensure_can_enter_text({:screenshot => should_screenshot,
-                                :skip => (not should_screenshot)})
-
-        if chr.length == 1
-          uia_type_string_raw chr
-        else
-          code = UIA_SUPPORTED_CHARS[chr]
-
-          unless code
-            raise "typing character '#{chr}' is not yet supported when running with Instruments"
-          end
-
-          # on iOS 6, the Delete char code is _not_ \b
-          # on iOS 7, the Delete char code is \b on non-numeric keyboards
-          #           on numeric keyboards, it is actually a button on the
-          #           keyboard and not a key
-          if code.eql?(UIA_SUPPORTED_CHARS['Delete'])
-            js_tap_delete = "(function() {"\
-              "var deleteElement = uia.keyboard().elements().firstWithName('Delete');"\
-              "deleteElement = deleteElement.isValid() ? deleteElement : uia.keyboard().elements().firstWithName('delete');"\
-              "deleteElement.tap();"\
-              "})();"
-            uia(js_tap_delete)
-          else
-            uia_type_string_raw(code)
-          end
-        end
-        # noinspection RubyStringKeysInHashInspection
-        res = {'results' => []}
-
-        if ENV['POST_ENTER_KEYBOARD']
-          w = ENV['POST_ENTER_KEYBOARD'].to_f
-          if w > 0
-            sleep(w)
-          end
-        end
-        pause = opts[:wait_after_char]
-        sleep(pause) if pause > 0
-        res['results']
-      end
-
-      # Uses the keyboard to enter text.
-      #
-      # @param [String] text the text to type.
-      # @raise [RuntimeError] if the text cannot be typed.
-      def keyboard_enter_text(text)
-        _ensure_can_enter_text
-        text_before = _text_from_first_responder()
-        text_before = text_before.gsub("\n","\\n") if text_before
-        uia_type_string(text, text_before)
-      end
-
-      # @!visibility private
-      #
-      # Enters text into view identified by a query
-      #
-      # @note
-      # *IMPORTANT* enter_text defaults to calling 'setValue' in UIAutomation
-      # on the text field. This is fast, but in some cases might result in slightly
-      # different behaviour than using `keyboard_enter_text`.
-      # To force use of `keyboard_enter_text` in `enter_text` use
-      # option :use_keyboard
-      #
-      # @param [String] uiquery the element to enter text into
-      # @param [String] text the text to enter
-      # @param [Hash] options controls details of text entry
-      # @option options [Boolean] :use_keyboard (false) use the iOS keyboard
-      #   to enter each character separately
-      # @option options [Boolean] :wait (true) call wait_for_element_exists with uiquery
-      # @option options [Hash] :wait_options ({}) if :wait pass this as options to wait_for_element_exists
-      def enter_text(uiquery, text, options = {})
-        default_opts = {:use_keyboard => false, :wait => true, :wait_options => {}}
-        options = default_opts.merge(options)
-        wait_for_element_exists(uiquery, options[:wait_options]) if options[:wait]
-        touch(uiquery, options)
-        wait_for_keyboard
-        if options[:use_keyboard]
-          keyboard_enter_text(text)
-        else
-          fast_enter_text(text)
-        end
-      end
-
-      # @!visibility private
-      #
-      # Enters text into current text input field
-      #
-      # @note
-      # *IMPORTANT* fast_enter_text defaults to calling 'setValue' in UIAutomation
-      # on the text field. This is fast, but in some cases might result in slightly
-      # different behaviour than using `keyboard_enter_text`.
-      # @param [String] text the text to enter
-      def fast_enter_text(text)
-        _ensure_can_enter_text
-        uia_set_responder_value(text)
-      end
-
-      # Touches the keyboard action key.
-      #
-      # The action key depends on the keyboard.  Some examples include:
-      #
-      # * Return
-      # * Next
-      # * Go
-      # * Join
-      # * Search
-      #
-      # @note
-      #  Not all keyboards have an action key.  For example, numeric keyboards
-      #  do not have an action key.
-      #
-      # @raise [RuntimeError] if the text cannot be typed.
-      def tap_keyboard_action_key
-        keyboard_enter_char 'Return'
-      end
-
-      # @!visibility private
-      # Returns the current keyplane.
-      def _current_keyplane
-        kp_arr = _do_keyplane(
-            lambda { query("view:'UIKBKeyplaneView'", 'keyplane', 'componentName') },
-            lambda { query("view:'UIKBKeyplaneView'", 'keyplane', 'name') })
-        kp_arr.first.downcase
-      end
-
-      # @!visibility private
-      # Searches the available keyplanes for chr and if it is found, types it.
-      #
-      # This is a recursive function.
-      #
-      # @note
-      #   Use the `KEYPLANE_SEARCH_STEP_PAUSE` variable to control how quickly
-      #   the next keyplane is searched.  Increase this value if you encounter
-      #   problems with missed keystrokes.
-      #
-      # @note
-      #   When running under instruments, this method is not called.
-      #
-      # @raise [RuntimeError] if the char cannot be found
-      def _search_keyplanes_and_enter_char(chr, visited=Set.new)
-        cur_kp = _current_keyplane
-        begin
-          keyboard_enter_char(chr, {:should_screenshot => false})
-          return true #found
-        rescue
-          pause = (ENV['KEYPLANE_SEARCH_STEP_PAUSE'] || 0.2).to_f
-          sleep (pause) if pause > 0
-
-          visited.add(cur_kp)
-
-          #figure out keyplane alternates
-          props = _do_keyplane(
-              lambda { query("view:'UIKBKeyplaneView'", 'keyplane', 'properties') },
-              lambda { query("view:'UIKBKeyplaneView'", 'keyplane', 'attributes', 'dict') }
-          ).first
-
-          known = KEYPLANE_NAMES.values
-
-          found = false
-          keyplane_selection_keys = ['shift', 'more']
-          keyplane_selection_keys.each do |key|
-            sleep (pause) if pause > 0
-            plane = props["#{key}-alternate"]
-            if known.member?(plane) and (not visited.member?(plane))
-              keyboard_enter_char(key.capitalize, {:should_screenshot => false})
-              found = _search_keyplanes_and_enter_char(chr, visited)
-              return true if found
-              #not found => try with other keyplane selection key
-              keyplane_selection_keys.delete(key)
-              other_key = keyplane_selection_keys.last
-              keyboard_enter_char(other_key.capitalize, {:should_screenshot => false})
-              found = _search_keyplanes_and_enter_char(chr, visited)
-              return true if found
-            end
-          end
-          return false
-        end
-      end
-
-      # @!visibility private
-      # Process a keyplane.
-      #
-      # @raise [RuntimeError] if there is no visible keyplane
-      def _do_keyplane(kbtree_proc, keyplane_proc)
-        desc = query("view:'UIKBKeyplaneView'", 'keyplane')
-        fail('No keyplane (UIKBKeyplaneView keyplane)') if desc.empty?
-        fail('Several keyplanes (UIKBKeyplaneView keyplane)') if desc.count > 1
-        kp_desc = desc.first
-        if /^<UIKBTree/.match(kp_desc)
-          #ios5+
-          kbtree_proc.call
-        elsif /^<UIKBKeyplane/.match(kp_desc)
-          #ios4
-          keyplane_proc.call
-        end
-      end
-
-      # @!visibility private
-      # Returns a query string for finding the iPad 'Hide keyboard' button.
-      def _query_uia_hide_keyboard_button
-        "uia.keyboard().buttons()['Hide keyboard']"
-      end
-
-      # Dismisses a iPad keyboard by touching the 'Hide keyboard' button and waits
-      # for the keyboard to disappear.
-      #
-      # @note
-      #  the dismiss keyboard key does not exist on the iPhone or iPod
-      #
-      # @raise [RuntimeError] if the device is not an iPad
-      def dismiss_ipad_keyboard
-        screenshot_and_raise "Cannot dismiss keyboard on iPhone" if device_family_iphone?
-        send_uia_command({:command =>  "#{_query_uia_hide_keyboard_button}.tap()"})
-
-        opts = {:timeout_message => 'keyboard did not disappear'}
-        wait_for(opts) do
-          not keyboard_visible?
-        end
-      end
-
-      # @!visibility private
-      # Returns the activation point of the iPad keyboard mode key.
-      #
-      # The mode key is also known as the 'Hide keyboard' key.
-      #
-      # @note
-      #  This is only available when running under instruments.
-      #
-      # @raise [RuntimeError] when the device is not an iPad
-      # @raise [RuntimeError] the app was not launched with instruments
-      def _point_for_ipad_keyboard_mode_key
-        raise "The keyboard mode does not exist on the on the iphone" if device_family_iphone?
-        res = send_uia_command({:command => "#{_query_uia_hide_keyboard_button}.rect()"})
-        origin = res['value']['origin']
-        {:x => origin['x'], :y => origin['y']}
-      end
-
-      # @!visibility private
-      # Touches the bottom option on the popup dialog that is presented when the
-      # the iPad keyboard `mode` key is touched and held.
-      #
-      # The `mode` key is also know as the 'Hide keyboard' key.
-      #
-      # The `mode` key allows the user to undock, dock, or split the keyboard.
-      def _touch_bottom_keyboard_mode_row
-        start_pt = _point_for_ipad_keyboard_mode_key
-        # there are 10 pt btw the key and the popup and the row is 50 pt
-        y_offset = 10 + 25
-        end_pt = {:x => (start_pt[:x] - 40), :y => (start_pt[:y] - y_offset)}
-        uia_pan_offset(start_pt, end_pt, {})
-        sleep(1.0)
-      end
-
-      # Touches the top option on the popup dialog that is presented when the
-      # the iPad keyboard mode key is touched and held.
-      #
-      # The `mode` key is also know as the 'Hide keyboard' key.
-      #
-      # The `mode` key allows the user to undock, dock, or split the keyboard.
-      def _touch_top_keyboard_mode_row
-        start_pt = _point_for_ipad_keyboard_mode_key
-        # there are 10 pt btw the key and the popup and each row is 50 pt
-        # NB: no amount of offsetting seems to allow touching the top row
-        #     when the keyboard is split
-
-        x_offset = 40
-        y_offset = 10 + 50 + 25
-        end_pt = {:x => (start_pt[:x] - x_offset), :y => (start_pt[:y] - y_offset)}
-        uia_pan_offset(start_pt, end_pt, {:duration => 1.0})
-      end
-
-      # Ensures that the iPad keyboard is docked.
-      #
-      # Docked means the keyboard is pinned to bottom of the view.
-      #
-      # If the device is not an iPad, this is behaves like a call to
-      # `wait_for_keyboard`.
-      #
-      # @raise [RuntimeError] if there is no visible keyboard
-      # @raise [RuntimeError] a docked keyboard was not achieved
-      def ensure_docked_keyboard
-        wait_for_keyboard
-
-        return if device_family_iphone?
-
-        mode = ipad_keyboard_mode
-
-        return if mode == :docked
-
-        if ios9?
-          raise KeyboardModeError,
-                'Changing keyboard modes is not supported on iOS 9'
-        else
-          case mode
-            when :split then
-              _touch_bottom_keyboard_mode_row
-            when :undocked then
-              _touch_top_keyboard_mode_row
-            when :docked then
-              # already docked
-            else
-              screenshot_and_raise "expected '#{mode}' to be one of #{_ipad_keyboard_modes}"
-          end
-        end
-
-        begin
-          wait_for({:post_timeout => 1.0}) do
-            docked_keyboard_visible?
-          end
-        rescue
-          mode = ipad_keyboard_mode
-          o = status_bar_orientation
-          screenshot_and_raise "expected keyboard to be ':docked' but found '#{mode}' in orientation '#{o}'"
-        end
-      end
-
-      # Ensures that the iPad keyboard is undocked.
-      #
-      # Undocked means the keyboard is floating in the middle of the view.
-      #
-      # If the device is not an iPad, this is behaves like a call to
-      # `wait_for_keyboard`.
-      #
-      # If the device is not an iPad, this is behaves like a call to
-      # `wait_for_keyboard`.
-      #
-      # @raise [RuntimeError] if there is no visible keyboard
-      # @raise [RuntimeError] an undocked keyboard was not achieved
-      def ensure_undocked_keyboard
-        wait_for_keyboard
-
-        return if device_family_iphone?
-
-        mode = ipad_keyboard_mode
-
-        return if mode == :undocked
-
-        if ios9?
-          raise KeyboardModeError,
-                'Changing keyboard modes is not supported on iOS 9'
-        else
-          case mode
-            when :split then
-              # keep these condition separate because even though they do the same
-              # thing, the else condition is a hack
-              if ios5?
-                # iOS 5 has no 'Merge' feature in split keyboard, so dock first then
-                # undock from docked mode
-                _touch_bottom_keyboard_mode_row
-                _wait_for_keyboard_in_mode(:docked)
-              else
-                # in iOS > 5, it seems to be impossible consistently touch the
-                # the top keyboard mode popup button, so we punt
-                _touch_bottom_keyboard_mode_row
-                _wait_for_keyboard_in_mode(:docked)
-              end
-              _touch_top_keyboard_mode_row
-            when :undocked then
-              # already undocked
-            when :docked then
-              _touch_top_keyboard_mode_row
-            else
-              screenshot_and_raise "expected '#{mode}' to be one of #{_ipad_keyboard_modes}"
-          end
-        end
-        _wait_for_keyboard_in_mode(:undocked)
-      end
-
-
-      # Ensures that the iPad keyboard is split.
-      #
-      # Split means the keyboard is floating in the middle of the view and is
-      # split into two sections to enable faster thumb typing.
-      #
-      # If the device is not an iPad, this is behaves like a call to
-      # `wait_for_keyboard`.
-      #
-      # If the device is not an iPad, this is behaves like a call to
-      # `wait_for_keyboard`.
-      #
-      # @raise [RuntimeError] if there is no visible keyboard
-      # @raise [RuntimeError] a split keyboard was not achieved
-      def ensure_split_keyboard
-        wait_for_keyboard
-
-        return if device_family_iphone?
-
-        mode = ipad_keyboard_mode
-
-        return if mode == :split
-
-        if ios9?
-          raise KeyboardModeError,
-                'Changing keyboard modes is not supported on iOS 9'
-        else
-          case mode
-            when :split then
-              # already split
-            when :undocked then
-              _touch_bottom_keyboard_mode_row
-            when :docked then
-              _touch_bottom_keyboard_mode_row
-            else
-              screenshot_and_raise "expected '#{mode}' to be one of #{_ipad_keyboard_modes}"
-          end
-        end
-        _wait_for_keyboard_in_mode(:split)
-      end
-
-      # @!visibility private
-      def _wait_for_keyboard_in_mode(mode, opts={})
-        default_opts = {:post_timeout => 1.0}
-        opts = default_opts.merge(opts)
-        begin
-          wait_for(opts) do
-            case mode
-              when :split then
-                split_keyboard_visible?
-              when :undocked
-                undocked_keyboard_visible?
-              when :docked
-                docked_keyboard_visible?
-              else
-                screenshot_and_raise "expected '#{mode}' to be one of #{_ipad_keyboard_modes}"
-            end
-          end
-        rescue
-          actual = ipad_keyboard_mode
-          o = status_bar_orientation
-          screenshot_and_raise "expected keyboard to be '#{mode}' but found '#{actual}' in orientation '#{o}'"
-        end
-      end
-
-      # Used for detecting keyboards that are not normally visible to calabash;
-      # e.g. the keyboard on the `MFMailComposeViewController`
-      #
-      # @note
-      #  IMPORTANT this should only be used when the app does not respond to
-      #  `keyboard_visible?`.
-      #
-      # @see #keyboard_visible?
-      #
-      # @raise [RuntimeError] if the app was not launched with instruments
-      def uia_keyboard_visible?
-        res = uia_query_windows(:keyboard)
-        not res.eql?(':nil')
-      end
-
-      # Waits for a keyboard that is not normally visible to calabash;
-      # e.g. the keyboard on `MFMailComposeViewController`.
-      #
-      # @note
-      #  IMPORTANT this should only be used when the app does not respond to
-      #  `keyboard_visible?`.
+      # @see Calabash::Cucumber::WaitHelpers#wait_for for other options this
+      #  method can handle.
       #
-      # @see #keyboard_visible?
+      # @param [Hash] options controls the `wait_for` behavior
+      # @option opts [String] :timeout_message ('keyboard did not appear')
+      #  Controls the message that appears in the error.
       #
-      # @raise [RuntimeError] if the app was not launched with instruments
-      def uia_wait_for_keyboard(opts={})
-        default_opts = {:timeout => 10,
-                        :retry_frequency => 0.1,
-                        :post_timeout => 0.5}
-        opts = default_opts.merge(opts)
-        unless opts[:timeout_message]
-          msg = "waited for '#{opts[:timeout]}' for keyboard"
-          opts[:timeout_message] = msg
-        end
+      # @raise [Calabash::Cucumber::WaitHelpers::WaitError] If keyboard does
+      #  not disappear.
+      def wait_for_no_keyboard(options={})
+        default_opts = {
+          :timeout_message => "Keyboard is visible",
+        }
 
-        wait_for(opts) do
-          uia_keyboard_visible?
+        merged_opts = default_opts.merge(options)
+        wait_for(merged_opts) do
+          !keyboard_visible?
         end
+        true
       end
 
       # Waits for a keyboard to appear and returns the localized name of the
@@ -780,17 +168,47 @@ module Calabash
       # the first responder.
       #
       # @raise [RuntimeError] if there is no visible keyboard
-      def _text_from_first_responder
-        raise 'there must be a visible keyboard' unless keyboard_visible?
+      def text_from_first_responder
+        if !keyboard_visible?
+          screenshot_and_raise "There must be a visible keyboard"
+        end
 
         ['textField', 'textView'].each do |ui_class|
-          res = query("#{ui_class} isFirstResponder:1", :text)
-          return res.first unless res.empty?
+          query = "#{ui_class} isFirstResponder:1"
+          result = _query_wrapper(query, :text)
+          if !result.empty?
+            return result.first
+          end
         end
-        #noinspection RubyUnnecessaryReturnStatement
-        return ''
+        ""
       end
 
+      # @visibility private
+      # TODO Remove in 0.21.0
+      alias_method :_text_from_first_responder, :text_from_first_responder
+
+      private
+
+      # @!visibility private
+      KEYBOARD_QUERY = "view:'UIKBKeyplaneView'"
+
+      # @!visibility private
+      SPLIT_KEYBOARD_QUERY = "view:'UIKBKeyView'"
+
+      # @!visibility private
+      def _query_wrapper(query, *args)
+        Calabash::Cucumber::Map.map(query, :query, *args)
+      end
+
+      # @!visibility private
+      def _query_for_keyboard
+        _query_wrapper(KEYBOARD_QUERY).first
+      end
+
+      # @!visibility private
+      def _query_for_split_keyboard
+        _query_wrapper(SPLIT_KEYBOARD_QUERY).first
+      end
     end
   end
 end