lib/capybara/node.rb in capybara-0.3.9 vs lib/capybara/node.rb in capybara-0.4.0.rc

@@ -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
 
-    attr_reader :driver, :node
+    include Capybara::Node::Finders
+    include Capybara::Node::Actions
+    include Capybara::Node::Matchers
 
-    def initialize(driver, node)
-      @driver = driver
-      @node = node
+    def initialize(session, base)
+      @session = session
+      @base = base
     end
 
+  protected
+
+    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
+
+    ##
+    #
+    # @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
+      base.click
     end
 
-    def drag_to(element)
-      raise NotImplementedError
-    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