calabash 1.9.9.pre3 → 2.0.0.pre1

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,6 +59,7 @@ module Calabash
       super(*several_variants)
     end
 
+    # @!visibility private
     def ensure_in_bounds(index)
       if empty?
         raise IndexError, "Query result is empty"
@@ -65,6 +74,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,21 +28,65 @@ 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)
@@ -70,7 +114,7 @@ module Calabash
     end
 
     # @!visibility private
-    def _tap_current_keyboard_action_key
+    def _tap_keyboard_action_key(action_key)
       abstract_method!
     end
 

data/lib/calabash/utility.rb

@@ -5,7 +5,6 @@ module Calabash
 
   end
 
-  # @!visibility private
   module Utility
 
     # @!visibility private
@@ -27,8 +26,8 @@ module Calabash
     #
     # @example
     #  # These are equivalent.
-    #  pan(percent(20, 50), percent(20, 100))
-    #  pan({x: 20, y: 50}, {x: 20, y: 100})
+    #  pan("*", percent(20, 50), percent(20, 100))
+    #  pan("*", {x: 20, y: 50}, {x: 20, y: 100})
     #
     # @param [Number] x The value of the x percent.
     # @param [Number] y The value of the y percent.
@@ -50,6 +49,7 @@ module Calabash
     # @param [Number] x The value of the x.
     # @param [Number] y The value of the y.
     # @return [Hash] Representing the given values.
+    # @!visibility private
     def coordinate(x, y)
       {x: x, y: y}
     end

data/lib/calabash/version.rb

@@ -1,5 +1,5 @@
 module Calabash
 
   # @!visibility private
-  VERSION = '1.9.9.pre3'
+  VERSION = '2.0.0.pre1'
 end

data/lib/calabash/wait.rb

@@ -1,7 +1,6 @@
 module Calabash
 
   # A public API for waiting for things to happen.
-  # @!visibility private
   module Wait
     # @!visibility private
     class TimeoutError < RuntimeError
@@ -141,9 +140,15 @@ module Calabash
 
     # Waits for `query` to match one or more views.
     #
-    # @param [String] query Query to match view
+    # @example
+    #  wait_for_view({marked: 'mark'})
+    #
+    # @example
+    #  text = wait_for_view("myview")['text']
+    #
+    # @param [String, Hash, Calabash::Query] query Query to match view
     # @see Calabash::Wait#with_timeout for options
-    # @return [Object] The first view matching `query`.
+    # @return [Hash] The first view matching `query`.
     def wait_for_view(query, options={})
       if query.nil?
         raise ArgumentError, 'Query cannot be nil'
@@ -169,7 +174,9 @@ module Calabash
 
     # Waits for all `queries` to simultaneously match at least one view.
     #
-    # @param [Array<String>, String] queries List of queries or a query.
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query.
+    #
     # @see Calabash::Wait#with_timeout for options
     # @return [void] The return value for this method is undefined.
     def wait_for_views(*queries, **options)
@@ -200,7 +207,7 @@ module Calabash
 
     # Waits for `query` not to match any views
     #
-    # @param [String] query Query to match view
+    # @param [String, Hash, Calabash::Query] query Query to match view
     # @see Calabash::Wait#with_timeout for options
     def wait_for_no_view(query, options={})
       if query.nil?
@@ -226,7 +233,9 @@ module Calabash
 
     # Waits for all `queries` to simultaneously match no views
     #
-    # @param [Array<String>, String] queries List of queries or a query.
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query.
+    #
     # @see Calabash::Wait#with_timeout for options
     def wait_for_no_views(*queries, **options)
       if queries.nil? || queries.any?(&:nil?)
@@ -252,7 +261,7 @@ module Calabash
 
     # Does the given `query` match at least one view?
     #
-    # @param [String] query Query to match view
+    # @param [String, Hash, Calabash::Query] query Query to match view
     # @return [Object] Returns truthy if the `query` matches at least one view
     # @raise [ArgumentError] If given an invalid `query`
     def view_exists?(query)
@@ -271,7 +280,9 @@ module Calabash
 
     # Does the given `queries` all match at least one view?
     #
-    # @param [Array<String>, String] queries List of queries or a query
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query
+    #
     # @return Returns truthy if the `queries` all match at least one view
     # @raise [ArgumentError] If given an invalid list of queries
     def views_exist?(*queries)
@@ -291,7 +302,7 @@ module Calabash
     # Expect `query` to match at least one view. Raise an exception if it does
     # not.
     #
-    # @param [String] query Query to match view
+    # @param [String, Hash, Calabash::Query] query Query to match a view
     # @raise [ArgumentError] If given an invalid `query`
     # @raise [ViewNotFoundError] If `query` does not match at least one view
     def expect_view(query)
@@ -303,6 +314,8 @@ module Calabash
         raise ViewNotFoundError,
               "No view matched #{parse_query_list(query)}"
       end
+
+      true
     end
 
     alias_method :view_should_exist, :expect_view
@@ -310,7 +323,8 @@ module Calabash
     # Expect `queries` to each match at least one view. Raise an exception if
     # they do not.
     #
-    # @param [String] queries List of queries or a query
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query.
     # @raise [ArgumentError] If given an invalid list of queries
     # @raise [ViewNotFoundError] If `queries` do not all match at least one
     #   view.
@@ -323,12 +337,15 @@ module Calabash
         raise ViewNotFoundError,
               "Not all queries #{parse_query_list(queries)} matched a view"
       end
+
+      true
     end
 
     alias_method :views_should_exist, :expect_views
 
     # Expect `query` to match no views. Raise an exception if it does.
     #
+    # @param [String, Hash, Calabash::Query] query Query to match a view
     # @raise [ArgumentError] If given an invalid `query`
     # @raise [ViewFoundError] If `query` matches any views.
     def do_not_expect_view(query)
@@ -339,13 +356,16 @@ module Calabash
       if view_exists?(query)
         raise ViewFoundError, "A view matched #{parse_query_list(query)}"
       end
+
+      true
     end
 
     alias_method :view_should_not_exist, :do_not_expect_view
 
     # Expect `queries` to each match no views. Raise an exception if they do.
     #
-    # @param [Array<String>, String] queries List of queries or a query
+    # @param [String, Hash, Calabash::Query] queries List of queries or a
+    #  query.
     # @raise [ArgumentError] If given an invalid list of queries
     # @raise [ViewFoundError] If one of `queries` matched any views
     def do_not_expect_views(*queries)
@@ -357,6 +377,8 @@ module Calabash
         raise ViewFoundError,
               "Some views matched #{parse_query_list(queries)}"
       end
+
+      true
     end
 
     alias_method :views_should_not_exist, :do_not_expect_views

data/lib/calabash.rb

@@ -45,22 +45,58 @@ module Calabash
 
   require 'calabash/page'
 
-  # Instantiate a page object.
+  # Instantiate a page object for the current platform.
+  #
+  # @note Your pages **must** be in the scope of either Android or IOS. See the
+  #  examples for details.
   #
   # @example
-  #  # android/pages/login_page.rb
-  #  class Android::LoginPage < Calabash::Page
+  #  # android/pages/my_page.rb
+  #  class Android::MyPage < Calabash::Page
   #    include Calabash::Android
   #
-  #    [...]
+  #    # [...]
   #  end
   #
   #  # step definition
-  #  Given([...]) do
+  #  Given(/[...]/) do
   #    # Calabash will determine your platform and pick the Android page.
-  #    page(LoginPage).method
+  #    page(MyPage).method
+  #  end
+  #
+  # @example
+  #  # This example shows page code sharing across iOS and Android
+  #  # Please see the sample 'shared-page-logic' for details.
+  #  # pages/abstract_login_page.rb
+  #  class AbstractLoginPage < Calabash::Page
+  #    def login(username, password)
+  #     enter_text_in(username_field, username)
+  #     # [...]
+  #    end
+  #
+  #    private
+  #
+  #    def username_field
+  #      abstract_method!
+  #    end
   #  end
   #
+  #  # pages/android_login_page.rb
+  #  class Android::LoginPage < SharedLoginPage
+  #    include Calabash::Android
+  #
+  #    private
+  #
+  #    def username_field
+  #      "* marked:'a_username'"
+  #    end
+  #
+  #    # [...]
+  #  end
+  #
+  #
+  # @see #android?
+  # @see #ios?
   # @param [Class] page_class The page to instantiate
   # @return [Calabash::Page] An instance of the page class
   def page(page_class)
@@ -76,9 +112,11 @@ module Calabash
       raise ArgumentError, "Expected a 'Class', got '#{page_class.class}'"
     end
 
-    page_name = page_class.name.split('::').last
 
-    if platform_module.const_defined?(page_name, false)
+    page_name = page_class.name
+    full_page_name = "#{platform_module}::#{page_name}"
+
+    if Calabash.is_defined?(full_page_name)
       page_class = platform_module.const_get(page_name, false)
 
       if page_class.is_a?(Class)
@@ -93,18 +131,26 @@ module Calabash
         raise "Page '#{page_class}' is not a class"
       end
     else
-      raise "No such page defined '#{platform_module}::#{page_name}'"
+      raise "No such page defined '#{full_page_name}'"
     end
   end
 
-  # Is the app under test running on Android?
+  # Is the device under test running Android?
+  #
+  # @return [Boolean] Returns true if
+  #  {Calabash::Defaults#default_device Calabash.default_device} is an instance
+  #  of {Calabash::Android::Device}.
   def android?
-    Android.const_defined?(:Device) && Device.default.is_a?(Android::Device)
+    Android.const_defined?(:Device, false) && Device.default.is_a?(Android::Device)
   end
 
-  # Is the app under test running on iOS?
+  # Is the device under test running iOS?
+  #
+  # @return [Boolean] Returns true if
+  #  {Calabash::Defaults#default_device Calabash.default_device} is an instance
+  #  of {Calabash::IOS::Device}.
   def ios?
-    IOS.const_defined?(:Device) && Device.default.is_a?(IOS::Device)
+    IOS.const_defined?(:Device, false) && Device.default.is_a?(IOS::Device)
   end
 
   # @!visibility private
@@ -159,6 +205,29 @@ module Calabash
     end
   end
 
+  # @!visibility private
+  def self.is_defined?(string, scope = Object)
+    constant, rest = string.split('::', 2)
+
+    begin
+      scope.const_defined?(constant.to_sym, false) &&
+          (!rest || is_defined?(rest, scope.const_get(constant, false)))
+    rescue NameError => _
+      false
+    end
+  end
+
+  # @!visibility private
+  def self.recursive_const_get(string, scope = Object)
+    constant, rest = string.split('::', 2)
+
+    if rest
+      recursive_const_get(rest, scope.const_get(constant.to_sym, false))
+    else
+      scope.const_get(constant.to_sym, false)
+    end
+  end
+
   # @!visibility private
   def self.on_cucumber_context(base)
     on_new_context(base)
@@ -193,3 +262,45 @@ end
 unless Object.const_defined?(:IOS)
   Object.const_set(:IOS, Module.new)
 end
+
+if Calabash::Environment::DEBUG_CALLED_METHODS
+  $stdout.puts "#{Calabash::Color.red("Will print every Calabash method called!")}"
+  $stdout.puts "#{Calabash::Color.red("Warning: This might slow down your test drastically")}"
+  $stdout.puts "#{Calabash::Color.red("and is an experimental feature.")}"
+
+  calabash_file = Calabash.method(:extended).source_location.first
+  $__calabash_dir_name = File.dirname(calabash_file)
+
+  trace_func = lambda do |event, file, line, id, binding, classname|
+    if event == 'call'
+      if classname.to_s.split('::').first == 'Calabash'
+        binding_caller_locations = binding.eval("caller_locations")
+        files = binding_caller_locations[3..-1].map(&:path)
+
+        calabash_not_in_stacktrace = files.none? do |file|
+          file.start_with?($__calabash_dir_name) &&
+              File.basename(file) != 'page.rb'
+        end
+
+        if calabash_not_in_stacktrace
+          unless id == :included || id == :extended || id == :inherited
+            arguments = {}
+
+            binding.eval('local_variables').each do |variable|
+              arguments[variable] = binding.eval(variable.to_s)
+            end
+
+            # The arguments will be in order
+            if arguments.empty?
+              $stdout.puts "Calabash method called: #{id}"
+            else
+              $stdout.puts "Calabash method called: #{id}(#{arguments.values.map(&:inspect).join(', ')})"
+            end
+          end
+        end
+      end
+    end
+  end
+
+  set_trace_func(trace_func)
+end