capybara 0.4.0 → 0.4.1.rc

data/lib/capybara/driver/selenium_driver.rb

@@ -43,7 +43,7 @@ class Capybara::Driver::Selenium < Capybara::Driver::Base
       if select_node['multiple'] != 'multiple' and select_node['multiple'] != 'true'
         raise Capybara::UnselectNotAllowed, "Cannot unselect option from single select box."
       end
-      native.clear
+      native.toggle if selected?
     end
 
     def click
@@ -59,9 +59,17 @@ class Capybara::Driver::Selenium < Capybara::Driver::Base
     end
 
     def visible?
-      native.displayed? and native.displayed? != "false"
+      displayed = native.displayed?
+      displayed and displayed != "false"
     end
 
+    def selected?
+      selected = native.selected?
+      selected and selected != "false"
+    end
+
+    alias :checked? :selected?
+
     def find(locator)
       native.find_elements(:xpath, locator).map { |n| self.class.new(driver, n) }
     end
@@ -83,7 +91,7 @@ class Capybara::Driver::Selenium < Capybara::Driver::Base
 
   def browser
     unless @browser
-      @browser = Selenium::WebDriver.for(options.delete(:browser) || :firefox, options)
+      @browser = Selenium::WebDriver.for(options[:browser] || :firefox, options)
       at_exit do
         @browser.quit
       end

data/lib/capybara/dsl.rb

@@ -39,6 +39,17 @@ module Capybara
       @current_driver = nil
     end
 
+    ##
+    #
+    # Yield a block using a specific driver
+    #
+    def using_driver(driver)
+      Capybara.current_driver = driver
+      yield
+    ensure
+      Capybara.use_default_driver
+    end
+
     ##
     #
     # The current Capybara::Session base on what is set as Capybara.app and Capybara.current_driver

data/lib/capybara/node/actions.rb

@@ -1,5 +1,5 @@
 module Capybara
-  class Node
+  module Node
     module Actions
 
       ##
@@ -13,6 +13,7 @@ module Capybara
         msg = "no link or button '#{locator}' found"
         find(:xpath, XPath::HTML.link_or_button(locator), :message => msg).click
       end
+      alias_method :click_on, :click_link_or_button
 
       ##
       #
@@ -101,9 +102,10 @@ module Capybara
       # box is a multiple select, +select+ can be called multiple times to select more than
       # one option. The select box can be found via its name, id or label text.
       #
-      #     page.uncheck('German')
+      #     page.select 'March', :from => 'Month'
       #
       # @param [String] locator           Which check box to uncheck
+      # @param [Hash{:from => String}]    The id, name or label of the select box
       #
       def select(value, options={})
         if options.has_key?(:from)
@@ -153,18 +155,6 @@ module Capybara
         msg = "cannot attach file, no file field with id, name, or label '#{locator}' found"
         find(:xpath, XPath::HTML.file_field(locator), :message => msg).set(path)
       end
-
-      ##
-      #
-      # Drag one element to another
-      #
-      # @deprecated    Use Capybara::Element#drag_to instead.
-      #
-      def drag(source_locator, target_locator)
-        source = find(:xpath, source_locator, :message => "drag source '#{source_locator}' not found on page")
-        target = find(:xpath, target_locator, :message => "drag target '#{target_locator}' not found on page")
-        source.drag_to(target)
-      end
     end
   end
 end

data/lib/capybara/node/base.rb

@@ -0,0 +1,47 @@
+module Capybara
+  module Node
+
+    ##
+    #
+    # A {Capybara::Node::Base} represents either an element on a page through the subclass
+    # {Capybara::Node::Element} or a document through {Capybara::Node::Document}.
+    #
+    # Both types of Node share the same methods, used for interacting with the
+    # elements on the page. These methods are divided into three categories,
+    # finders, actions and matchers. These are found in the modules
+    # {Capybara::Node::Finders}, {Capybara::Node::Actions} and {Capybara::Node::Matchers}
+    # respectively.
+    #
+    # A {Capybara::Session} exposes all methods from {Capybara::Node::Document} directly:
+    #
+    #     session = Capybara::Session.new(:rack_test, my_app)
+    #     session.visit('/')
+    #     session.fill_in('Foo', :with => 'Bar')    # from Capybara::Node::Actions
+    #     bar = session.find('#bar')                # from Capybara::Node::Finders
+    #     bar.select('Baz', :from => 'Quox')        # from Capybara::Node::Actions
+    #     session.has_css?('#foobar')               # from Capybara::Node::Matchers
+    #
+    class Base
+      attr_reader :session, :base
+
+      include Capybara::Node::Finders
+      include Capybara::Node::Actions
+      include Capybara::Node::Matchers
+
+      def initialize(session, base)
+        @session = session
+        @base = base
+      end
+
+    protected
+
+      def wait?
+        driver.wait?
+      end
+
+      def driver
+        session.driver
+      end
+    end
+  end
+end

data/lib/capybara/node/document.rb

@@ -0,0 +1,17 @@
+module Capybara
+  module Node
+
+    ##
+    #
+    # A {Capybara::Document} represents an HTML document. Any operation
+    # performed on it will be performed on the entire document.
+    #
+    # @see Capybara::Node
+    #
+    class Document < Base
+      def inspect
+        %(#<Capybara::Document>)
+      end
+    end
+  end
+end

data/lib/capybara/node/element.rb

@@ -0,0 +1,178 @@
+module Capybara
+  module Node
+
+    ##
+    #
+    # A {Capybara::Element} represents a single element on the page. It is possible
+    # to interact with the contents of this element the same as with a document:
+    #
+    #     session = Capybara::Session.new(:rack_test, my_app)
+    #
+    #     bar = session.find('#bar')              # from Capybara::Node::Finders
+    #     bar.select('Baz', :from => 'Quox')      # from Capybara::Node::Actions
+    #
+    # {Capybara::Element} also has access to HTML attributes and other properties of the
+    # element:
+    #
+    #      bar.value
+    #      bar.text
+    #      bar[:title]
+    #
+    # @see Capybara::Node
+    #
+    class Element < Base
+
+      ##
+      #
+      # @return [Object]    The native element from the driver, this allows access to driver specific methods
+      #
+      def native
+        base.native
+      end
+
+      ##
+      #
+      # @return [String]    The text of the element
+      #
+      def text
+        base.text
+      end
+
+      ##
+      #
+      # Retrieve the given attribute
+      #
+      #     element[:title] # => HTML title attribute
+      #
+      # @param  [Symbol] attribute     The attribute to retrieve
+      # @return [String]               The value of the attribute
+      #
+      def [](attribute)
+        base[attribute]
+      end
+
+      ##
+      #
+      # @return [String]    The value of the form element
+      #
+      def value
+        base.value
+      end
+
+      ##
+      #
+      # Set the value of the form element to the given value.
+      #
+      # @param [String] value    The new value
+      #
+      def set(value)
+        base.set(value)
+      end
+
+      ##
+      #
+      # Select this node if is an option element inside a select tag
+      #
+      def select_option
+        base.select_option
+      end
+
+      ##
+      #
+      # Unselect this node if is an option element inside a multiple select tag
+      #
+      def unselect_option
+        base.unselect_option
+      end
+
+      ##
+      #
+      # Click the Element
+      #
+      def click
+        base.click
+      end
+
+      ##
+      #
+      # @return [String]      The tag name of the element
+      #
+      def tag_name
+        base.tag_name
+      end
+
+      ##
+      #
+      # Whether or not the element is visible. Not all drivers support CSS, so
+      # the result may be inaccurate.
+      #
+      # @return [Boolean]     Whether the element is visible
+      #
+      def visible?
+        base.visible?
+      end
+
+      ##
+      #
+      # Whether or not the element is checked.
+      #
+      # @return [Boolean]     Whether the element is checked
+      #
+      def checked?
+        base.checked?
+      end
+
+      ##
+      #
+      # Whether or not the element is selected.
+      #
+      # @return [Boolean]     Whether the element is selected
+      #
+      def selected?
+        base.selected?
+      end
+
+      ##
+      #
+      # An XPath expression describing where on the page the element can be found
+      #
+      # @return [String]      An XPath expression
+      #
+      def path
+        base.path
+      end
+
+      ##
+      #
+      # Trigger any event on the current element, for example mouseover or focus
+      # events. Does not work in Selenium.
+      #
+      # @param [String] event       The name of the event to trigger
+      #
+      def trigger(event)
+        base.trigger(event)
+      end
+
+      ##
+      #
+      # Drag the element to the given other element.
+      #
+      #     source = page.find('#foo')
+      #     target = page.find('#bar')
+      #     source.drag_to(target)
+      #
+      # @param [Capybara::Element] node     The element to drag to
+      #
+      def drag_to(node)
+        base.drag_to(node.base)
+      end
+
+      def inspect
+        %(#<Capybara::Element tag="#{tag_name}" path="#{path}">)
+      rescue NotSupportedByDriverError
+        %(#<Capybara::Element tag="#{tag_name}">)
+      end
+
+    end
+  end
+end

data/lib/capybara/node/finders.rb

@@ -1,5 +1,5 @@
 module Capybara
-  class Node
+  module Node
     module Finders
 
       ##
@@ -24,22 +24,17 @@ module Capybara
       # @raise  [Capybara::ElementNotFound]   If the element can't be found before time expires
       #
       def find(*args)
-        node = wait_conditionally_until { all(*args).first }
-      ensure
-        options = if args.last.is_a?(Hash) then args.last else {} end
-        raise Capybara::ElementNotFound, options[:message] || "Unable to find '#{args[1] || args[0]}'" unless node
+        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
 
-      ##
-      #
-      # @deprecated {#find} now behaves like locate used to. Use {#find} instead.
-      #
-      def locate(*args)
-        Capybara.deprecate("locate", "find")
-        find(*args)
-      end
-
       ##
       #
       # Find a form field on the page. The field can be found by its name, id or label text.
@@ -120,31 +115,87 @@ module Capybara
       # @return [Capybara::Element]                       The found elements
       #
       def all(*args)
-        options = if args.last.is_a?(Hash) then args.pop else {} end
+        options = extract_normalized_options(args)
 
-        results = Capybara::Selector.normalize(*args).map do |path|
-          base.find(path)
-        end.flatten
-
-        if text = options[:text]
-          text = Regexp.escape(text) unless text.kind_of?(Regexp)
+        Capybara::Selector.normalize(*args).
+          map    { |path| find_in_base(path) }.flatten.
+          select { |node| matches_options(node, options) }.
+          map    { |node| convert_element(node) }
+      end
 
-          results = results.select { |node| node.text.match(text) }
-        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)
 
-        if options[:visible] or Capybara.ignore_hidden_elements
-          results = results.select { |node| node.visible? }
+        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
 
-        results.map { |n| Capybara::Element.new(session, n) }
+        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 driver.wait? then session.wait_until { yield } else yield end
+        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