calabash 1.9.9.pre3 → 2.0.0.prelegacy

data/lib/calabash/location.rb

@@ -1,7 +1,8 @@
 require 'geocoder'
 
 module Calabash
-  # @!visibility private
+
+  # An API for setting the location of your app.
   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

@@ -1,29 +1,75 @@
 module Calabash
+
+  # A base class for the Page Object Model (POM) or Page Object Pattern.
+  #
+  # We recommend the POM for testing cross-platform apps.
+  #
+  # We have a great examples of using the POM in the Calabash 2.0 repository.
+  #   * https://github.com/calabash/calabash/tree/develop/samples/wordpress
+  #   * https://github.com/calabash/calabash/tree/develop/samples/shared-page-logic
   class Page
     # For auto-completion
     include Calabash
 
+    # @!visibility private
     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
 
     private_class_method :new
 
+    # @!visibility private
     def initialize(world)
       @world = world
     end
 
+    # A query that distinguishes your page.
+    # @return [String, Hash, Calabash::Query] A query.
     def trait
       raise 'Implement your own trait'
     end
 
+    # Waits for the page trait to appear.
     def await(options={})
       wait_for_view(trait, options)
     end

data/lib/calabash/patch.rb

@@ -3,6 +3,7 @@ module Calabash
   module Patch
     require 'calabash/patch/array'
 
+    # @!visibility private
     def self.apply_patches!
       modules = Patch.constants(false)
 

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 =
         [
             {

data/lib/calabash/query_result.rb

@@ -4,6 +4,7 @@ module Calabash
   # It will, unlike `Array`, raise an IndexError instead of returning nil if
   # an entry outside bounds is accessed.
   class QueryResult < Array
+    # @!visibility private
     def self.create(result, query)
       query_result = QueryResult.send(:new, query)
       query_result.send(:initialize_copy, result)
@@ -13,36 +14,43 @@ module Calabash
 
     private_class_method :new
 
+    # @!visibility private
     attr_reader :query
 
+    # @!visibility private
     def initialize(query)
       @query = Query.new(query)
     end
 
+    # @!visibility private
     def first(*several_variants)
       ensure_in_bounds(0)
 
       super(*several_variants)
     end
 
+    # @!visibility private
     def last(*several_variants)
       ensure_in_bounds(-1)
 
       super(*several_variants)
     end
 
+    # @!visibility private
     def [](index)
       ensure_in_bounds(index)
 
       super(index)
     end
 
+    # @!visibility private
     def at(index)
       ensure_in_bounds(index)
 
       super(index)
     end
 
+    # @!visibility private
     def fetch(*several_variants)
       unless block_given? || several_variants.length > 1
         ensure_in_bounds(several_variants.first)
@@ -51,7 +59,12 @@ module Calabash
       super(*several_variants)
     end
 
+    # @!visibility private
     def ensure_in_bounds(index)
+      unless index.is_a?(Numeric)
+        return true
+      end
+
       if empty?
         raise IndexError, "Query result is empty"
       end
@@ -65,6 +78,7 @@ module Calabash
       end
     end
 
+    # @!visibility private
     def self.recursive_freeze(object)
       if object.is_a?(Array)
         object.each do |entry|

data/lib/calabash/screenshot.rb

@@ -4,7 +4,6 @@ require 'pathname'
 module Calabash
 
   # A public API for taking screenshots.
-  # @!visibility private
   module Screenshot
     # @!visibility private
     def self.screenshot_directory_prefix
@@ -12,6 +11,7 @@ module Calabash
     end
 
     # Set the screenshot directory prefix.
+    # @!visibility private
     def self.screenshot_directory_prefix=(value)
       if class_variable_defined?(:@@screenshots_taken) &&
           @@screenshots_taken != 0
@@ -24,22 +24,36 @@ module Calabash
     # @!visibility private
     self.screenshot_directory_prefix = 'test_run_'
 
-    # Takes a screenshot and saves it. The file is stored in the directory
-    # given by the ENV variable $CAL_SCREENSHOT_DIR, or by default in
-    # the relative directory 'screenshots'. The files are saved in a
+    # Takes a screenshot and saves it.
+    #
+    # If `name` is a relative path or a file name, then the file is stored in
+    # the directory specified by the ENV variable CAL_SCREENSHOT_DIR, or by
+    # default in the relative directory 'screenshots'. The files are saved in a
     # sub directory named test_run_n, where n is unique and incrementing for
     # each new test run. The filename of the screenshot will be `name`.
     # If `name` is not given (nil), the screenshot will be saved as
     # screenshot_N, where N is the total amount of screenshots taken for the
     # test run.
     #
+    # If the name given is an absolute path, then Calabash will save the
+    # screenshot to the absolute directory given.
+    #
+    # If the name given starts with ./ (e.g. `screenshot('./foo.png')`) then
+    # the filename will be saved relative to the current working directory.
+    #
+    # If the file specified by `name` has no extension then the filename will
+    # default to name + '.png'.
+    #
+    # If the directories specified do not exist, Calabash will create them.
+    #
     # @param [String] name Name of the screenshot.
     # @return [String] Path to the screenshot
     def screenshot(name=nil)
       Device.default.screenshot(name)
     end
 
-    # Takes a screenshot and embeds it in the test report.
+    # Takes a screenshot and embeds it in the test report. This method is only
+    # available/useful when running in the context of cucumber.
     # @see Screenshot#screenshot
     def screenshot_embed(name=nil)
       path = screenshot(name)
@@ -58,11 +72,17 @@ module Calabash
 
       @@screenshots_taken += 1
 
-      unless Dir.exist?(File.expand_path(screenshot_directory))
-        FileUtils.mkdir_p(File.expand_path(screenshot_directory))
+      if name.start_with?('./')
+        name = File.join(Dir.pwd, "#{name[2..-1]}")
+      end
+
+      file_name = File.expand_path(name, screenshot_directory)
+
+      unless Dir.exist?(File.dirname(file_name))
+        FileUtils.mkdir_p(File.dirname(file_name))
       end
 
-      File.join(screenshot_directory, name)
+      file_name
     end
 
     # @!visibility private

data/lib/calabash/text.rb

@@ -1,7 +1,6 @@
 module Calabash
 
   # A public API for entering text.
-  # @!visibility private
   module Text
     # Enter `text` into the currently focused view.
     #
@@ -15,7 +14,8 @@ module Calabash
     # @see Calabash::Text#enter_text
     #
     # @param [String] text The text to type.
-    # @param query A query describing the view to enter text into.
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #  to enter text into.
     def enter_text_in(query, text)
       _enter_text_in(query, text)
     end
@@ -28,27 +28,110 @@ module Calabash
     # Clears the text `view`
     # @see Calabash::Text#clear_text
     #
-    # @param query A query describing the view to clear text in.
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #  to clear text in.
     def clear_text_in(query)
       _clear_text_in(query)
     end
 
-    # @todo add docs
-    def tap_current_keyboard_action_key
-      _tap_current_keyboard_action_key
+    # Taps the keyboard action key. On iOS there is only one action key, which
+    # is the blue coloured key on the standard keyboard. On Android, there can
+    # be multiple actions keys available depending on the keyboard, but one key
+    # is often replacing the enter key, becoming the default action key. The
+    # view in focus on Android asks to keyboard to show one action key, but the
+    # keyboard might not adhere to this.
+    #
+    # On iOS some examples include:
+    #  * Return
+    #  * Next
+    #  * Go
+    #  * Join
+    #  * Search
+    #
+    # On Android some examples include:
+    #  * Search
+    #  * Next
+    #  * Previous
+    #
+    # See http://developer.android.com/reference/android/view/inputmethod/EditorInfo.html
+    #
+    # @example
+    #  tap_keyboard_action_key(:search)
+    #  tap_keyboard_action_key(:send)
+    #  tap_keyboard_action_key(:next)
+    #  tap_keyboard_action_key(:previous)
+    #
+    # Notice that, for Android, Calabash does not ensure that this particular action key is
+    # actually available on the current keyboard.
+    #
+    # Not all keyboards have an action key. For example, on iOS, numeric keyboards
+    # do not have an action key. On Android, if no action key is set for the
+    # view, the enter key is pressed instead.
+    #
+    # @param [Symbol] action_key The action key to press. This is only
+    #  used for Android.
+    # @raise [ArgumentError] If action_key if set for iOS.
+    def tap_keyboard_action_key(action_key = nil)
+      _tap_keyboard_action_key(action_key)
+      true
     end
 
     # Escapes single quotes in `string`.
     #
     # @example
-    #   > escape_quotes("Let's get this done.")
+    #   escape_single_quotes("Let's get this done.")
     #   => "Let\\'s get this done."
+    #
+    # @example
+    #  query("* text:'#{escape_single_quotes("Let's go")}'")
+    #  # Equivalent to
+    #  query("* text:'Let\\'s go'")
+    #
     # @param [String] string The string to escape.
     # @return [String] A string with its single quotes properly escaped.
     def escape_single_quotes(string)
       Text.escape_single_quotes(string)
     end
 
+    # Returns true if there is a visible keyboard.
+    # On Android, if a physical keyboard is connected, this method will always
+    # return true.
+    #
+    # @return [Boolean] Returns true if there is a visible keyboard.
+    def keyboard_visible?
+      _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
+
     # @!visibility private
     def _enter_text(text)
       abstract_method!
@@ -70,7 +153,12 @@ module Calabash
     end
 
     # @!visibility private
-    def _tap_current_keyboard_action_key
+    def _tap_keyboard_action_key(action_key)
+      abstract_method!
+    end
+
+    # @!visibility private
+    def _keyboard_visible?
       abstract_method!
     end
 
@@ -78,5 +166,14 @@ module Calabash
     def self.escape_single_quotes(string)
       string.gsub("'", "\\\\'")
     end
+
+    # @!visibility private
+    def keyboard_wait_timeout(timeout)
+      if timeout.nil?
+        Calabash::Gestures::DEFAULT_GESTURE_WAIT_TIMEOUT
+      else
+        timeout
+      end
+    end
   end
 end