capybara 0.3.9 → 0.4.0.rc

data/lib/capybara/driver/selenium_driver.rb

@@ -1,16 +1,16 @@
 require 'selenium-webdriver'
 
 class Capybara::Driver::Selenium < Capybara::Driver::Base
-  class Node < Capybara::Node
+  class Node < Capybara::Driver::Node
     def text
-      node.text
+      native.text
     end
 
     def [](name)
       if name == :value
-        node.value
+        native.value
       else
-        node.attribute(name.to_s)
+        native.attribute(name.to_s)
       end
     rescue Selenium::WebDriver::Error::WebDriverError
       nil
@@ -18,65 +18,59 @@ class Capybara::Driver::Selenium < Capybara::Driver::Base
 
     def value
       if tag_name == "select" and self[:multiple]
-        node.find_elements(:xpath, ".//option").select { |n| n.selected? }.map { |n| n.text }
+        native.find_elements(:xpath, ".//option").select { |n| n.selected? }.map { |n| n.value || n.text }
       else
-        super
+        self[:value]
       end
     end
 
     def set(value)
       if tag_name == 'input' and type == 'radio'
-        node.click
+        native.click
       elsif tag_name == 'input' and type == 'checkbox'
-        node.click if node.attribute('checked') != value
+        native.click if value ^ native.attribute('checked').to_s.eql?("true")
       elsif tag_name == 'textarea' or tag_name == 'input'
-        node.clear
-        node.send_keys(value.to_s)
+        native.clear
+        native.send_keys(value.to_s)
       end
     end
 
-    def select(option)
-      option_node = node.find_element(:xpath, ".//option[normalize-space(text())=#{Capybara::XPath.escape(option)}]") || node.find_element(:xpath, ".//option[contains(.,#{Capybara::XPath.escape(option)})]")
-      option_node.select
-    rescue 
-      options = node.find_elements(:xpath, "//option").map { |o| "'#{o.text}'" }.join(', ')
-      raise Capybara::OptionNotFound, "No such option '#{option}' in this select box. Available options: #{options}"
+    def select_option
+      native.select
     end
 
-    def unselect(option)
-      if node['multiple'] != 'multiple'
-        raise Capybara::UnselectNotAllowed, "Cannot unselect option '#{option}' from single select box."
-      end
-
-      begin
-        option_node = node.find_element(:xpath, ".//option[normalize-space(text())=#{Capybara::XPath.escape(option)}]") || node.find_element(:xpath, ".//option[contains(.,#{Capybara::XPath.escape(option)})]")
-        option_node.clear
-      rescue
-        options = node.find_elements(:xpath, "//option").map { |o| "'#{o.text}'" }.join(', ')
-        raise Capybara::OptionNotFound, "No such option '#{option}' in this select box. Available options: #{options}"
+    def unselect_option
+      if select_node['multiple'] != 'multiple' and select_node['multiple'] != 'true'
+        raise Capybara::UnselectNotAllowed, "Cannot unselect option from single select box."
       end
+      native.clear
     end
 
     def click
-      node.click
+      native.click
     end
 
     def drag_to(element)
-      node.drag_and_drop_on(element.node)
+      native.drag_and_drop_on(element.native)
     end
 
     def tag_name
-      node.tag_name
+      native.tag_name
     end
 
     def visible?
-      node.displayed? and node.displayed? != "false"
+      native.displayed? and native.displayed? != "false"
+    end
+
+    def find(locator)
+      native.find_elements(:xpath, locator).map { |n| self.class.new(driver, n) }
     end
-    
+
   private
 
-    def all_unfiltered(locator)
-      node.find_elements(:xpath, locator).map { |n| self.class.new(driver, n) }
+    # a reference to the select node if this is an option node
+    def select_node
+      find('./ancestor::select').first
     end
 
     def type
@@ -85,20 +79,21 @@ class Capybara::Driver::Selenium < Capybara::Driver::Base
 
   end
 
-  attr_reader :app, :rack_server
+  attr_reader :app, :rack_server, :options
 
-  def self.driver
-    unless @driver
-      @driver = Selenium::WebDriver.for :firefox
+  def browser
+    unless @browser
+      @browser = Selenium::WebDriver.for(options.delete(:browser) || :firefox, options)
       at_exit do
-        @driver.quit
+        @browser.quit
       end
     end
-    @driver
+    @browser
   end
 
-  def initialize(app)
+  def initialize(app, options={})
     @app = app
+    @options = options
     @rack_server = Capybara::Server.new(@app)
     @rack_server.boot if Capybara.run_server
   end
@@ -133,12 +128,9 @@ class Capybara::Driver::Selenium < Capybara::Driver::Base
     browser.execute_script "return #{script}"
   end
 
-  def browser
-    self.class.driver
-  end
-
-  def cleanup!
-    browser.manage.delete_all_cookies
+  def reset!
+    # Use instance variable directly so we avoid starting the browser just to reset the session
+    @browser.manage.delete_all_cookies if @browser
   end
 
   def within_frame(frame_id)
@@ -148,6 +140,10 @@ class Capybara::Driver::Selenium < Capybara::Driver::Base
     browser.switch_to.window old_window
   end
 
+  def within_window(handle, &blk)
+    browser.switch_to.window(handle, &blk)
+  end
+
 private
 
   def url(path)

data/lib/capybara/dsl.rb

@@ -6,35 +6,58 @@ module Capybara
 
     attr_accessor :app
 
+    ##
+    #
+    # @return [Symbol]    The name of the driver to use by default
+    #
     def default_driver
       @default_driver || :rack_test
     end
 
+    ##
+    #
+    # @return [Symbol]    The name of the driver currently in use
+    #
     def current_driver
       @current_driver || default_driver
     end
     alias_method :mode, :current_driver
 
+    ##
+    #
+    # @return [Symbol]    The name of the driver used when JavaScript is needed
+    #
     def javascript_driver
       @javascript_driver || :selenium
     end
 
+    ##
+    #
+    # Use the default driver as the current driver
+    #
     def use_default_driver
       @current_driver = nil
     end
 
+    ##
+    #
+    # The current Capybara::Session base on what is set as Capybara.app and Capybara.current_driver
+    #
+    # @return [Capybara::Session]     The currently used session
+    #
     def current_session
       session_pool["#{current_driver}#{app.object_id}"] ||= Capybara::Session.new(current_driver, app)
     end
 
-    def current_session?
-      session_pool.has_key?("#{current_driver}#{app.object_id}")
-    end
-
+    ##
+    #
+    # Reset sessions, cleaning out the pool of sessions. This will remove any session information such
+    # as cookies.
+    #
     def reset_sessions!
-      session_pool.each { |mode, session| session.cleanup! }
-      @session_pool = nil
+      session_pool.each { |mode, session| session.reset! }
     end
+    alias_method :reset!, :reset_sessions!
 
   private
 
@@ -45,6 +68,21 @@ module Capybara
 
   extend(self)
 
+  ##
+  #
+  # Shortcut to accessing the current session. This is useful when Capybara is included in a
+  # class or module.
+  #
+  #     class MyClass
+  #       include Capybara
+  #
+  #       def has_header?
+  #         page.has_css?('h1')
+  #       end
+  #     end
+  #
+  # @return [Capybara::Session] The current session object
+  #
   def page
     Capybara.current_session
   end

data/lib/capybara/node.rb

@@ -1,60 +1,221 @@
+require 'capybara/node/finders'
+require 'capybara/node/actions'
+require 'capybara/node/matchers'
+
 module Capybara
+
+  ##
+  #
+  # A {Capybara::Node} represents either an element on a page through the subclass
+  # {Capybara::Element} or a document through {Capybara::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::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 Node
-    include Searchable
+    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
 
-    attr_reader :driver, :node
+    def driver
+      session.driver
+    end
+  end
+
+  ##
+  #
+  # 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 < Node
+
+    ##
+    #
+    # @return [Object]    The native element from the driver, this allows access to driver specific methods
+    #
+    def native
+      base.native
+    end
 
-    def initialize(driver, node)
-      @driver = driver
-      @node = node
+    ##
+    #
+    # @deprecated node is deprecated, please use {Capybara::Element#native} instead
+    #
+    def node
+      Capybara.deprecate("node", "native")
+      native
     end
 
+    ##
+    #
+    # @return [String]    The text of the element
+    #
     def text
-      raise NotImplementedError
+      base.text
     end
 
-    def [](name)
-      raise NotImplementedError
+    ##
+    #
+    # 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
-      self[:value]
+      base.value
     end
 
+    ##
+    #
+    # Set the value of the form element to the given value.
+    #
+    # @param [String] value    The new value
+    #
     def set(value)
-      raise NotImplementedError
+      base.set(value)
     end
 
-    def select(option)
-      raise NotImplementedError
+    ##
+    #
+    # Select this node if is an option element inside a select tag
+    #
+    def select_option
+      base.select_option
     end
 
-    def unselect(option)
-      raise NotImplementedError
+    ##
+    #
+    # 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
-      raise NotImplementedError
-    end
-
-    def drag_to(element)
-      raise NotImplementedError
+      base.click
     end
 
+    ##
+    #
+    # @return [String]      The tag name of the element
+    #
     def tag_name
-      raise NotImplementedError
+      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?
-      raise NotImplementedError
+      base.visible?
     end
 
+    ##
+    #
+    # An XPath expression describing where on the page the element can be found
+    #
+    # @return [String]      An XPath expression
+    #
     def path
-      raise NotSupportedByDriverError
+      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)
-      raise NotSupportedByDriverError
+      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
+
+  ##
+  #
+  # A {Capybara::Document} represents an HTML document. Any operation
+  # performed on it will be performed on the entire document.
+  #
+  # @see Capybara::Node
+  #
+  class Document < Node
+    def inspect
+      %(#<Capybara::Document>)
     end
   end
 end