rcarvalho-capybara 0.4.1.1

data/lib/capybara/node/finders.rb

@@ -0,0 +1,201 @@
+module Capybara
+  module Node
+    module Finders
+
+      ##
+      #
+      # Find an {Capybara::Element} based on the given arguments. +find+ will raise an error if the element
+      # is not found. The error message can be customized through the +:message+ option.
+      #
+      # If the driver is capable of executing JavaScript, +find+ will wait for a set amount of time
+      # and continuously retry finding the element until either the element is found or the time
+      # expires. The length of time +find+ will wait is controlled through {Capybara.default_wait_time}
+      # and defaults to 2 seconds.
+      #
+      # +find+ takes the same options as +all+.
+      #
+      #     page.find('#foo').find('.bar')
+      #     page.find(:xpath, '//div[contains("bar")]')
+      #     page.find('li', :text => 'Quox').click_link('Delete')
+      #
+      # @param (see Capybara::Node::Finders#all)
+      # @option options [String] :message     An error message in case the element can't be found
+      # @return [Capybara::Element]           The found element
+      # @raise  [Capybara::ElementNotFound]   If the element can't be found before time expires
+      #
+      def find(*args)
+        begin
+          node = wait_conditionally_until { first(*args) }
+        rescue TimeoutError
+        end
+        unless node
+          options = if args.last.is_a?(Hash) then args.last else {} end
+          raise Capybara::ElementNotFound, options[:message] || "Unable to find '#{args[1] || args[0]}'"
+        end
+        return node
+      end
+
+      ##
+      #
+      # Find a form field on the page. The field can be found by its name, id or label text.
+      #
+      # @param [String] locator       Which field to find
+      # @return [Capybara::Element]   The found element
+      #
+      def find_field(locator)
+        find(:xpath, XPath::HTML.field(locator))
+      end
+      alias_method :field_labeled, :find_field
+
+      ##
+      #
+      # Find a link on the page. The link can be found by its id or text.
+      #
+      # @param [String] locator       Which link to find
+      # @return [Capybara::Element]   The found element
+      #
+      def find_link(locator)
+        find(:xpath, XPath::HTML.link(locator))
+      end
+
+      ##
+      #
+      # Find a button on the page. The link can be found by its id, name or value.
+      #
+      # @param [String] locator       Which button to find
+      # @return [Capybara::Element]   The found element
+      #
+      def find_button(locator)
+        find(:xpath, XPath::HTML.button(locator))
+      end
+
+      ##
+      #
+      # Find a element on the page, given its id.
+      #
+      # @param [String] locator       Which element to find
+      # @return [Capybara::Element]   The found element
+      #
+      def find_by_id(id)
+        find(:css, "##{id}")
+      end
+
+      ##
+      #
+      # Find all elements on the page matching the given selector
+      # and options.
+      #
+      # Both XPath and CSS expressions are supported, but Capybara
+      # does not try to automatically distinguish between them. The
+      # following statements are equivalent:
+      #
+      #     page.all(:css, 'a#person_123')
+      #     page.all(:xpath, '//a[@id="person_123"]')
+      #
+      #
+      # If the type of selector is left out, Capybara uses
+      # {Capybara.default_selector}. It's set to :css by default.
+      #
+      #     page.all("a#person_123")
+      #
+      #     Capybara.default_selector = :xpath
+      #     page.all('//a[@id="person_123"]')
+      #
+      # The set of found elements can further be restricted by specifying
+      # options. It's possible to select elements by their text or visibility:
+      #
+      #     page.all('a', :text => 'Home')
+      #     page.all('#menu li', :visible => true)
+      #
+      # @param [:css, :xpath, String] kind_or_locator     Either the kind of selector or the selector itself
+      # @param [String] locator                           The selector
+      # @param [Hash{Symbol => Object}] options           Additional options
+      # @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
+      # @return [Capybara::Element]                       The found elements
+      #
+      def all(*args)
+        options = extract_normalized_options(args)
+
+        Capybara::Selector.normalize(*args).
+          map    { |path| find_in_base(path) }.flatten.
+          select { |node| matches_options(node, options) }.
+          map    { |node| convert_element(node) }
+      end
+
+      ##
+      #
+      # Find the first element on the page matching the given selector
+      # and options, or nil if no element matches.
+      #
+      # When only the first matching element is needed, this method can
+      # be faster than all(*args).first.
+      #
+      # @param [:css, :xpath, String] kind_or_locator     Either the kind of selector or the selector itself
+      # @param [String] locator                           The selector
+      # @param [Hash{Symbol => Object}] options           Additional options; see {all}
+      # @return Capybara::Element                         The found element
+      #
+      def first(*args)
+        options = extract_normalized_options(args)
+
+        Capybara::Selector.normalize(*args).each do |path|
+          find_in_base(path).each do |node|
+            if matches_options(node, options)
+              return convert_element(node)
+            end
+          end
+        end
+
+        nil
+      end
+
+    protected
+
+      def find_in_base(xpath)
+        base.find(xpath)
+      end
+
+      def convert_element(element)
+        Capybara::Node::Element.new(session, element)
+      end
+
+      def wait_conditionally_until
+        if wait? then session.wait_until { yield } else yield end
+      end
+
+      def extract_normalized_options(args)
+        options = if args.last.is_a?(Hash) then args.pop.dup else {} end
+
+        if text = options[:text]
+          options[:text] = Regexp.escape(text) unless text.kind_of?(Regexp)
+        end
+
+        if !options.has_key?(:visible)
+          options[:visible] = Capybara.ignore_hidden_elements
+        end
+
+        if selected = options[:selected]
+          options[:selected] = [selected].flatten
+        end
+
+        options
+      end
+
+      def matches_options(node, options)
+        return false if options[:text]      and not node.text.match(options[:text])
+        return false if options[:visible]   and not node.visible?
+        return false if options[:with]      and not node.value == options[:with]
+        return false if options[:checked]   and not node.checked?
+        return false if options[:unchecked] and node.checked?
+        return false if options[:selected]  and not has_selected_options?(node, options[:selected])
+        true
+      end
+
+      def has_selected_options?(node, expected)
+        actual = node.find('.//option').select { |option| option.selected? }.map { |option| option.text }
+        (expected - actual).empty?
+      end
+    end
+  end
+end

data/lib/capybara/node/matchers.rb

@@ -0,0 +1,391 @@
+module Capybara
+  module Node
+    module Matchers
+
+      ##
+      #
+      # Checks if a given selector is on the page or current node.
+      #
+      #     page.has_selector?('p#foo')
+      #     page.has_selector?(:xpath, './/p[@id="foo"]')
+      #     page.has_selector?(:foo)
+      #
+      # 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)
+      #
+      # This will check if the expression occurs exactly 4 times.
+      #
+      # It also accepts all options that {Capybara::Node::Finders#all} accepts,
+      # such as :text and :visible.
+      #
+      #     page.has_selector?('li', :text => 'Horse', :visible => true)
+      #
+      # has_selector? can also accept XPath expressions generated by the
+      # XPath gem:
+      #
+      #     xpath = XPath.generate { |x| x.descendant(:p) }
+      #     page.has_selector?(:xpath, xpath)
+      #
+      # @param (see Capybara::Node::Finders#all)
+      # @option options [Integer] :count (nil)    Number of times the expression should occur
+      # @return [Boolean]                         If the expression exists
+      #
+      def has_selector?(*args)
+        options = if args.last.is_a?(Hash) then args.last else {} end
+        wait_conditionally_until do
+          results = all(*args)
+
+          case
+          when results.empty?
+            false
+          when options[:between]
+            options[:between] === results.size
+          when options[:count]
+            options[:count] == results.size
+          when options[:maximum]
+            options[:maximum] >= results.size
+          when options[:minimum]
+            options[:minimum] <= results.size
+          else
+            results.size > 0
+          end
+        end
+      rescue Capybara::TimeoutError
+        return false
+      end
+
+      ##
+      #
+      # Checks if a given selector is not on the page or current node.
+      # Usage is identical to Capybara::Node::Matchers#has_selector?
+      #
+      # @param (see Capybara::Node::Finders#has_selector?)
+      # @return [Boolean]
+      #
+      def has_no_selector?(*args)
+        options = if args.last.is_a?(Hash) then args.last else {} end
+        wait_conditionally_until do
+          results = all(*args)
+
+          case
+          when results.empty?
+            true
+          when options[:between]
+            not(options[:between] === results.size)
+          when options[:count]
+            not(options[:count] == results.size)
+          when options[:maximum]
+            not(options[:maximum] >= results.size)
+          when options[:minimum]
+            not(options[:minimum] <= results.size)
+          else
+            results.empty?
+          end
+        end
+      rescue Capybara::TimeoutError
+        return false
+      end
+
+      ##
+      #
+      # Checks if a given XPath expression is on the page or current node.
+      #
+      #     page.has_xpath?('.//p[@id="foo"]')
+      #
+      # By default it will check if the expression occurs at least once,
+      # but a different number can be specified.
+      #
+      #     page.has_xpath?('.//p[@id="foo"]', :count => 4)
+      #
+      # This will check if the expression occurs exactly 4 times.
+      #
+      # It also accepts all options that {Capybara::Node::Finders#all} accepts,
+      # such as :text and :visible.
+      #
+      #     page.has_xpath?('.//li', :text => 'Horse', :visible => true)
+      #
+      # has_xpath? can also accept XPath expressions generate by the
+      # XPath gem:
+      #
+      #     xpath = XPath.generate { |x| x.descendant(:p) }
+      #     page.has_xpath?(xpath)
+      #
+      # @param [String] path                      An XPath expression
+      # @param options                            (see Capybara::Node::Finders#all)
+      # @option options [Integer] :count (nil)    Number of times the expression should occur
+      # @return [Boolean]                         If the expression exists
+      #
+      def has_xpath?(path, options={})
+        has_selector?(:xpath, path, options)
+      end
+
+      ##
+      #
+      # Checks if a given XPath expression is not on the page or current node.
+      # Usage is identical to Capybara::Node::Matchers#has_xpath?
+      #
+      # @param (see Capybara::Node::Finders#has_xpath?)
+      # @return [Boolean]
+      #
+      def has_no_xpath?(path, options={})
+        has_no_selector?(:xpath, path, options)
+      end
+
+      ##
+      #
+      # Checks if a given CSS selector is on the page or current node.
+      #
+      #     page.has_css?('p#foo')
+      #
+      # By default it will check if the selector occurs at least once,
+      # but a different number can be specified.
+      #
+      #     page.has_css?('p#foo', :count => 4)
+      #
+      # This will check if the selector occurs exactly 4 times.
+      #
+      # It also accepts all options that {Capybara::Node::Finders#all} accepts,
+      # such as :text and :visible.
+      #
+      #     page.has_css?('li', :text => 'Horse', :visible => true)
+      #
+      # @param [String] path                      A CSS selector
+      # @param options                            (see Capybara::Node::Finders#all)
+      # @option options [Integer] :count (nil)    Number of times the selector should occur
+      # @return [Boolean]                         If the selector exists
+      #
+      def has_css?(path, options={})
+        has_xpath?(XPath.css(path), options)
+      end
+
+      ##
+      #
+      # Checks if a given CSS selector is not on the page or current node.
+      # Usage is identical to Capybara::Node::Matchers#has_css?
+      #
+      # @param (see Capybara::Node::Finders#has_css?)
+      # @return [Boolean]
+      #
+      def has_no_css?(path, options={})
+        has_no_xpath?(XPath.css(path), options)
+      end
+
+      ##
+      #
+      # Checks if the page or current node has the given text content,
+      # ignoring any HTML tags and normalizing whitespace.
+      #
+      # @param [String] content       The text to check for
+      # @return [Boolean]             Whether it exists
+      #
+      def has_content?(content)
+        has_xpath?(XPath::HTML.content(content))
+      end
+
+      ##
+      #
+      # Checks if the page or current node does not have the given text
+      # content, ignoring any HTML tags and normalizing whitespace.
+      #
+      # @param [String] content       The text to check for
+      # @return [Boolean]             Whether it exists
+      #
+      def has_no_content?(content)
+        has_no_xpath?(XPath::HTML.content(content))
+      end
+
+      ##
+      #
+      # Checks if the page or current node has a link with the given
+      # text or id.
+      #
+      # @param [String] locator           The text or id of a link to check for
+      # @param options
+      # @option options [String] :href    The value the href attribute must be
+      # @return [Boolean]                 Whether it exists
+      #
+      def has_link?(locator, options={})
+        has_xpath?(XPath::HTML.link(locator, options))
+      end
+
+      ##
+      #
+      # Checks if the page or current node has no link with the given
+      # text or id.
+      #
+      # @param (see Capybara::Node::Finders#has_link?)
+      # @return [Boolean]            Whether it doesn't exist
+      #
+      def has_no_link?(locator, options={})
+        has_no_xpath?(XPath::HTML.link(locator, options))
+      end
+
+      ##
+      #
+      # Checks if the page or current node has a button with the given
+      # text, value or id.
+      #
+      # @param [String] locator      The text, value or id of a button to check for
+      # @return [Boolean]            Whether it exists
+      #
+      def has_button?(locator)
+        has_xpath?(XPath::HTML.button(locator))
+      end
+
+      ##
+      #
+      # Checks if the page or current node has no button with the given
+      # text, value or id.
+      #
+      # @param [String] locator      The text, value or id of a button to check for
+      # @return [Boolean]            Whether it doesn't exist
+      #
+      def has_no_button?(locator)
+        has_no_xpath?(XPath::HTML.button(locator))
+      end
+
+      ##
+      #
+      # Checks if the page or current node has a form field with the given
+      # label, name or id.
+      #
+      # For text fields and other textual fields, such as textareas and
+      # HTML5 email/url/etc. fields, it's possible to specify a :with
+      # option to specify the text the field should contain:
+      #
+      #     page.has_field?('Name', :with => 'Jonas')
+      #
+      # @param [String] locator           The label, name or id of a field to check for
+      # @option options [String] :with    The text content of the field
+      # @return [Boolean]                 Whether it exists
+      #
+      def has_field?(locator, options={})
+        options, with = split_options(options, :with)
+        has_xpath?(XPath::HTML.field(locator, options), with)
+      end
+
+      ##
+      #
+      # Checks if the page or current node has no form field with the given
+      # label, name or id. See {Capybara::Node::Matchers#has_field?}.
+      #
+      # @param [String] locator           The label, name or id of a field to check for
+      # @option options [String] :with    The text content of the field
+      # @return [Boolean]                 Whether it doesn't exist
+      #
+      def has_no_field?(locator, options={})
+        options, with = split_options(options, :with)
+        has_no_xpath?(XPath::HTML.field(locator, options), with)
+      end
+
+      ##
+      #
+      # Checks if the page or current node has a radio button or
+      # checkbox with the given label, value or id, that is currently
+      # checked.
+      #
+      # @param [String] locator           The label, name or id of a checked field
+      # @return [Boolean]                 Whether it exists
+      #
+      def has_checked_field?(locator)
+        has_xpath?(XPath::HTML.field(locator), :checked => true)
+      end
+
+      ##
+      #
+      # Checks if the page or current node has a radio button or
+      # checkbox with the given label, value or id, that is currently
+      # unchecked.
+      #
+      # @param [String] locator           The label, name or id of an unchecked field
+      # @return [Boolean]                 Whether it exists
+      #
+      def has_unchecked_field?(locator)
+        has_xpath?(XPath::HTML.field(locator), :unchecked => true)
+      end
+
+      ##
+      #
+      # Checks if the page or current node has a select field with the
+      # given label, name or id.
+      #
+      # It can be specified which option should currently be selected:
+      #
+      #     page.has_select?('Language', :selected => 'German')
+      #
+      # For multiple select boxes, several options may be specified:
+      #
+      #     page.has_select?('Language', :selected => ['English', 'German'])
+      #
+      # It's also possible to check if a given set of options exists for
+      # this select box:
+      #
+      #     page.has_select?('Language', :options => ['English', 'German'])
+      #
+      # @param [String] locator                      The label, name or id of a select box
+      # @option options [Array] :options             Options which should be contained in this select box
+      # @option options [String, Array] :selected    Options which should be selected
+      # @return [Boolean]                            Whether it exists
+      #
+      def has_select?(locator, options={})
+        options, selected = split_options(options, :selected)
+        has_xpath?(XPath::HTML.select(locator, options), selected)
+      end
+
+      ##
+      #
+      # Checks if the page or current node has no select field with the
+      # given label, name or id. See {Capybara::Node::Matchers#has_select?}.
+      #
+      # @param (see Capybara::Node::Matchers#has_select?)
+      # @return [Boolean]     Whether it doesn't exist
+      #
+      def has_no_select?(locator, options={})
+        options, selected = split_options(options, :selected)
+        has_no_xpath?(XPath::HTML.select(locator, options), selected)
+      end
+
+      ##
+      #
+      # Checks if the page or current node has a table with the given id
+      # or caption.
+      #
+      # If the options :rows is given, it will check that the table contains
+      # the rows and columns given:
+      #
+      #    page.has_table?('People', :rows => [['Jonas', '24'], ['Peter', '32']])
+      #
+      # Note that this option is quite strict, the order needs to be correct
+      # and the text needs to match exactly.
+      #
+      # @param [String] locator                        The id or caption of a table
+      # @option options [Array[Array[String]]] :rows   A set of rows the table should contain
+      # @return [Boolean]                              Whether it exist
+      #
+      def has_table?(locator, options={})
+        has_xpath?(XPath::HTML.table(locator, options))
+      end
+
+      ##
+      #
+      # Checks if the page or current node has no table with the given id
+      # or caption. See {Capybara::Node::Matchers#has_table?}.
+      #
+      # @param (see Capybara::Node::Matchers#has_table?)
+      # @return [Boolean]       Whether it doesn't exist
+      #
+      def has_no_table?(locator, options={})
+        has_no_xpath?(XPath::HTML.table(locator, options))
+      end
+
+      protected
+
+      def split_options(options, key)
+        options = options.dup
+        [options, if options.has_key?(key) then {key => options.delete(key)} else {} end]
+      end
+    end
+  end
+end