calabash 1.9.9.pre3 → 2.0.0.pre1

data/lib/calabash/ios/runtime.rb

@@ -1,16 +1,160 @@
 module Calabash
   module IOS
-    # @!visibility private
+
+    # Methods that describe the runtime attributes of the device under test.
+    #
+    # @note The key/value pairs in the Hash returned by #runtime_details are
+    #  not stable and can change at any time.  Don't write tests that rely on
+    #  specific keys or values in this Hash.  Instead, use the API methods
+    #  defined in this class.
     module Runtime
 
-      # @todo Complete and document the Runtime API
+      # Is the device under test a simulator?
       def simulator?
         Calabash::IOS::Device.default.simulator?
       end
 
+      # Is the device under test a physical device?
       def physical_device?
         Calabash::IOS::Device.default.physical_device?
       end
+
+      # Is the device under test an iPad?
+      def ipad?
+        Calabash::IOS::Device.default.device_family == 'iPad'
+      end
+
+      # Is the device under test an iPhone?
+      def iphone?
+        Calabash::IOS::Device.default.device_family == 'iPhone'
+      end
+
+      # Is the device under test an iPod?
+      def ipod?
+        Calabash::IOS::Device.default.device_family == 'iPod'
+      end
+
+      # Is the device under test an iPhone or iPod?
+      def device_family_iphone?
+        iphone? or ipod?
+      end
+
+      # Is the app that is being tested an iPhone app emulated on an iPad?
+      #
+      # An iPhone only app running on an iPad will be displayed in an emulated
+      # mode.  Starting in iOS 7, such apps will always be launched in 2x mode.
+      def iphone_app_emulated_on_ipad?
+        Calabash::IOS::Device.default.iphone_app_emulated_on_ipad?
+      end
+
+      # Is the device under test have a 4 inch screen?
+      def iphone_4in?
+        Calabash::IOS::Device.default.form_factor == 'iphone 4in'
+      end
+
+      # Is the device under test an iPhone 6.
+      def iphone_6?
+        Calabash::IOS::Device.default.form_factor == 'iphone 6'
+      end
+
+      # Is the device under test an iPhone 6+?
+      def iphone_6_plus?
+        Calabash::IOS::Device.default.form_factor == 'iphone 6 +'
+      end
+
+      # Is the device under test an iPhone 3.5in?
+      def iphone_35in?
+        Calabash::IOS::Device.default.form_factor == 'iphone 3.5in'
+      end
+
+      # The screen dimensions and details about scale and sample rates.
+      #
+      # @example
+      #  > app_screen_details
+      #  => {
+      #        :height => 1,
+      #        :height => 1334,
+      #        :width => 750,
+      #        :scale => 2
+      #      }
+      #
+      # @return [Hash] See the example.
+      def app_screen_details
+        Calabash::IOS::Device.default.screen_dimensions
+      end
+
+      # The version of iOS running on the test device.
+      #
+      # @example
+      #  > ios_version.major
+      #  > ios_version.minor
+      #  > ios_version.patch
+      #
+      # @return [RunLoop::Version] A version object.
+      def ios_version
+        Calabash::IOS::Device.default.ios_version
+      end
+
+      # Is the device under test running iOS 6?
+      def ios6?
+        ios_version.major == 6
+      end
+
+      # Is the device under test running iOS 7?
+      def ios7?
+        ios_version.major == 7
+      end
+
+      # Is the device under test running iOS 8?
+      def ios8?
+        ios_version.major == 8
+      end
+
+      # Is the device under test running iOS 9?
+      def ios9?
+        ios_version.major == 9
+      end
+
+      # The version of the Calabash iOS Server running in the app.
+      #
+      # @example
+      #  > server_version.major
+      #  > server_version.minor
+      #  > server_version.patch
+      #
+      # @return [RunLoop::Version] A version object.
+      def server_version
+        Calabash::IOS::Device.default.server_version
+      end
+
+      # Details about the version of the app under test.
+      #
+      # Will always contain these two keys:
+      #
+      #  * :bundle_version => CFBundleVersion
+      #  * :short_version => CFBundleShortVersionString
+      #
+      # It may contain other key/value pairs.
+      #
+      # @return [Hash] Key/value pairs that describe the version of the app
+      #  under test.
+      def app_version_details
+        hash = runtime_details
+        {
+              :bundle_version => hash['app_version'],
+              :short_version => hash['short_version_string']
+        }
+      end
+
+      # A hash of all the details about the runtime environment.
+      #
+      # @note The key/value pairs in this Hash are subject to change.  Don't
+      #  write tests that rely on a specific key appearing in the Hash.  Use
+      #  the methods in the {Calabash::IOS::Runtime} module instead.
+      # @return[Hash] Key/value pairs that describe the runtime environment.
+      def runtime_details
+        Calabash::IOS::Device.default.runtime_details
+      end
     end
   end
 end

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)
@@ -128,7 +127,12 @@ 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

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

@@ -30,6 +30,7 @@ module Calabash
     require 'calabash/ios/scroll'
     require 'calabash/ios/runtime'
     require 'calabash/ios/gestures'
+    require 'calabash/ios/slider'
 
     include Calabash::IOS::Conditions
     include Calabash::IOS::Orientation
@@ -39,6 +40,7 @@ module Calabash
     include Calabash::IOS::Scroll
     include Calabash::IOS::Runtime
     include Calabash::IOS::Gestures
+    include Calabash::IOS::Slider
 
   end
 end

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

@@ -1,58 +1,85 @@
 module Calabash
-  # @!visibility private
   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 +87,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,16 +105,17 @@ 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)
@@ -96,8 +125,8 @@ module Calabash
     # `for_seconds`. This should not exceed 60 seconds for iOS.
     #
     # On Android you can control the app lifecycle more granularly using
-    # #{Calabash::Android::Interactions#go_home} and
-    # #{Calabash::Android::LifeCycle#resume_app}.
+    # {Calabash::Android::Interactions#go_home \#go_home} and
+    # {Calabash::Android::LifeCycle#resume_app \#resume_app}.
     def send_current_app_to_background(for_seconds = 10)
       _send_current_app_to_background(for_seconds)
 

data/lib/calabash/location.rb

@@ -1,7 +1,6 @@
 require 'geocoder'
 
 module Calabash
-  # @!visibility private
   module Location
     # Simulates gps location of the device/simulator.
     # @note Seems UIAutomation is broken here on physical devices on iOS 7.1

data/lib/calabash/orientation.rb

@@ -2,7 +2,6 @@ module Calabash
 
   # Methods for querying an app's orientation and for rotating the app into
   # different orientations.
-  # @!visibility private
   module Orientation
     # Is the device in the portrait orientation?
     #

data/lib/calabash/page.rb

@@ -5,12 +5,45 @@ module Calabash
 
     def self.inherited(subclass)
       # Define the page into global scope
-      name = subclass.to_s.split('::').last
+      full_name = subclass.name
 
-      unless Object.const_defined?(name.to_sym)
-        # We need a unique type for this constant
-        clz = Class.new(StubPage)
-        Object.const_set(name.to_sym, clz)
+      if full_name == 'IOS' || full_name == 'Android'
+        raise "Invalid page name '#{full_name}'"
+      end
+
+      os_scope = full_name.split('::').first
+
+      if os_scope == 'IOS' || os_scope == 'Android'
+        page_name = full_name.split('::', 2).last
+
+        unless Calabash.is_defined?(page_name)
+          scopes = page_name.split('::')
+
+          previous_scope = ''
+
+          scopes[0..-2].each do |scope|
+            old_scope = Calabash.recursive_const_get("Object::#{os_scope}#{previous_scope}")
+            new_scope = Calabash.recursive_const_get("Object#{previous_scope}")
+
+            old_const = old_scope.const_get(scope.to_sym)
+
+            if new_scope.const_defined?(scope.to_sym)
+              new_scope.send(:remove_const, scope.to_sym)
+            end
+
+            new_scope.const_set(scope.to_sym, old_const.class.allocate)
+
+            previous_scope << "::#{scope}"
+          end
+
+          simple_page_name = page_name.split('::').last.to_sym
+          new_scope = Calabash.recursive_const_get("Object#{previous_scope}")
+
+          unless new_scope.const_defined?(simple_page_name, false)
+            clz = Class.new(StubPage)
+            new_scope.const_set(simple_page_name, clz)
+          end
+        end
       end
     end
 

data/lib/calabash/patch/array.rb

@@ -4,13 +4,13 @@ module Calabash
 
     # @!visibility private
     module Array
-      def to_pct
-        if length != 2
-          raise RangeError, "Cannot convert #{self} to {:x, :y} hash"
-        end
-
-        {x: self.[](0), y: self.[](1)}
-      end
+#      def to_pct
+#        if length != 2
+#          raise RangeError, "Cannot convert #{self} to {:x, :y} hash"
+#        end
+#
+#        {x: self.[](0), y: self.[](1)}
+#      end
     end
   end
 end

data/lib/calabash/query.rb

@@ -1,8 +1,6 @@
 module Calabash
 
   # A representation of a Calabash query.
-  # @todo Query needs more documentation.
-  # @todo Query needs some methods moved to private or doc'd private.
   class Query
     # @!visibility private
     def self.web_query?(query_string)
@@ -110,6 +108,13 @@ module Calabash
       result
     end
 
+    # Create a new query. The returned instance will be frozen (immutable).
+    #
+    # @example
+    #  Calabash::Query.new({marked: 'mark'})
+    #  Calabash::Query.new("myview")
+    #
+    # @param [String, Hash, Calabash::Query] query The query to create
     def initialize(query)
       unless query.is_a?(Query) || query.is_a?(Hash) || query.is_a?(String)
         raise ArgumentError, "Invalid argument for query: '#{query}' (#{query.class})"
@@ -120,6 +125,13 @@ module Calabash
       freeze
     end
 
+    # Parse the query to it's string representation.
+    #
+    # @example
+    #  puts Calabash::Query.new({marked: 'foo'})
+    #  # => "* marked:'foo'"
+    #
+    # @!visibility private
     def to_s
       if @query.is_a?(Query)
         @query.to_s
@@ -130,14 +142,17 @@ module Calabash
       end
     end
 
+    # @!visibility private
     def inspect
       "<Calabash::Query #{@query.inspect}>"
     end
 
+    # @!visibility private
     def web_query?
       Query.web_query?(to_s)
     end
 
+    # @!visibility private
     WEB_QUERY_INDICATORS =
         [
             {