calabash 1.9.9.pre3 → 2.0.0.prelegacy

data/lib/calabash/ios/slider.rb

@@ -0,0 +1,70 @@
+module Calabash
+  module IOS
+
+    # An interface for interacting with UISliders.
+    module Slider
+
+      # Sets the value of the first UISliders matched by `query` to `value`.
+      #
+      # If `query` matches a view that is not a UISlider or UISlider subclass,
+      # an error will be raised.
+      #
+      # An error will be raised if more than on view is matched by `query`.
+      #
+      # To avoid matching more than one UISlider (or subclass):
+      #  * Make the query more specific: "UISlider marked:'volume'"
+      #  * Use the index language feature:  "UISlider index:0"
+      #
+      # @example
+      #  slider_set_value("UISlider marked:'office slider'", 2)
+      #  slider_set_value("slider marked:'weather slider'", -1)
+      #  slider_set_value("UISlider", 11)
+      #
+      # @param [String, Hash, Calabash::Query] query A query to that indicates
+      #   in which slider to set the value.
+      # @param [Numeric] value The value to set the slider to.  value.to_s should
+      #  produce a String representation of a Number.
+      #
+      # @param [options] options Options to control the behavior of the gesture.
+      # @option options [Boolean] :animate (true) Animate the change.
+      # @option options [Boolean] :notify_targets (true) Simulate a UIEvent by
+      #  calling every target/action pair defined on the UISlider matching
+      #  `query`.
+      #
+      # @raise [RuntimeError] When `query` does not match exactly one slider.
+      # @raise [RuntimeError] When setting the value of the slider matched by
+      #  `query` is not successful.
+      def slider_set_value(query, value,  options={})
+        Query.ensure_valid_query(query)
+
+        default_options = {
+              :animate => true,
+              :notify_targets => true
+        }
+
+        merged_options = default_options.merge(options)
+
+        found_none = "Expected '#{query}' to match exactly one view, but found no matches."
+        query_object = Query.new(query)
+        wait_for(found_none) do
+          results = query(query_object)
+          if results.length > 1
+            message = [
+                  "Expected '#{query}' to match exactly one view, but found '#{results.length}'",
+                  results.join("\n")
+            ].join("\n")
+            fail(message)
+          else
+            results.length == 1
+          end
+        end
+
+        value_str = value.to_s
+
+        args = [merged_options[:animate], merged_options[:notify_targets]]
+
+        Device.default.map_route(query, :changeSlider, value_str, *args)
+      end
+    end
+  end
+end

data/lib/calabash/ios/text.rb

@@ -1,7 +1,6 @@
 module Calabash
   module IOS
     # Methods for entering text and interacting with iOS keyboards.
-    # @!visibility private
     module Text
       # @!visibility private
       def _enter_text(text)
@@ -74,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:
@@ -128,11 +90,21 @@ module Calabash
       # @todo Refactor uia_route to a public API call
       # @todo Move this documentation to the public method
       # @!visibility private
-      def _tap_current_keyboard_action_key
+      def _tap_keyboard_action_key(action_key)
+        unless action_key.nil?
+          raise ArgumentError,
+                "An iOS keyboard does not have multiple action keys"
+        end
+
         char_sequence = ESCAPED_KEYBOARD_CHARACTERS[:action]
         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
@@ -238,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/ios/uia.rb

@@ -1,22 +1,44 @@
 module Calabash
   module IOS
-    # @!visibility private
+
+    # Methods for interacting directly with Apple's UIAutomation API.
+    #
+    # https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/InstrumentsUserGuide/UsingtheAutomationInstrument/UsingtheAutomationInstrument.html
+    # https://developer.apple.com/library/ios/documentation/DeveloperTools/Reference/UIAutomationRef/
+    #
+    # Calabash iOS uses this API to perform gestures.  It is sometimes helpful
+    # to drop down into this API to explore your app.
     module UIA
 
-      # Evaluates `script` with Apple's UIAutomation API.
+      # Evaluates `script` using Apples's UIAutomation API.
       #
+      # @example
+      #  uia("UIATarget.localTarget().shake()")
+      #  uia("UIATarget.localTarget().frontMostApp().keyboard().buttons()['Delete']")
+      #  uia("UIATarget.localTarget().frontMostApp().mainWindow().elements()")
       def uia(script)
         Device.default.evaluate_uia(script)
       end
 
+      # Evaluates `script` after prefixing with "UIATarget.localTarget()"
+      #
+      # @example
+      #  uia_with_target("shake()")
       def uia_with_target(script)
         uia("UIATarget.localTarget().#{script}")
       end
 
+      # Evaluates `script` after prefixing with
+      # "UIATarget.localTarget().frontMostApp()"
+      #
+      # @example
+      #  uia_with_app("keyboard().buttons()['Delete'])
       def uia_with_app(script)
         uia("UIATarget.localTarget().frontMostApp().#{script}")
       end
 
+      # Evaluates `script` after prefixing with
+      # "UIATarget.localTarget().frontMostApp().mainWindow()"
       def uia_with_main_window(script)
         uia("UIATarget.localTarget().frontMostApp().mainWindow().#{script}")
       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/dry_run.rb

@@ -0,0 +1,8 @@
+# Cucumber does not load env.rb when running a dry-run. As the pages inherit
+# from Calabash::Page and assert that the scopes IOS and Android are defined,
+# we should require calabash.
+
+if ARGV.include?('--dry-run')
+  require 'calabash/android'
+  require 'calabash/ios'
+end

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,58 +1,93 @@
 module Calabash
-  # @!visibility private
+
+  # 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
-    def start_app(path_or_application = nil, **opt)
-      path_or_application ||= Application.default
+    # Start the given application (and its test-server) on the port of
+    # {Calabash::Defaults#default_server Calabash.default_server}.
+    # This method will **not** install the application specified. If no
+    # application is given, it will start
+    # {Calabash::Defaults#default_application Calabash.default_application}
+    #
+    # @note This method will fail if the application (and test-server for
+    #  Android) is not installed, or if the application installed is not the
+    #  same as the one specified.
+    #
+    # @note On Android, if a test-server is already running on the port of
+    #  {Calabash::Defaults#default_server Calabash.default_server} then that
+    #  application will be shut down.
+    #
+    # @param [String, Calabash::Application] path_or_application A path to the
+    #  application, or an instance of {Calabash::Application}.
+    #  Defaults to
+    #  {Calabash::Defaults#default_application Calabash.default_application}
+    # @param [Hash] options Options for specifying the details the app start
+    # @option options [Hash] :activity Android-only. Specify which activity
+    #  to start. If none is given, launch the default launchable activity.
+    # @option options [Hash] :extras Android-only. Specify the extras for the
+    #  startup intent.
+    def start_app(path_or_application = nil, **options)
+      path_or_application ||= Calabash.default_application
 
       unless path_or_application
-        raise 'No application given, and Application.default is not set'
+        raise 'No application given, and Calabash.default_application is not set'
       end
 
-      Device.default.start_app(path_or_application, opt.dup)
+      Device.default.start_app(path_or_application, options.dup)
     end
 
+    # Stop the app running on
+    # {Calabash::Defaults#default_server Calabash.default_server}
     def stop_app
       Device.default.stop_app
     end
 
     # Installs the given application. If the application is already installed,
     # the application will be uninstalled, and installed afterwards. If no
-    # application is given, it will install `Application.default`.
+    # application is given, it will install
+    # {Calabash::Defaults#default_application Calabash.default_application}
     #
     # If the given application is an instance of
-    # `Calabash::Android::Application`, the same procedure is executed for the
+    # {Calabash::Android::Application}, the same procedure is executed for the
     # test-server of the application, if it is set.
     #
     # @param [String, Calabash::Application] path_or_application A path to the
-    #  application, or an instance of `Calabash::Application`. Defaults to
-    #  `Application.default`
+    #  application, or an instance of {Calabash::Application}.
+    #  Defaults to
+    #  {Calabash::Defaults#default_application Calabash.default_application}
     def install_app(path_or_application = nil)
-      path_or_application ||= Application.default
+      path_or_application ||= Calabash.default_application
 
       unless path_or_application
-        raise 'No application given, and Application.default is not set'
+        raise 'No application given, and Calabash.default_application is not set'
       end
 
       Device.default.install_app(path_or_application)
     end
 
     # Installs the given application *if it is not already installed*. If no
-    # application is given, it will ensure `Application.default` is installed.
+    # application is given, it will ensure `Calabash.default_application` is installed.
     # If the application has changed, it will be installed using the same
-    # approach as #{Calabash::LifeCycle#install_app}.
+    # approach as {#install_app}.
     #
     # If the given application is an instance of
-    # `Calabash::Android::Application`, the same procedure is executed for the
+    # {Calabash::Android::Application}, the same procedure is executed for the
     # test-server of the application, if it is set.
     #
     # @param [String, Calabash::Application] path_or_application A path to the
-    #  application, or an instance of `Calabash::Application`. Defaults to
-    #  `Application.default`
+    #  application, or an instance of {Calabash::Application}.
+    #  Defaults to
+    #  {Calabash::Defaults#default_application Calabash.default_application}
     def ensure_app_installed(path_or_application = nil)
-      path_or_application ||= Application.default
+      path_or_application ||= Calabash.default_application
 
       unless path_or_application
-        raise 'No application given, and Application.default is not set'
+        raise 'No application given, and Calabash.default_application is not set'
       end
 
       Device.default.ensure_app_installed(path_or_application)
@@ -60,16 +95,17 @@ module Calabash
 
     # Uninstalls the given application. Does nothing if the application is
     # already uninstalled. If no application is given, it will uninstall
-    # `Application.default`.
+    # {Calabash::Defaults#default_application Calabash.default_application}
     #
     # @param [String, Calabash::Application] path_or_application A path to the
-    #  application, or an instance of `Calabash::Application`. Defaults to
-    #  `Application.default`
+    #  application, or an instance of {Calabash::Application}.
+    #  Defaults to
+    #  {Calabash::Defaults#default_application Calabash.default_application}
     def uninstall_app(path_or_application = nil)
-      path_or_application ||= Application.default
+      path_or_application ||= Calabash.default_application
 
       unless path_or_application
-        raise 'No application given, and Application.default is not set'
+        raise 'No application given, and Calabash.default_application is not set'
       end
 
       Device.default.uninstall_app(path_or_application)
@@ -77,27 +113,37 @@ module Calabash
 
     # Clears the contents of the given application. This is roughly equivalent to
     # reinstalling the application. If no  application is given, it will clear
-    # `Application.default`.
+    # {Calabash::Defaults#default_application Calabash.default_application}.
     #
     # @param [String, Calabash::Application] path_or_application A path to the
-    #  application, or an instance of `Calabash::Application`. Defaults to
-    #  `Application.default`
+    #  application, or an instance of {Calabash::Application}.
+    #  Defaults to
+    #  {Calabash::Defaults#default_application Calabash.default_application}
     def clear_app_data(path_or_application = nil)
-      path_or_application ||= Application.default
+      path_or_application ||= Calabash.default_application
 
       unless path_or_application
-        raise 'No application given, and Application.default is not set'
+        raise 'No application given, and Calabash.default_application is not set'
       end
 
       Device.default.clear_app_data(path_or_application)
     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 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.
     #
-    # On Android you can control the app lifecycle more granularly using
-    # #{Calabash::Android::Interactions#go_home} and
-    # #{Calabash::Android::LifeCycle#resume_app}.
+    # @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)