calabash 1.2.1 → 1.9.9.pre1

data/lib/calabash/query.rb

@@ -0,0 +1,160 @@
+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)
+      # :no, :double or :single
+      in_quotes = :no
+
+      # Number of slashes before the current char
+      slash_count = 0
+
+      # If the query starts with css: or xpath:
+      # We could change the regex from /(\s|\'|\")css:/ to /(^|\s|\'|\")css:/
+      # and change if (query[i, indicator[:length]] =~ indicator[:regex]) == 0
+      # to if (query[0, i+indicator[:length]] =~ indicator[:regex]) == i
+      # (not working)
+      # to avoid having to do this check.
+      results = WEB_QUERY_INDICATORS.map do |indicator|
+        query_string =~ /^\s*#{indicator[:string]}/
+      end
+
+      if results.any?
+        return true
+      end
+
+      length = query_string.length
+
+      length.times do |i|
+        char = query_string[i]
+
+        if char == "\\"
+          slash_count += 1
+          next
+        end
+
+        if char == "'"
+          if slash_count == 0
+            if in_quotes == :no
+              in_quotes = :single
+            elsif in_quotes == :single
+              in_quotes = :no
+            end
+          end
+        elsif char == '"'
+          if slash_count == 0
+            if in_quotes == :no
+              in_quotes = :double
+            elsif in_quotes == :double
+              in_quotes = :no
+            end
+          end
+        end
+
+        if slash_count == 0 && in_quotes == :no
+          WEB_QUERY_INDICATORS.each do |indicator|
+            if (query_string[i, indicator[:length]] =~ indicator[:regex]) == 0
+              return true
+            end
+          end
+        end
+
+        slash_count = 0
+      end
+
+      false
+    end
+
+    # @!visibility private
+    def self.query_hash_to_string(hash)
+      result = hash.fetch(:class, '*')
+
+      if hash[:marked] && (hash[:id] || hash[:text])
+        raise 'Cannot use both marked and id/text'
+      end
+
+      if hash[:marked]
+        result = "#{result} marked:'#{Text.escape_single_quotes(hash[:marked])}'"
+      end
+
+      if hash[:id]
+        result = "#{result} id:'#{Text.escape_single_quotes(hash[:id])}'"
+      end
+
+      if hash[:text]
+        result = "#{result} text:'#{Text.escape_single_quotes(hash[:text])}'"
+      end
+
+      if hash[:index]
+        result = "#{result} index:#{hash[:index]}"
+      end
+
+      if hash[:css]
+        result = "#{result} css:'#{Text.escape_single_quotes(hash[:css])}'"
+      end
+
+      if hash[:xpath]
+        result = "#{result} xpath:'#{Text.escape_single_quotes(hash[:xpath])}'"
+      end
+
+      result
+    end
+
+    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})"
+      end
+
+      @query = query.dup
+
+      freeze
+    end
+
+    def to_s
+      if @query.is_a?(Query)
+        @query.to_s
+      elsif @query.is_a?(Hash)
+        Query.query_hash_to_string(@query)
+      else
+        @query.dup
+      end
+    end
+
+    def inspect
+      "<Calabash::Query #{@query.inspect}>"
+    end
+
+    def web_query?
+      Query.web_query?(to_s)
+    end
+
+    WEB_QUERY_INDICATORS =
+        [
+            {
+                string: 'css:',
+                regex: /(\s|\'|\")css:/,
+                length: 5
+            },
+            {
+                string: 'xpath:',
+                regex: /(\s|\'|\")xpath:/,
+                length: 7
+            }
+        ]
+
+    # @!visibility private
+    def self.valid_query?(query)
+      query.is_a?(String) || query.is_a?(Hash) || query.is_a?(Query)
+    end
+
+    # @!visibility private
+    def self.ensure_valid_query(query)
+      unless valid_query?(query)
+        raise ArgumentError, "invalid query '#{query}' (#{query.class})"
+      end
+    end
+  end
+end

data/lib/calabash/query_result.rb

@@ -0,0 +1,85 @@
+module Calabash
+  # A QueryResult represents the returned value of a query.
+  # It is an immutable collection of matches or the result of applied methods.
+  # It will, unlike `Array`, raise an IndexError instead of returning nil if
+  # an entry outside bounds is accessed.
+  class QueryResult < Array
+    def self.create(result, query)
+      query_result = QueryResult.send(:new, query)
+      query_result.send(:initialize_copy, result)
+      recursive_freeze(query_result)
+      query_result
+    end
+
+    private_class_method :new
+
+    attr_reader :query
+
+    def initialize(query)
+      @query = Query.new(query)
+    end
+
+    def first(*several_variants)
+      ensure_in_bounds(0)
+
+      super(*several_variants)
+    end
+
+    def last(*several_variants)
+      ensure_in_bounds(-1)
+
+      super(*several_variants)
+    end
+
+    def [](index)
+      ensure_in_bounds(index)
+
+      super(index)
+    end
+
+    def at(index)
+      ensure_in_bounds(index)
+
+      super(index)
+    end
+
+    def fetch(*several_variants)
+      unless block_given? || several_variants.length > 1
+        ensure_in_bounds(several_variants.first)
+      end
+
+      super(*several_variants)
+    end
+
+    def ensure_in_bounds(index)
+      if empty?
+        raise IndexError, "Query result is empty"
+      end
+
+      if index > 0 && index >= length
+        raise IndexError, "Index out of bounds [index: #{index}, length: #{length}]"
+      end
+
+      if index < 0 && -index > length
+        raise IndexError, "Index out of bounds [index: #{index}, length: #{length}]"
+      end
+    end
+
+    def self.recursive_freeze(object)
+      if object.is_a?(Array)
+        object.each do |entry|
+          recursive_freeze(entry)
+        end
+      end
+
+      if object.is_a?(Hash)
+        object.each do |key, value|
+          recursive_freeze(key)
+          recursive_freeze(value)
+        end
+      end
+
+      object.freeze
+    end
+  end
+end

data/lib/calabash/screenshot.rb

@@ -0,0 +1,89 @@
+require 'fileutils'
+require 'pathname'
+
+module Calabash
+
+  # A public API for taking screenshots.
+  module Screenshot
+    # @!visibility private
+    def self.screenshot_directory_prefix
+      @@screenshot_directory_prefix
+    end
+
+    # Set the screenshot directory prefix.
+    def self.screenshot_directory_prefix=(value)
+      if class_variable_defined?(:@@screenshots_taken) &&
+          @@screenshots_taken != 0
+        raise 'Cannot change the screenshot directory prefix after a screenshot has been taken'
+      end
+
+      @@screenshot_directory_prefix = value
+    end
+
+    # @!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
+    # 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.
+    #
+    # @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.
+    # @see Screenshot#screenshot
+    def screenshot_embed(name=nil)
+      path = screenshot(name)
+      embed(path, 'image/png', name || File.basename(path))
+    end
+
+    # @!visibility private
+    def self.obtain_screenshot_path!(name=nil)
+      @@screenshots_taken ||= 1
+
+      if name.nil?
+        name = "screenshot_#{@@screenshots_taken}.png"
+      end
+
+      name = "#{name}.png" if File.extname(name).empty?
+
+      @@screenshots_taken += 1
+
+      unless Dir.exist?(File.expand_path(screenshot_directory))
+        FileUtils.mkdir_p(File.expand_path(screenshot_directory))
+      end
+
+      File.join(screenshot_directory, name)
+    end
+
+    # @!visibility private
+    def self.screenshot_directory
+      @@screenshot_directory ||= new_screenshot_sub_directory
+    end
+
+    # @!visibility private
+    def self.new_screenshot_sub_directory
+      count = screenshot_directory_test_run_directories.count
+      File.join(Environment::SCREENSHOT_DIRECTORY,
+                "#{screenshot_directory_prefix}#{count+1}")
+    end
+
+    # @!visibility private
+    def self.screenshot_directory_test_run_directories
+      dir = File.expand_path(File.join(Environment::SCREENSHOT_DIRECTORY, '*'))
+
+      Dir.glob(dir).select do |file|
+        File.directory?(file) &&
+        File.basename(file) =~ /^#{screenshot_directory_prefix}\d+$/
+      end
+    end
+  end
+end

data/lib/calabash/server.rb

@@ -0,0 +1,16 @@
+module Calabash
+
+  # A representation of the Calabash test server.
+  class Server
+    attr_reader :endpoint
+    attr_reader :test_server_port
+
+    # @param [URI] endpoint The endpoint to reach the test server.
+    # @param [Integer] test_server_port The port bound to the test server
+    #   running on the device.  On iOS this is same as the endpoint port.
+    def initialize(endpoint, test_server_port = nil)
+      @endpoint = endpoint
+      @test_server_port = test_server_port || endpoint.port
+    end
+  end
+end

data/lib/calabash/text.rb

@@ -0,0 +1,76 @@
+module Calabash
+
+  # A public API for entering text.
+  module Text
+    # Enter `text` into the currently focused view.
+    #
+    # @param [String] text The text to type.
+    # @raise [RuntimeError] if the text cannot be typed.
+    def enter_text(text)
+      Device.default.enter_text(text)
+    end
+
+    # Enter `text` into `query`.
+    # @see Calabash::Text#enter_text
+    #
+    # @param [String] text The text to type.
+    # @param query A query describing the view to enter text into.
+    def enter_text_in(query, text)
+      _enter_text_in(query, text)
+    end
+
+    # Clears the text of the currently focused view.
+    def clear_text
+      _clear_text
+    end
+
+    # Clears the text `view`
+    # @see Calabash::Text#clear_text
+    #
+    # @param query A query describing the view to clear text in.
+    def clear_text_in(view)
+      _clear_text_in(view)
+    end
+
+    # @todo add docs
+    def tap_current_keyboard_action_key
+      _tap_current_keyboard_action_key
+    end
+
+    # Escapes single quotes in `string`.
+    #
+    # @example
+    #   > escape_quotes("Let's get this done.")
+    #   => "Let\\'s get this done."
+    # @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
+
+    # @!visibility private
+    def _enter_text_in(view, text)
+      abstract_method!
+    end
+
+    # @!visibility private
+    def _clear_text
+      abstract_method!
+    end
+
+    # @!visibility private
+    def _clear_text_in(view)
+      abstract_method!
+    end
+
+    # @!visibility private
+    def _tap_current_keyboard_action_key
+      abstract_method!
+    end
+
+    # @!visibility private
+    def self.escape_single_quotes(string)
+      string.gsub("'", "\\\\'")
+    end
+  end
+end

data/lib/calabash/utility.rb

@@ -0,0 +1,58 @@
+module Calabash
+
+  # @!visibility private
+  class AbstractMethodError < StandardError
+
+  end
+
+  module Utility
+
+    # @!visibility private
+    def abstract_method!
+      method_name = if Kernel.method_defined?(:caller_locations)
+                      caller_locations.first.label
+                    else
+                      caller.first[/\`(.*)\'/, 1]
+                    end
+
+      raise AbstractMethodError.new("Abstract method '#{method_name}'")
+    end
+
+    # @! visibility private
+    class RetryError < RuntimeError; end
+
+    # A convenience method for creating a percentage hash that that can be
+    # passed to gestures.
+    #
+    # @example
+    #  # These are equivalent.
+    #  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.
+    # @return [Hash] Representing the given values.
+    def percent(x, y)
+      {x: x, y: y}
+    end
+
+    alias_method :pct, :percent
+
+    # A convenience method for creating a coordinate hash that that can be
+    # passed to gestures.
+    #
+    # @example
+    #  # These are equivalent.
+    #  tap(query, offset: coordinate(20, 50))
+    #  tap(query, offset: {x: 20, y: 50})
+    #
+    # @param [Number] x The value of the x.
+    # @param [Number] y The value of the y.
+    # @return [Hash] Representing the given values.
+    def coordinate(x, y)
+      {x: x, y: y}
+    end
+
+    alias_method :coord, :coordinate
+  end
+end