capybara 2.0.3 → 2.1.0

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
 
       ##
@@ -42,12 +44,13 @@ module Capybara
       #
       #     page.fill_in 'Name', :with => 'Bob'
       #
-      # @param [String] locator           Which field to fill in
-      # @param [Hash{:with => String}]    The value to fill in
+      # @param [String] locator                 Which field to fill in
+      # @param [Hash{:with => String}] options  The value to fill in
       #
       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
 
       ##
@@ -97,14 +100,15 @@ module Capybara
       #
       #     page.select 'March', :from => 'Month'
       #
-      # @param [String] value             Which option to select
-      # @param [Hash{:from => String}]    The id, name or label of the select box
+      # @param [String] value                   Which option to select
+      # @param [Hash{:from => String}] options  The id, name or label of the select box
       #
       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
 
@@ -116,14 +120,15 @@ module Capybara
       #
       #     page.unselect 'March', :from => 'Month'
       #
-      # @param [String] value             Which option to unselect
-      # @param [Hash{:from => String}]    The id, name or label of the select box
+      # @param [String] value                   Which option to unselect
+      # @param [Hash{:from => String}] options  The id, name or label of the select box
       #
       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,25 @@ 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] type  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 +118,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 +165,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 +212,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
 
       ##
@@ -125,12 +137,27 @@ module Capybara
       # @overload first([kind], locator, options)
       #   @param [:css, :xpath] kind                 The type of selector
       #   @param [String] locator                    The selector
-      #   @param [Hash] options                      Additional options; see {all}
+      #   @param [Hash] options                      Additional options; see {#all}
       # @return [Capybara::Element]                  The found element or nil
       #
       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

data/lib/capybara/node/matchers.rb

@@ -13,7 +13,7 @@ module Capybara
       # By default it will check if the expression occurs at least once,
       # but a different number can be specified.
       #
-      #     page.has_selector?('p#foo', :count => 4)
+      #     page.has_selector?('p.foo', :count => 4)
       #
       # This will check if the expression occurs exactly 4 times.
       #
@@ -28,8 +28,12 @@ module Capybara
       #     page.has_selector?(:xpath, XPath.descendant(:p))
       #
       # @param (see Capybara::Node::Finders#all)
-      # @option options [Integer] :count (nil)    Number of times the expression should occur
-      # @return [Boolean]                         If the expression exists
+      # @param args
+      # @option args [Integer] :count (nil)     Number of times the text should occur
+      # @option args [Integer] :minimum (nil)   Minimum number of times the text should occur
+      # @option args [Integer] :maximum (nil)   Maximum number of times the text should occur
+      # @option args [Range]   :between (nil)   Range of times that should contain number of times text occurs
+      # @return [Boolean]                       If the expression exists
       #
       def has_selector?(*args)
         assert_selector(*args)
@@ -71,7 +75,7 @@ module Capybara
       #
       #     page.assert_selector('li', :text => 'Horse', :visible => true)
       #
-      # {assert_selector} can also accept XPath expressions generated by the
+      # `assert_selector` can also accept XPath expressions generated by the
       # XPath gem:
       #
       #     page.assert_selector(:xpath, XPath.descendant(:p))
@@ -193,17 +197,26 @@ module Capybara
       # Checks if the page or current node has the given text content,
       # ignoring any HTML tags and normalizing whitespace.
       #
-      # This only matches displayable text and specifically excludes text
-      # contained within non-display nodes such as script or head tags.
+      # By default it will check if the text occurs at least once,
+      # but a different number can be specified.
+      #
+      #     page.has_text?('lorem ipsum', between: 2..4)
+      #
+      # This will check if the text occurs from 2 to 4 times.
       #
-      # @param [String] content       The text to check for
-      # @return [Boolean]             Whether it exists
+      # @overload has_text?([type], text, [options])
+      #   @param [:all, :visible] type               Whether to check for only visible or all text
+      #   @param [String, Regexp] text               The text/regexp to check for
+      #   @param [Hash] options                      additional options
+      #   @option options [Integer] :count (nil)     Number of times the text should occur
+      #   @option options [Integer] :minimum (nil)   Minimum number of times the text should occur
+      #   @option options [Integer] :maximum (nil)   Maximum number of times the text should occur
+      #   @option options [Range]   :between (nil)   Range of times that should contain number of times text occurs
+      #   @return [Boolean]                          Whether it exists
       #
-      def has_text?(content)
+      def has_text?(*args)
         synchronize do
-          unless Capybara::Helpers.normalize_whitespace(text).match(Capybara::Helpers.to_regexp(content))
-            raise ExpectationNotMet
-          end
+          raise ExpectationNotMet unless text_found?(*args)
         end
         return true
       rescue Capybara::ExpectationNotMet
@@ -216,17 +229,12 @@ module Capybara
       # Checks if the page or current node does not have the given text
       # content, ignoring any HTML tags and normalizing whitespace.
       #
-      # This only matches displayable text and specifically excludes text
-      # contained within non-display nodes such as script or head tags.
+      # @param             (see #has_text?)
+      # @return [Boolean]  Whether it doesn't exist
       #
-      # @param [String] content       The text to check for
-      # @return [Boolean]             Whether it doesn't exist
-      #
-      def has_no_text?(content)
+      def has_no_text?(*args)
         synchronize do
-          if Capybara::Helpers.normalize_whitespace(text).match(Capybara::Helpers.to_regexp(content))
-            raise ExpectationNotMet
-          end
+          raise ExpectationNotMet if text_found?(*args)
         end
         return true
       rescue Capybara::ExpectationNotMet
@@ -299,6 +307,8 @@ module Capybara
       #
       #     page.has_field?('Email', :type => 'email')
       #
+      # Note: 'textarea' and 'select' are valid type values, matching the associated tag names.
+      #
       # @param [String] locator           The label, name or id of a field to check for
       # @option options [String] :with    The text content of the field
       # @option options [String] :type    The type attribute of the field
@@ -450,6 +460,13 @@ module Capybara
 
     private
 
+      def text_found?(*args)
+        type = args.shift if args.first.is_a?(Symbol) or args.first.nil?
+        content, options = args
+        count = Capybara::Helpers.normalize_whitespace(text(type)).scan(Capybara::Helpers.to_regexp(content)).count
+
+        Capybara::Helpers.matches_count?(count, options || {})
+      end
     end
   end
 end

data/lib/capybara/node/simple.rb

@@ -26,7 +26,7 @@ module Capybara
       #
       # @return [String]    The text of the element
       #
-      def text
+      def text(type=nil)
         native.text
       end
 
@@ -36,8 +36,8 @@ module Capybara
       #
       #     element[:title] # => HTML title attribute
       #
-      # @param  [Symbol] attribute     The attribute to retrieve
-      # @return [String]               The value of the attribute
+      # @param  [Symbol] name  The attribute name to retrieve
+      # @return [String]       The value of the attribute
       #
       def [](name)
         attr_name = name.to_s
@@ -108,6 +108,15 @@ module Capybara
         native[:checked]
       end
 
+      ##
+      #
+      # Whether or not the element is disabled.
+      #
+      # @return [Boolean]     Whether the element is disabled
+      def disabled?
+        native[:disabled]
+      end
+
       ##
       #
       # Whether or not the element is selected.
@@ -118,7 +127,7 @@ module Capybara
         native[:selected]
       end
 
-      def synchronize
+      def synchronize(seconds=nil)
         yield # simple nodes don't need to wait
       end
 
@@ -126,13 +135,26 @@ module Capybara
         # no op
       end
 
-      def unsynchronized
-        yield # simple nodes don't need to wait
+      def title
+        native.xpath("//title").first.text
       end
 
-      def all(*args)
-        query = Capybara::Query.new(*args)
-        elements = native.xpath(query.xpath).map do |node|
+      def has_title?(content)
+        title.match(Capybara::Helpers.to_regexp(content))
+      end
+
+      def has_no_title?(content)
+        not has_title?(content)
+      end
+
+    private
+
+      def resolve_query(query, exact=nil)
+        elements = if query.selector.format == :css
+          native.css(query.css)
+        else
+          native.xpath(query.xpath(exact))
+        end.map do |node|
           self.class.new(node)
         end
         Capybara::Result.new(elements, query)