capybara 2.0.3 → 2.1.0.beta1

data/lib/capybara/helpers.rb

@@ -1,31 +1,120 @@
 # encoding: UTF-8
 
 module Capybara
+
+  # @api private
   module Helpers
-    class << self
-      ##
-      #
-      # Normalizes whitespace space by stripping leading and trailing
-      # whitespace and replacing sequences of whitespace characters
-      # with a single space.
-      #
-      # @param [String] text     Text to normalize
-      # @return [String]         Normalized text
-      #
-      def normalize_whitespace(text)
-        text.to_s.gsub(/[[:space:]]+/, ' ').strip
+    extend self
+
+    ##
+    #
+    # Normalizes whitespace space by stripping leading and trailing
+    # whitespace and replacing sequences of whitespace characters
+    # with a single space.
+    #
+    # @param [String] text     Text to normalize
+    # @return [String]         Normalized text
+    #
+    def normalize_whitespace(text)
+      text.to_s.gsub(/[[:space:]]+/, ' ').strip
+    end
+
+    ##
+    #
+    # Escapes any characters that would have special meaning in a regexp
+    # if text is not a regexp
+    #
+    # @param [String] text Text to escape
+    # @return [String]     Escaped text
+    #
+    def to_regexp(text)
+      text.is_a?(Regexp) ? text : Regexp.new(Regexp.escape(normalize_whitespace(text)))
+    end
+
+    ##
+    #
+    # Injects a `<base>` tag into the given HTML code, pointing to
+    # `Capybara.asset_host`.
+    #
+    # @param [String] html     HTML code to inject into
+    # @param [String]          The modified HTML code
+    #
+    def inject_asset_host(html)
+      if Capybara.asset_host
+        if Nokogiri::HTML(html).css("base").empty? and match = html.match(/<head[^<]*?>/)
+          html.clone.insert match.end(0), "<base href='#{Capybara.asset_host}' />"
+        end
+      else
+        html
       end
+    end
+
+    ##
+    #
+    # Checks if the given count matches the given count options. By default,
+    # when no options are given, count should be larger than zero.
+    #
+    # @param [Integer] count     The actual number. Should be coercible via Integer()
+    # @option [Range] between    Count must be within the given range
+    # @option [Integer] count    Count must be exactly this
+    # @option [Integer] maximum  Count must be smaller than or equal to this value
+    # @option [Integer] minimum  Count must be larger than or equal to this value
+    #
+    def matches_count?(count, options={})
+      case
+      when options[:between]
+        options[:between] === count
+      when options[:count]
+        Integer(options[:count]) == count
+      when options[:maximum]
+        Integer(options[:maximum]) >= count
+      when options[:minimum]
+        Integer(options[:minimum]) <= count
+      else
+        count > 0
+      end
+    end
+
+    ##
+    #
+    # Generates a failure message given a description of the query and count
+    # options.
+    #
+    # @param [String] description   Description of a query
+    # @option [Range] between       Count should have been within the given range
+    # @option [Integer] count       Count should have been exactly this
+    # @option [Integer] maximum     Count should have been smaller than or equal to this value
+    # @option [Integer] minimum     Count should have been larger than or equal to this value
+    #
+    def failure_message(description, options={})
+      message = "expected to find #{description}"
+      if options[:count]
+        message << " #{options[:count]} #{declension('time', 'times', options[:count])}"
+      elsif options[:between]
+        message << " between #{options[:between].first} and #{options[:between].last} times"
+      elsif options[:maximum]
+        message << " at most #{options[:maximum]} #{declension('time', 'times', options[:maximum])}"
+      elsif options[:minimum]
+        message << " at least #{options[:minimum]} #{declension('time', 'times', options[:minimum])}"
+      end
+      message
+    end
 
-      ##
-      #
-      # Escapes any characters that would have special meaning in a regexp
-      # if text is not a regexp
-      #
-      # @param [String] text Text to escape
-      # @return [String]     Escaped text
-      #
-      def to_regexp(text)
-        text.is_a?(Regexp) ? text : Regexp.escape(normalize_whitespace(text))
+    ##
+    #
+    # A poor man's `pluralize`. Given two declensions, one singular and one
+    # plural, as well as a count, this will pick the correct declension. This
+    # way we can generate gramatically correct error message.
+    #
+    # @param [String] singular     The singular form of the word
+    # @param [String] plural       The plural form of the word
+    # @param [Integer] count       The number of items
+    #
+    def declension(singular, plural, count)
+      if count == 1
+        singular
+      else
+        plural
       end
     end
   end

data/lib/capybara/node/actions.rb

@@ -9,8 +9,8 @@ module Capybara
       #
       # @param [String] locator      Text, id or value of link or button
       #
-      def click_link_or_button(locator)
-        find(:link_or_button, locator).click
+      def click_link_or_button(locator, options={})
+        find(:link_or_button, locator, options).click
       end
       alias_method :click_on, :click_link_or_button
 
@@ -20,9 +20,11 @@ module Capybara
       # alt text inside the link.
       #
       # @param [String] locator      Text, id or text of link
+      # @param options
+      # @option options [String] :href    The value the href attribute must be
       #
-      def click_link(locator)
-        find(:link, locator).click
+      def click_link(locator, options={})
+        find(:link, locator, options).click
       end
 
       ##
@@ -31,8 +33,8 @@ module Capybara
       #
       # @param [String] locator      Text, id or value of button
       #
-      def click_button(locator)
-        find(:button, locator).click
+      def click_button(locator, options={})
+        find(:button, locator, options).click
       end
 
       ##
@@ -47,7 +49,8 @@ module Capybara
       #
       def fill_in(locator, options={})
         raise "Must pass a hash containing 'with'" if not options.is_a?(Hash) or not options.has_key?(:with)
-        find(:fillable_field, locator).set(options[:with])
+        with = options.delete(:with)
+        find(:fillable_field, locator, options).set(with)
       end
 
       ##
@@ -59,8 +62,8 @@ module Capybara
       #
       # @param [String] locator           Which radio button to choose
       #
-      def choose(locator)
-        find(:radio_button, locator).set(true)
+      def choose(locator, options={})
+        find(:radio_button, locator, options).set(true)
       end
 
       ##
@@ -72,8 +75,8 @@ module Capybara
       #
       # @param [String] locator           Which check box to check
       #
-      def check(locator)
-        find(:checkbox, locator).set(true)
+      def check(locator, options={})
+        find(:checkbox, locator, options).set(true)
       end
 
       ##
@@ -85,8 +88,8 @@ module Capybara
       #
       # @param [String] locator           Which check box to uncheck
       #
-      def uncheck(locator)
-        find(:checkbox, locator).set(false)
+      def uncheck(locator, options={})
+        find(:checkbox, locator, options).set(false)
       end
 
       ##
@@ -102,9 +105,10 @@ module Capybara
       #
       def select(value, options={})
         if options.has_key?(:from)
-          find(:select, options[:from]).find(:option, value).select_option
+          from = options.delete(:from)
+          find(:select, from, options).find(:option, value, options).select_option
         else
-          find(:option, value).select_option
+          find(:option, value, options).select_option
         end
       end
 
@@ -121,9 +125,10 @@ module Capybara
       #
       def unselect(value, options={})
         if options.has_key?(:from)
-          find(:select, options[:from]).find(:option, value).unselect_option
+          from = options.delete(:from)
+          find(:select, from, options).find(:option, value, options).unselect_option
         else
-          find(:option, value).unselect_option
+          find(:option, value, options).unselect_option
         end
       end
 
@@ -137,11 +142,11 @@ module Capybara
       # @param [String] locator       Which field to attach the file to
       # @param [String] path          The path of the file that will be attached, or an array of paths
       #
-      def attach_file(locator, path)
+      def attach_file(locator, path, options={})
         Array(path).each do |p|
           raise Capybara::FileNotFound, "cannot attach file, #{p} does not exist" unless File.exist?(p.to_s)
         end
-        find(:file_field, locator).set(path)
+        find(:file_field, locator, options).set(path)
       end
     end
   end

data/lib/capybara/node/base.rb

@@ -31,7 +31,6 @@ module Capybara
       def initialize(session, base)
         @session = session
         @base = base
-        @unsynchronized = false
       end
 
       # overridden in subclasses, e.g. Capybara::Node::Element
@@ -64,50 +63,44 @@ module Capybara
       # until a certain amount of time passes. The amount of time defaults to
       # {Capybara.default_wait_time} and can be overriden through the `seconds`
       # argument. This time is compared with the system time to see how much
-      # time has passed. If the return value of {Time.now} is stubbed out,
+      # time has passed. If the return value of `Time.now` is stubbed out,
       # Capybara will raise `Capybara::FrozenInTime`.
       #
-      # @param [Integer] seconds          Number of seconds to retry this block
+      # @param  [Integer] seconds         Number of seconds to retry this block
       # @return [Object]                  The result of the given block
-      # @raise [Capybara::FrozenInTime]   If the return value of {Time.now} appears stuck
+      # @raise  [Capybara::FrozenInTime]  If the return value of `Time.now` appears stuck
       #
       def synchronize(seconds=Capybara.default_wait_time)
         start_time = Time.now
 
-        begin
+        if session.synchronized
           yield
-        rescue => e
-          raise e if @unsynchronized
-          raise e unless driver.wait?
-          raise e unless driver.invalid_element_errors.include?(e.class) || e.is_a?(Capybara::ElementNotFound)
-          raise e if (Time.now - start_time) >= seconds
-          sleep(0.05)
-          raise Capybara::FrozenInTime, "time appears to be frozen, Capybara does not work with libraries which freeze time, consider using time travelling instead" if Time.now == start_time
-          reload if Capybara.automatic_reload
-          retry
+        else
+          session.synchronized = true
+          begin
+            yield
+          rescue => e
+            raise e unless driver.wait?
+            raise e unless catch_error?(e)
+            raise e if (Time.now - start_time) >= seconds
+            sleep(0.05)
+            raise Capybara::FrozenInTime, "time appears to be frozen, Capybara does not work with libraries which freeze time, consider using time travelling instead" if Time.now == start_time
+            reload if Capybara.automatic_reload
+            retry
+          ensure
+            session.synchronized = false
+          end
         end
       end
 
-      ##
-      #
-      # Within the given block, prevent synchronize from having any effect.
-      #
-      # This is an internal method which should not be called unless you are
-      # absolutely sure of what you're doing.
-      #
-      # @api private
-      # @return [Object]                  The result of the given block
-      #
-      def unsynchronized
-        orig = @unsynchronized
-        @unsynchronized = true
-        yield
-      ensure
-        @unsynchronized = orig
-      end
-
     protected
 
+      def catch_error?(error)
+        (driver.invalid_element_errors + [Capybara::ElementNotFound]).any? do |type|
+          error.is_a?(type)
+        end
+      end
+
       def driver
         session.driver
       end

data/lib/capybara/node/document.rb

@@ -17,8 +17,12 @@ module Capybara
       #
       # @return [String]    The text of the document
       #
-      def text
-        find(:xpath, '/html').text
+      def text(type=nil)
+        find(:xpath, '/html').text(type)
+      end
+
+      def title
+        session.driver.title
       end
     end
   end

data/lib/capybara/node/element.rb

@@ -42,10 +42,26 @@ module Capybara
 
       ##
       #
-      # @return [String]    The text of the element
-      #
-      def text
-        synchronize { base.text }
+      # Retrieve the text of the element. If `Capybara.ignore_hidden_elements`
+      # is `true`, which it is by default, then this will return only text
+      # which is visible. The exact semantics of this may differ between
+      # drivers, but generally any text within elements with `display:none` is
+      # ignored. This behaviour can be overridden by passing `:all` to this
+      # method.
+      #
+      # @param [:all, :visible]    Whether to return only visible or all text
+      #
+      # @return [String]           The text of the element
+      #
+      def text(type=nil)
+        type ||= :all unless Capybara.ignore_hidden_elements or Capybara.visible_text_only
+        synchronize do
+          if type == :all
+            base.all_text
+          else
+            base.visible_text
+          end
+        end
       end
 
       ##
@@ -103,6 +119,14 @@ module Capybara
         synchronize { base.click }
       end
 
+      ##
+      #
+      # Hover on the Element
+      #
+      def hover
+        synchronize { base.hover }
+      end
+
       ##
       #
       # @return [String]      The tag name of the element
@@ -142,6 +166,16 @@ module Capybara
         synchronize { base.selected? }
       end
 
+      ##
+      #
+      # Whether or not the element is disabled.
+      #
+      # @return [Boolean]     Whether the element is disabled
+      #
+      def disabled?
+        synchronize { base.disabled? }
+      end
+
       ##
       #
       # An XPath expression describing where on the page the element can be found
@@ -179,15 +213,19 @@ module Capybara
 
       def reload
         if @allow_reload
-          reloaded = parent.reload.first(@query.name, @query.locator, @query.options)
-          @base = reloaded.base if reloaded
+          begin
+            reloaded = parent.reload.first(@query.name, @query.locator, @query.options)
+            @base = reloaded.base if reloaded
+          rescue => e
+            raise e unless catch_error?(e)
+          end
         end
         self
       end
 
       def inspect
         %(#<Capybara::Element tag="#{tag_name}" path="#{path}">)
-      rescue NotSupportedByDriverError
+      rescue NotSupportedByDriverError, 'Capybara::Node::Element#inspect'
         %(#<Capybara::Element tag="#{tag_name}">)
       end
     end

data/lib/capybara/node/finders.rb

@@ -19,11 +19,29 @@ module Capybara
       #     page.find('li', :text => 'Quox').click_link('Delete')
       #
       # @param (see Capybara::Node::Finders#all)
-      # @return [Capybara::Element]           The found element
-      # @raise  [Capybara::ElementNotFound]   If the element can't be found before time expires
+      # @option options [Boolean] match        The matching strategy to use.
+      # @option options [false, Numeric] wait  How long to wait for the element to appear.
+      #
+      # @return [Capybara::Element]            The found element
+      # @raise  [Capybara::ElementNotFound]    If the element can't be found before time expires
       #
       def find(*args)
-        synchronize { all(*args).find! }.tap(&:allow_reload!)
+        query = Capybara::Query.new(*args)
+        synchronize(query.wait) do
+          if query.match == :smart or query.match == :prefer_exact
+            result = resolve_query(query, true)
+            result = resolve_query(query, false) if result.size == 0 and not query.exact?
+          else
+            result = resolve_query(query)
+          end
+          if query.match == :one or query.match == :smart and result.size > 1
+            raise Capybara::Ambiguous.new("Ambiguous match, found #{result.size} elements matching #{query.description}")
+          end
+          if result.size == 0
+            raise Capybara::ElementNotFound.new("Unable to find #{query.description}")
+          end
+          result.first
+        end.tap(&:allow_reload!)
       end
 
       ##
@@ -33,8 +51,8 @@ module Capybara
       # @param [String] locator       Which field to find
       # @return [Capybara::Element]   The found element
       #
-      def find_field(locator)
-        find(:field, locator)
+      def find_field(locator, options={})
+        find(:field, locator, options)
       end
       alias_method :field_labeled, :find_field
 
@@ -45,8 +63,8 @@ module Capybara
       # @param [String] locator       Which link to find
       # @return [Capybara::Element]   The found element
       #
-      def find_link(locator)
-        find(:link, locator)
+      def find_link(locator, options={})
+        find(:link, locator, options)
       end
 
       ##
@@ -56,8 +74,8 @@ module Capybara
       # @param [String] locator       Which button to find
       # @return [Capybara::Element]   The found element
       #
-      def find_button(locator)
-        find(:button, locator)
+      def find_button(locator, options={})
+        find(:button, locator, options)
       end
 
       ##
@@ -67,8 +85,8 @@ module Capybara
       # @param [String] id            Which element to find
       # @return [Capybara::Element]   The found element
       #
-      def find_by_id(id)
-        find(:id, id)
+      def find_by_id(id, options={})
+        find(:id, id, options)
       end
 
       ##
@@ -103,18 +121,12 @@ module Capybara
       #   @param [String] locator                    The selector
       #   @option options [String, Regexp] text      Only find elements which contain this text or match this regexp
       #   @option options [Boolean] visible          Only find elements that are visible on the page. Setting this to false
-      #                                              (the default, unless Capybara.ignore_hidden_elements = true), finds
-      #                                              invisible _and_ visible elements.
-      # @return [Array[Capybara::Element]]           The found elements
+      #                                              finds invisible _and_ visible elements.
+      #   @option options [Boolean] exact            Control whether `is` expressions in the given XPath match exactly or partially
+      # @return [Capybara::Result]                   A collection of found elements
       #
       def all(*args)
-        query = Capybara::Query.new(*args)
-        elements = synchronize do
-          base.find(query.xpath).map do |node|
-            Capybara::Node::Element.new(session, node, self, query)
-          end
-        end
-        Capybara::Result.new(elements, query)
+        resolve_query(Capybara::Query.new(*args))
       end
 
       ##
@@ -131,6 +143,21 @@ module Capybara
       def first(*args)
         all(*args).first
       end
+
+    private
+
+      def resolve_query(query, exact=nil)
+        elements = synchronize do
+          if query.selector.format==:css
+            base.find_css(query.css)
+          else
+            base.find_xpath(query.xpath(exact))
+          end.map do |node|
+            Capybara::Node::Element.new(session, node, self, query)
+          end
+        end
+        Capybara::Result.new(elements, query)
+      end
     end
   end
 end