calabash 1.2.1 → 1.9.9.pre1

data/lib/calabash/ios/server.rb

@@ -0,0 +1,73 @@
+module Calabash
+  module IOS
+
+    # A representation of the embedded Calabash iOS server.
+    class Server < ::Calabash::Server
+
+      # Returns the default server.
+      #
+      # You can set the default server by setting the `CAL_ENDPOINT` environment
+      # variable.  If this value is not set, the default server will be
+      # `http://localhost:37265`.
+      #
+      # **IMPORTANT**
+      #
+      # You must include http:// and the port number when setting the
+      # `CAL_ENDPOINT` variable.
+      #
+      # ### Physical Devices
+      #
+      # When targeting a physical device, you _must_ set the `CAL_ENDPOINT`
+      # environment variable.  Your device must be on the same network as the
+      # host machine.  You can find your device's IP address the Settings.app.
+      #
+      #     Settings.app > WiFi > touch the (i)nfo
+      #     disclosure button of the network you are
+      #     connected to.
+      #
+      # ### Pro Tip:  Name your devices.
+      #
+      # The Calabash iOS Server is a Bonjour web service. You can avoid the
+      # hassle of determining a device's IP address by naming your devices.  The
+      # names should not have spaces or characters that cannot be displayed
+      # plainly in a URL.
+      #
+      # Suppose you have 3 devices:  an iPad Mini Retina, an iPhone 4S, and an
+      # iPhone 6.
+      #
+      # | Device | Name | IP |
+      # |--------|------|----|
+      # | iPad   | ipad-mini | CAL_ENDPOINT=http://ipad-mini.local:37265 |
+      # | iPhone 4S     | iphone4s  | CAL_ENDPOINT=http://iphone4s.local:37265 |
+      # | iPhone 6      | iphone6   | CAL_ENDPOINT=http://iphone6.local:37265 |
+      #
+      # ### Pro Tip: Changing the Calabash server port.
+      #
+      # You can change the port number of the server by adding
+      # `CalabashServerPort` to your app's Info plist.
+      #
+      #      CalabashServerPort NSNumber 9999
+      #
+      # ### Pro Tip: Share your wired connection
+      #
+      # https://github.com/calabash/calabash/wiki/iOS:-Improving-Network-Stability
+      #
+      # @return [Calabash::IOS::Server] The Calabash iOS server that is
+      #  embedded in your app.
+      def self.default
+        endpoint = Environment::DEVICE_ENDPOINT
+        Server.new(endpoint)
+      end
+
+      # Is this server running on the host machine?
+      #
+      # Apps running on the iOS Simulator are running on localhost.
+      #
+      # @return [Boolean] Returns true if the server hostname resolves to
+      #  localhost.
+      def localhost?
+        endpoint.hostname == 'localhost' || endpoint.hostname == '127.0.0.1'
+      end
+    end
+  end
+end

data/lib/calabash/ios/text.rb

@@ -0,0 +1,248 @@
+module Calabash
+  module IOS
+    module Text
+      # @!visibility private
+      def enter_text(text)
+        wait_for_keyboard
+        existing_text = text_from_keyboard_first_responder
+        options = { existing_text: existing_text }
+        Device.default.uia_type_string(text, options)
+      end
+
+      # @!visibility private
+      def _enter_text_in(view, text)
+        tap(view)
+        enter_text(text)
+      end
+
+      # @!visibility private
+      def _clear_text
+        unless view_exists?("* isFirstResponder:1")
+          raise 'Cannot clear text. No view has focus'
+        end
+
+        clear_text_in("* isFirstResponder:1")
+      end
+
+      # @!visibility private
+      def _clear_text_in(view)
+        unless keyboard_visible?
+          tap(view)
+          wait_for_keyboard
+        end
+
+        unless wait_for_view(view)['text'].empty?
+          tap(view)
+          tap("UICalloutBarButton marked:'Select All'")
+          tap_keyboard_delete_key
+        end
+
+        true
+      end
+
+      # 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.
+      #
+      # @return [Boolean] Returns true if a keyboard is visible and docked.
+      def docked_keyboard_visible?
+        Device.default.docked_keyboard_visible?
+      end
+
+      # Returns true if an undocked keyboard is visible.
+      #
+      # A undocked keyboard is floats in the middle of the view.
+      #
+      # @return [Boolean] Returns false if the device is not an iPad; all
+      # keyboards on the iPhone and iPod are docked.
+      def undocked_keyboard_visible?
+        Device.default.undocked_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
+      #
+      # @return [Boolean] Returns false if the device is not an iPad; all
+      # keyboards on the Phone and iPod are docked and not split.
+      def split_keyboard_visible?
+        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:
+      #
+      # * Return
+      # * Next
+      # * Go
+      # * Join
+      # * Search
+      #
+      # 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.
+      # @todo Refactor uia_route to a public API call
+      # @todo Move this documentation to the public method
+      def _tap_current_keyboard_action_key
+        char_sequence = ESCAPED_KEYBOARD_CHARACTERS[:action]
+        Device.default.uia_route("uia.keyboard().typeString('#{char_sequence}')")
+      end
+
+      # Touches the keyboard delete key.
+      #
+      # The 'delete' key difficult to find and touch because its behavior
+      # changes depending on the iOS version and keyboard type.  Consider the
+      # following:
+      #
+      # 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, the delete key is a button on the
+      #           the keyboard.
+      #
+      # By default, Calabash uses a raw UIAutomaton JavaScript call to tap the
+      # element named 'Delete'.  This works well in English localizations for
+      # most keyboards.  If you find that it does not work, use the options
+      # pass either an translation of 'Delete' for your localization or use the
+      # default the escaped keyboard character.
+      #
+      # @example
+      #   # Uses UIAutomation to tap the 'Delete' key or button.
+      #   tap_keyboard_delete_key
+      #
+      #   # Types the \b key.
+      #   tap_keyboard_delete_key({:use_escaped_char => true})
+      #
+      #   # Types the \d key.
+      #   tap_keyboard_delete_key({:use_escaped_char => '\d'})
+      #
+      #   # Uses UIAutomation to tap the 'Slet' key or button.
+      #   tap_keyboard_delete_key({:delete_key_label => 'Slet'})
+      #
+      #   # Don't specify both options!  If :use_escape_sequence is truthy,
+      #   # Calabash will ignore the :delete_key_label and try to use an
+      #   # escaped character sequence.
+      #   tap_keyboard_delete_key({:use_escaped_char => true,
+      #                            :delete_key_label => 'Slet'})
+      #
+      # @param [Hash] options Alternative ways to tap the delete key.
+      # @option options [Boolean, String] :use_escaped_char (false) If true,
+      #  delete by typing the \b character.  If this value is truthy, but not
+      #  'true', they it is expected to be an alternative escaped character.
+      # @option options [String] :delete_key_label ('Delete') An alternative
+      #  localization of 'Delete'.
+      # @todo Need translations of 'Delete' key.
+      def tap_keyboard_delete_key(options = {})
+        default_options =
+            {
+                use_escaped_char: false,
+                delete_key_label: 'Delete'
+            }
+        merged_options = default_options.merge(options)
+
+        use_escape_sequence = merged_options[:use_escaped_char]
+        if use_escape_sequence
+          if use_escape_sequence.to_s == 'true'
+            # Use the default \b
+            char_sequence = ESCAPED_KEYBOARD_CHARACTERS[:delete]
+          else
+            char_sequence = use_escape_sequence
+          end
+          return Device.default.uia_route("uia.keyboard().typeString('#{char_sequence}')")
+        end
+
+        delete_key_label = merged_options[:delete_key_label]
+        uia = "uia.keyboard().elements().firstWithName('#{delete_key_label}').tap()"
+        Device.default.uia_route(uia)
+      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.
+      #
+      # @raise [RuntimeError] If there is no visible keyboard.
+      def text_from_keyboard_first_responder
+        Device.default.text_from_keyboard_first_responder
+      end
+
+      private
+
+      # @!visibility private
+      # noinspection RubyStringKeysInHashInspection
+      ESCAPED_KEYBOARD_CHARACTERS =
+          {
+              :action => '\n',
+
+              # This works for some combinations of keyboard types and
+              # iOS version.  The current solution is use a raw UIA call
+              # to find the 'Delete' key, which may not work in some
+              # situations, for example in non-English environments.  The
+              # tap_keyboard_delete_key allows an option to us this escape
+              # sequence.
+              :delete => '\b',
+
+              # 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,
+          }
+
+      def keyboard_wait_timeout(timeout)
+        if timeout.nil?
+          Calabash::Gestures::DEFAULT_GESTURE_WAIT_TIMEOUT
+        else
+          timeout
+        end
+      end
+    end
+  end
+end

data/lib/calabash/ios/uia.rb

@@ -0,0 +1,24 @@
+module Calabash
+  module IOS
+    module UIA
+
+      # Evaluates `script` with Apple's UIAutomation API.
+      #
+      def uia(script)
+        Device.default.evaluate_uia(script)
+      end
+
+      def uia_with_target(script)
+        uia("UIATarget.localTarget().#{script}")
+      end
+
+      def uia_with_app(script)
+        uia("UIATarget.localTarget().frontMostApp().#{script}")
+      end
+
+      def uia_with_main_window(script)
+        uia("UIATarget.localTarget().frontMostApp().mainWindow().#{script}")
+      end
+    end
+  end
+end

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

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

data/lib/calabash/lib/skeleton/features/sample.feature

@@ -0,0 +1,5 @@
+Feature: Sample Feature
+  Scenario: Sample Scenario
+    Given I have done a specific thing
+    When I do something
+    Then something should happen

data/lib/calabash/lib/skeleton/features/step_definitions/calabash_steps.rb

@@ -0,0 +1,29 @@
+Given(/^I have done a specific thing$/) do
+  # Sample step definition
+  # Example: (Given I am logged in)
+  #  enter_text("* marked:'username'", USERNAME)
+  #  enter_text("* marked:'password'", PASSWORD)
+  #  touch("* marked:'login'")
+  #  wait_for_view("* text:'Welcome #{USERNAME}'")
+
+  # Remember: any Ruby is allowed in your step definitions
+  did_something = true
+
+  unless did_something
+    fail 'Expected to have done something'
+  end
+end
+
+When(/^I do something$/) do
+  # Sample step definition
+  # Example: When I create a new entry
+  #  touch("* marked:'new_entry'")
+  #  enter_text("* marked:'entry_title'", 'My Entry')
+  #  touch("* marked:'submit'")
+end
+
+Then(/^something should happen$/) do
+  # Sample step definition
+  # Example: Then I should see the entry on my home page
+  #  wait_for_view("* text:'My Entry'")
+end

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

@@ -0,0 +1,54 @@
+require 'calabash'
+
+platform = Calabash::Environment.variable('PLATFORM')
+
+case platform
+  when 'android'
+    require 'calabash/android'
+
+    World(Calabash::Android)
+
+    # Setup the default application
+    Calabash::Application.default =
+        Calabash::Android::Application.default_from_environment
+
+    identifier = Calabash::Android::Device.default_serial
+    server = Calabash::Android::Server.default
+
+    # Setup the default device
+    Calabash::Device.default =
+        Calabash::Android::Device.new(identifier, server)
+  when 'ios'
+    require 'calabash/ios'
+
+    World(Calabash::IOS)
+
+    # Setup the default application
+    Calabash::Application.default =
+        Calabash::IOS::Application.default_from_environment
+
+    identifier =
+        Calabash::IOS::Device.default_identifier_for_application(Calabash::Application.default)
+
+    server = Calabash::IOS::Server.default
+
+    # Setup the default device
+    Calabash::Device.default =
+        Calabash::IOS::Device.new(identifier, server)
+  else
+    message = if platform.nil? || platform.empty?
+                'No platform given'
+              else
+                "Invalid platform '#{platform}'. Expected 'android' or 'ios'"
+              end
+
+    failure_messages =
+        [
+            'ERROR! Unable to start the cucumber test:',
+            message,
+            "Use the profile 'android' or 'ios', or run cucumber using $ calabash run"
+        ]
+
+    Calabash::Logger.error(failure_messages.join("\n"))
+    exit(1)
+end

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

@@ -0,0 +1,83 @@
+require 'calabash'
+
+Before do |scenario|
+  if scenario.respond_to?(:scenario_outline)
+    scenario = scenario.scenario_outline
+  end
+
+  AppLifeCycle.on_new_scenario(scenario)
+
+  start_app
+end
+
+After do
+  stop_app
+end
+
+module AppLifeCycle
+  # Since this is a module, the methods in the Cucumber World are not
+  # available inside the scope of this module. We can safely include Calabash
+  # because we will not affect the scope outside this module. The methods are
+  # loaded as class (static) methods.
+  class << self
+    include Calabash
+  end
+
+  DEFAULT_RESET_BETWEEN = #!DEFAULT_RESET_BETWEEN#! # Filled in by calabash gen
+  DEFAULT_RESET_METHOD = #!DEFAULT_RESET_METHOD#! # Filled in by calabash gen
+
+  RESET_BETWEEN = if Calabash::Environment.variable('RESET_BETWEEN')
+                    Calabash::Environment.variable('RESET_BETWEEN').downcase.to_sym
+                  else
+                    DEFAULT_RESET_BETWEEN
+                  end
+
+  RESET_METHOD = if Calabash::Environment.variable('RESET_METHOD')
+                   Calabash::Environment.variable('RESET_METHOD').downcase.to_sym
+                 else
+                   DEFAULT_RESET_METHOD
+                 end
+
+  def self.on_new_scenario(scenario)
+    # Ensure the app is installed at the beginning of the test,
+    # if we never reset
+    if @last_feature.nil? && RESET_BETWEEN == :never
+      ensure_app_installed
+    end
+
+    if should_reset?(scenario)
+      reset
+    end
+
+    @last_feature = scenario.feature
+  end
+
+  private
+
+  def self.should_reset?(scenario)
+    case RESET_BETWEEN
+      when :scenarios
+        true
+      when :features
+        scenario.feature != @last_feature
+      when :never
+        false
+      else
+        raise "Invalid reset between option '#{RESET_BETWEEN}'"
+    end
+  end
+
+  def self.reset
+    case RESET_METHOD
+      when :reinstall
+        install_app
+      when :clear
+        ensure_app_installed
+        clear_app_data
+      when '', nil
+        raise 'No reset method given'
+      else
+        raise "Invalid reset method '#{RESET_METHOD}'"
+    end
+  end
+end