locator 0.0.3 → 0.0.4

data/README.textile

@@ -1,13 +1,184 @@
+<a name="readme"></a>
+
 h1. Locator
 
-This library aims to extract common html element selection from testing tools such as "Webrat":http://github.com/brynary/webrat/blob/master/lib/webrat/core/locators.rb, "Capybara":http://github.com/jnicklas/capybara/blob/master/lib/capybara/xpath.rb or "Steam":http://github.com/svenfuchs/steam/blob/master/lib/steam/locators.rb. At its core it constructs "XPath":http://github.com/svenfuchs/locator/blob/master/lib/locator/xpath.rb objects using a simple "boolean expression engine":http://github.com/svenfuchs/locator/blob/master/lib/locator/boolean.rb in order to locate elements in a Nokogiri DOM. It provides a bunch of "Element classes":http://github.com/svenfuchs/locator/blob/master/lib/locator/element.rb that are targeted at implementing a Webrat-style DSL for convenience.
+This Gem aims to extract common html element selection from testing tools such as "Webrat":http://github.com/brynary/webrat/blob/master/lib/webrat/core/locators.rb, "Capybara":http://github.com/jnicklas/capybara/blob/master/lib/capybara/xpath.rb or "Steam":http://github.com/svenfuchs/steam/blob/master/lib/steam/locators.rb. At its core it constructs "XPath":http://github.com/svenfuchs/locator/blob/master/lib/locator/xpath.rb objects using a simple "boolean expression engine":http://github.com/svenfuchs/locator/blob/master/lib/locator/boolean.rb in order to locate elements in a Nokogiri DOM. It provides a bunch of "Element classes":http://github.com/svenfuchs/locator/blob/master/lib/locator/element.rb that are targeted at implementing a Webrat-style DSL for convenience.
+
+"See below":#why-another-library for why I strongly believe that this behavior should be implemented as a stand-alone library.
 
 h2. Usage
 
-Of course you can use the underlying implementation, too, but there are three main public methods which are supposed to give you access to all you need.
+Of course you can use the underlying implementation, too, but there are three main public methods which are supposed to give you access to all you need:
+
+* @Locator.locate(html, *args)@
+* @Locator.within(*args)@
+* @Locator.xpath(*args)@
+
+The following code examples all assume that you include the Locator module like so:
+
+pre. include Locator
 
-h3. Building an XPath
+All the examples should work without doing so though. You should be able to statically call the same methods on the Locator module instead.
 
 h3. Locating an element
 
-h3. Scoping to an element
+There are three APIs for locating elements:
+
+* using a locator type (e.g. @:link@) and/or required node attributes (e.g. @:id => 'foo'@) and/or a selector (e.g. @"The link"@)
+* using an xpath
+* using a css selector
+
+In all cases you can use the Locator.locate method which wants you to pass the HTML code as the first argument:
+
+pre. locate(html, *args)
+
+h4. Locating elements using a locator type
+
+If you pass a *Symbol* as a first argument, then Locator will interpret this as a *locator type*. For a list of "supported locator types":#locator-types see below, these sometimes but do not always equal HTML tag node names.
+
+E.g. the @:form@ tag will simply locate HTML form tags. Locator types like @:button@, @:field@ and @:link@ bake in some more knowledge about how we want to build a DSL (e.g. a helper locator_button could use the Button locator type and match both HTML button tags and clickable input tags such as submit input tags).
+
+So this will simply return the first link tag on the page:
+
+pre. locate(html, :link)
+
+h4. Locating elements using a selector
+
+You can (alternatively or additionally) specify a *selector*. Selectors will be matched against matchable values depending on the locator type, "see below":#matchable-values for details.
+
+E.g. to find a link that has the text @"Click here!"@ you could use any of the following calls:
+
+<pre>locate(html, :link, "Click here!")
+locate(html, :link, "Click")
+locate(html, :link, "here!")
+locate(html, "Click")</pre>
+
+And so on. Note that Locator will pick the *outermost* element with the *shortest matching value*, see below for details about "matchable values":#matchable-values.
+
+h4. Locating elements using attributes
+
+You can (alternatively or additionally) specify required attributes. E.g. to find a link with the id @"foo"@ you can use:
+
+pre. locate(html, :link, :id => "foo")
+
+You can combine that with a selector. E.g. this will locate a link that has a text "click" and a class "foo":
+
+pre. locate(html, :link, "click", :class => "foo")
+
+All attributes are matched by equality. I.e. when you pass @:id => "foo"@ then only elements are matched that have the exact id attribute "foo". The only *exception* from this is the @:class@ attribute. When you pass @:class => "foo"@ then this is semantically equivalent to saying "an element that has the class 'foo'". 
+
+(Technically the class attribute is matched using an xpath @*[contains(concat(' ', @class, ' '), concat(' ', "foo", ' '))]@, i.e. leading and tailing spaces are added to the element's class attribute value and the requested value, and then it checks that the requested value is contained in the actual class attribute value.)
+
+h4. Locating elements using an XPath or CSS selector
+
+Instead using the API described above you can also specify an XPath or CSS selector like so:
+
+<pre>locate(html, :xpath => "//div[@id='foo']")
+locate(html, :xpath => "div#foo")</pre>
+
+These both would lookup the same div element with the id "foo".
+
+h3. Scoping to an element
+
+You can scope the element lookup to certain parts of your HTML Dom. E.g. this is useful when you have a couple of forms with the same input elements and you want to fill in a particular one.
+
+You can use both the Locator.locate and Locator.within methods for this:
+
+pre. within(:form, "login_form") { locate(html, :field, "password") }
+
+Or:
+
+pre. locate(html, :form, "login_form") { locate(html, :field, "password") }
+
+h2. Appendix
+
+<a name="locator-types"></a>
+
+h3. Supported locator types
+
+All types will match the id attribute, all form elements (input, textarea etc.) additionally match the name attribute. Some locators additionally match the value attribute and/or the node content (inner_text). Also see below for "matchable values":#matchable-values.
+
+All form element locator types (like :field, :checkbox, :file etc.) can additionally be located through their label tag. E.g. when you have a label tag "Name" that points to a text input tag then you can locate the text input using the text selector "Name". E.g.:
+
+pre. locate(html, :field, "Name")
+
+Here's a list of supported locator types and any additional matchable values:
+
+| *Type*         | *Locates*                                                                     | *Extra matchable*                         |
+| :button        | a button element or a submit, button or image input tag                       | content (for buttons), value (for inputs) |
+| :check_box     | a checkbox input tag                                                          |                                           |
+| :field         | an input element (see below) or a textarea                                    |                                           |
+| :file          | a file input tag                                                              |                                           |
+| :form          | a form tag                                                                    |                                           |
+| :hidden_field  | a hidden input tag                                                            |                                           |
+| :input         | an input tag with a type of text, password , email, url, search, tel or color |                                           |
+| :label         | a label tag                                                                   | content                                   |
+| :link          | a link (i.e. an :a tag with an href attribute)                                | content                                   |
+| :radio_button  | a radio input tag                                                             |                                           |
+| :select        | a select box                                                                  |                                           |
+| :select_option | a select option tag                                                           | value, content                            |
+| :text_area     | a textarea tag                                                                |                                           |
+
+<a name="matchable-values"></a>
+
+h3. Matchable values
+
+When given a *selector* Locator (as in @locate("The link")@) will match it against different node values depending on the locator type. Node attributes like id, name and value need to equal the given selector. The node content needs to include the selector text (case sensitive).
+
+Locator will then pick the *outermost* element with the *shortest* matching value.
+
+| *Matchable*  | *Looks at*                    | *Match type*         |
+| content      | the element's full inner text | contained in content |
+| id           | the elements id attribute     | equals               |
+| name         | the elements name attribute   | equals               |
+| value        | the elements value attribute  | equals               |
+
+E.g. @locate(html, :link, "link")@ will find both a link with the text @"link"@ as well as @"The link"@ but it will select and return the first one because it has the shorter matching value (i.e. @"link"@).
+
+Locator regards the inner text of an element as its content. That means that the given HTML structure looks like this:
+
+<pre><div>
+  <div>
+    Some <span>text</span>
+  </div>
+</div></pre>
+
+... then @locate(:div, "Some text")@ will locate the outer div because it a) ignores the nested span so that the content (inner text) is @"Some text"@ and b) the contents of both div elements are the same.
+
+The same locator will return the inner div though when given the following HTML structure:
+
+<pre><div>
+  <div>
+    Some <span>text</span>
+  </div>
+  here
+</div></pre>
+
+... because the content of the outer div now is @"Some text here"@ which is longer than @"Some text"@ and Locator returns the *outermost* element with the *shortest*@ matching value.
+
+This might seem complicated at first but it is required and quite consistent if you think about it. 
+
+One obvious reason for returning the outermost element is that one wants @locate@ and @within@ behave the same way. If within would refer to the innermost element though then the following locator would not find any element in the HTML above which would be highly confusing:
+
+<pre>within(:div) { within(:div) { locate(:span) } }</pre>
+
+And an obvious reason for returning an element with the shortest matching value is that in the following case one will want @locate("The Link")@ to return the second element, not the first one:
+
+<pre><a href="#">The link with extra text</a>
+<a href="http://www.some-very-long-url.com">The link!</a></pre>
+
+<a name="why-another-library"></a>
+
+h3. Why another library?
+
+In my opinion each of the libraries mentioned above do way to much. Amongst many other things they all implement tools for locating HTML elements from a Dom in some way. When we look at the details of the implementation they all do it differently though. So moving a test suite from Webrat to Capybara or Steam might be easy if only the simplest and most common helpers are used. But it can also be a huge pita because of all the tiny differences in those libraries: the APIs are simply not the same even if they seem to be at the first glimpse.
+
+Thus, having a library that does nothing but locating elements but does this one thing well and can then be used by other solutions that add other features is the way to go.
+
+By now Locator has been integrated to Steam (which already very much streamlined Steam's API). Obviously I would be humbled if other solutions would pick up Locator, too, and I do offer my help for working on this.
+
+
+TODO
+
+* add notes about using Locator::Element classes directly
+

data/TODO

@@ -1,4 +1,4 @@
-somehow allow these?
+Somehow allow these?
 
   locate(html, :foo) { locate(:bar) }
   within(html, :foo) { locate(:bar) }

data/lib/core_ext/hash/except.rb

@@ -0,0 +1,11 @@
+class Hash
+  def except!(*keys)
+    keys.map! { |key| convert_key(key) } if respond_to?(:convert_key)
+    keys.each { |key| delete(key) }
+    self
+  end
+  
+  def except(*keys)
+    dup.except!(*keys)
+  end
+end unless Hash.method_defined?(:slice)

data/lib/core_ext/hash/slice.rb

@@ -0,0 +1,14 @@
+class Hash
+  def slice!(*keys)
+    omit = slice(*self.keys - keys)
+    hash = slice(*keys)
+    replace(hash)
+    omit
+  end
+
+  def slice(*keys)
+    hash = self.class.new
+    keys.each { |k| hash[k] = self[k] if has_key?(k) }
+    hash
+  end
+end unless Hash.method_defined?(:slice)

data/lib/locator.rb

@@ -26,7 +26,8 @@ module Locator
       end
   end
 
-  def xpath(type, *args)
+  def xpath(*args)
+    type = args.shift if args.first.is_a?(Symbol)
     Locator[type].new.xpath(*args)
   end
 

data/lib/locator/dom.rb

@@ -2,6 +2,7 @@ require 'nokogiri'
 
 module Locator
   module Dom
+    autoload :Htmlunit, 'locator/dom/htmlunit'
     autoload :Nokogiri, 'locator/dom/nokogiri'
     
     class << self

data/lib/locator/dom/htmlunit.rb

@@ -0,0 +1,10 @@
+require 'nokogiri'
+
+module Locator
+  module Dom
+    module Htmlunit
+      autoload :Element, 'locator/dom/htmlunit/element'
+      autoload :Page,    'locator/dom/htmlunit/page'
+    end
+  end
+end

data/lib/locator/dom/htmlunit/element.rb

@@ -0,0 +1,80 @@
+module Locator
+  module Dom
+    module Htmlunit
+      class Element
+        attr_reader :element, :matches
+
+        def initialize(element)
+          @element = element || raise('nil passed as an element')
+          @matches = []
+        end
+
+        def <=>(other)
+          to_s.length <=> other.to_s.length
+        end
+
+        def name
+          element.getNodeName
+        end
+
+        def xpath
+          element.getCanonicalXPath
+        end
+
+        def css_path
+          raise 'not implemented'
+        end
+        
+        def content
+          # TODO HtmlUnit has asText and getTextContent
+          element.getTextContent # Celerity normalizes this
+        end
+        
+        # def inner_html
+        #   element.inner_html
+        # end
+        
+        def to_s
+          element.asXml
+        end
+        
+        def attribute(name)
+          element.getAttribute(name)
+        end
+        
+        def element_by_id(id)
+          element_by_xpath("//*[@id='#{id}']")
+        end
+
+        def element_by_xpath(xpath)
+          if element = self.element.getFirstByXPath(xpath)
+            Element.new(element)
+          end
+        end
+        
+        def elements_by_xpath(*xpaths)
+          xpaths.map do |xpath| 
+            element.getByXPath(xpath).toArray.map { |e| Element.new(e) }
+          end.flatten
+        end
+
+        def elements_by_css(*rules)
+          elements_by_xpath(*::Nokogiri::CSS.xpath_for(*rules))
+        end
+
+        def ancestors
+          ancestors, node = [], element.getParentNode
+          until node.getNodeName == '#document'
+            ancestors.unshift(Element.new(node))
+            node = node.getParentNode
+          end
+          ancestors
+        end
+        
+        def ancestor_of?(other)
+          other.element.ancestors.include?(element)
+        end
+      end
+    end
+  end
+end

data/lib/locator/dom/htmlunit/page.rb

@@ -0,0 +1,11 @@
+module Locator
+  module Dom
+    module Htmlunit
+      class Page < Element
+        def dom
+          element
+        end
+      end
+    end
+  end
+end

data/lib/locator/dom/nokogiri/element.rb

@@ -14,7 +14,7 @@ module Locator
         end
 
         def name
-          @element.name
+          element.name
         end
 
         def xpath
@@ -37,32 +37,32 @@ module Locator
           element.to_s
         end
 
-        def tag_name
-          element.description.name
-        end
-
-        def ancestor_of?(other)
-          other.element.ancestors.include?(element)
-        end
-
         def attribute(name)
           element.attribute(name).to_s
         end
 
-        def attributes(names)
-          names.map { |name| attribute(name) }
-        end
-
         def element_by_id(id)
           elements_by_xpath("//*[@id='#{id}']").first
         end
 
+        def element_by_xpath(xpath)
+          elements_by_xpath(xpath).first
+        end
+        
+        def elements_by_xpath(*xpaths)
+          element.xpath(*xpaths).map { |element| Element.new(element) }
+        end
+
         def elements_by_css(*rules)
           element.css(*rules).map { |element| Element.new(element) }
         end
 
-        def elements_by_xpath(*xpaths)
-          element.xpath(*xpaths).map { |element| Element.new(element) }
+        def ancestors
+          element.ancestors
+        end
+
+        def ancestor_of?(other)
+          other.ancestors.include?(element)
         end
       end
     end

data/lib/locator/dom/nokogiri/page.rb

@@ -2,8 +2,9 @@ module Locator
   module Dom
     module Nokogiri
       class Page < Element
-        def initialize(html)
-          super(::Nokogiri::HTML::Document.parse(html))
+        def initialize(dom)
+          dom = ::Nokogiri::HTML::Document.parse(dom) if dom.is_a?(String)
+          super
         end
         
         def dom

data/lib/locator/element.rb

@@ -1,3 +1,6 @@
+require 'core_ext/hash/except'
+require 'core_ext/hash/slice'
+
 module Locator
   class Element
     autoload :Area,           'locator/element/area'
@@ -20,10 +23,11 @@ module Locator
 
     attr_reader :name, :css, :locatables, :attributes
 
-    def initialize(name = nil, locatables = nil, attributes = nil)
+    def initialize(*args)
+      attributes, name = args.last.is_a?(Hash) ? args.pop : {}, args.pop
       @name = name
-      @locatables = { :equals => :id, :matches => :content }.merge(locatables || {})
-      @attributes = attributes || {}
+      @attributes = attributes
+      @locatables = ((attributes.delete(:matches) || [:content]) + [:id]).uniq
     end
 
     def locate(*args)
@@ -46,7 +50,8 @@ module Locator
       def lookup(scope, selector, attributes = {})
         scope = scope.respond_to?(:elements_by_xpath) ? scope : Locator::Dom.page(scope)
         xpath, css = attributes.delete(:xpath), attributes.delete(:css)
-        elements = css ? scope.elements_by_css(css) : scope.elements_by_xpath(xpath || xpath(attributes))
+        xpath = ::Nokogiri::CSS.xpath_for(*css).first if css
+        elements = scope.elements_by_xpath(xpath || xpath(attributes))
         Result.new(elements).filter!(selector, locatables)
       end
   end

data/lib/locator/element/area.rb

@@ -2,7 +2,7 @@ module Locator
   class Element
     class Area < Element
       def initialize
-        super(:area, :equals => [:id], :matches => [:alt])
+        super(:area, :matches => [:alt])
       end
     end
   end

data/lib/locator/element/button.rb

@@ -2,8 +2,8 @@ module Locator
   class Element
     class Button < ElementsList
       def initialize
-        input  = Element.new(:input, { :equals => [:id, :name], :matches => [:value] }, :type => %w(submit button image))
-        button = Element.new(:button, :equals => [:id, :name], :matches => [:content])
+        input  = Element.new(:input, :matches => [:value], :type => %w(submit button image))
+        button = Element.new(:button, :matches => [:content])
         super(input, button)
       end
     end

data/lib/locator/element/form.rb

@@ -2,7 +2,7 @@ module Locator
   class Element
     class Form < Element
       def initialize
-        super(:form, :equals => [:id, :name])
+        super(:form)
       end
     end
   end

data/lib/locator/element/form_element.rb

@@ -1,8 +1,14 @@
 module Locator
   class Element
     class FormElement < Element
+      def initialize(name, attributes = {})
+        attributes[:matches] ||= []
+        attributes[:matches] << :name
+        super
+      end
+
       def lookup(dom, selector, attributes)
-        super(dom, selector, attributes) + LabeledElement.new(name).send(:lookup, dom, selector, attributes)
+        super(dom, selector, attributes) + LabeledElement.new(name).send(:lookup, dom, selector, attributes.dup)
       end
     end
   end

data/lib/locator/element/input.rb

@@ -2,9 +2,8 @@ module Locator
   class Element
     class Input < FormElement
       def initialize(attributes = {})
-        attributes = { :type => [:text, :password , :email, :url, :search, :tel, :color] }.merge(attributes)
-        matchables = { :equals => [:id, :name] }
-        super(:input, { :equals => [:id, :name] }, attributes)
+        defaults = { :type => [:text, :password , :email, :url, :search, :tel, :color] }
+        super(:input, defaults.merge(attributes))
       end
     end
   end

data/lib/locator/element/label.rb

@@ -2,7 +2,7 @@ module Locator
   class Element
     class Label < Element
       def initialize
-        super(:label, :equals => [:id, :content])
+        super(:label, :matches => [:content])
       end
     end
   end

data/lib/locator/element/link.rb

@@ -2,7 +2,7 @@ module Locator
   class Element
     class Link < Element
       def initialize
-        super(:a, nil, :href => true)
+        super(:a, :href => true)
       end
     end
   end

data/lib/locator/element/select.rb

@@ -2,7 +2,7 @@ module Locator
   class Element
     class Select < FormElement
       def initialize
-        super(:select, :equals => [:id, :name])
+        super(:select)
       end
     end
   end

data/lib/locator/element/select_option.rb

@@ -2,7 +2,7 @@ module Locator
   class Element
     class SelectOption < Element
       def initialize
-        super(:option, :equals => [:id, :value, :content])
+        super(:option, :matches => [:value, :content])
       end
     end
   end

data/lib/locator/element/text_area.rb

@@ -2,7 +2,7 @@ module Locator
   class Element
     class TextArea < FormElement
       def initialize
-        super(:textarea, :equals => [:id, :name])
+        super(:textarea)
       end
     end
   end

data/lib/locator/result.rb

@@ -1,13 +1,29 @@
 module Locator
   class Result < Array
+    MATCH_TYPES = {
+      :alt     => :contains,
+      :title   => :contains,
+      :content => :contains
+    }
+
     class << self
+      def matches?(name, value, selector)
+        value = normalize_whitespace(value)
+        case selector
+        when Regexp
+          value =~ selector
+        else
+          type = MATCH_TYPES[name] || :equals
+          send("#{type}?", value, selector)
+        end
+      end
+
       def equals?(value, selector)
         value == selector
       end
 
-      def matches?(value, selector)
-        value = normalize_whitespace(value)
-        Regexp === selector ? value =~ selector : value.include?(selector)
+      def contains?(value, selector)
+        value.include?(selector)
       end
 
       def normalize_whitespace(value)
@@ -20,7 +36,7 @@ module Locator
     end
 
     def filter(selector, locatables)
-      selector ? locatables.map { |(type, attrs)| filter_by(type, selector, attrs) }.flatten : self
+      selector ? filter_by(selector, locatables) : self
     end
 
     def sort!
@@ -34,11 +50,11 @@ module Locator
 
     protected
 
-      def filter_by(type, selector, attributes)
+      def filter_by(selector, attributes)
         select do |element|
           Array(attributes).any? do |name|
             value = name == :content ? element.content : element.attribute(name.to_s)
-            element.matches << value if self.class.send("#{type}?", value, selector)
+            element.matches << value if self.class.matches?(name, value, selector)
           end
         end
       end

data/lib/locator/version.rb

@@ -1,3 +1,3 @@
 module Locator
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/lib/locator/xpath.rb

@@ -46,6 +46,10 @@ module Locator
       replace(self.map { |l| other.map { |r| "#{l}#{r}" } })
     end
 
+    def or!(other)
+      other.empty? ? self : replace([self.dup, other])
+    end
+
     def to_s
       flatten.join(' | ')
     end

data/test/locator/dom/htmlunit_test.rb

@@ -0,0 +1,77 @@
+require File.expand_path('../../../test_helper', __FILE__)
+
+$: << '~/Development/projects/steam/lib'
+require 'steam'
+include Steam
+
+Java.load(Dir["#{Steam.config[:html_unit][:java_path]}/*.jar"].join(':'))
+Java.import 'com.gargoylesoftware.htmlunit.WebClient'
+Java.import 'com.gargoylesoftware.htmlunit.BrowserVersion'
+
+class HtmlunitElementTest < Test::Unit::TestCase
+  include Locator, Java::Com::Gargoylesoftware::Htmlunit
+
+  def setup
+    connection = Connection::Mock.new
+    client = WebClient.new(BrowserVersion.FIREFOX_3)
+    client.setWebConnection(Rjb::bind(Browser::HtmlUnit::Connection.new(connection), 'com.gargoylesoftware.htmlunit.WebConnection'))
+
+    connection.mock(:get, 'http://localhost:3000/', '<a href="#" class="foo">the link</a><div id="bar"></div>')
+    @dom = Dom::Htmlunit::Page.new(client.getPage('http://localhost:3000/'))
+  end
+
+  test "Element takes a Htmlunit::Page adapter" do
+    element = Element::Link.new.locate(@dom, 'the link', :class => 'foo')
+    assert element.name
+  end
+
+  test "responds to name" do
+    element = Element::Link.new.locate(@dom, 'the link')
+    assert_equal 'a', element.name
+  end
+
+  test "responds to xpath" do
+    element = Element::Link.new.locate(@dom, 'the link')
+    assert_equal '/html/body/a', element.xpath
+  end
+
+  test "responds to to_s" do
+    element = Element::Link.new.locate(@dom, 'the link')
+    assert_equal "<a href=\"#\" class=\"foo\">\n  the link\n</a>\n", element.to_s
+  end
+
+  test "responds to content" do
+    element = Element::Link.new.locate(@dom, 'the link')
+    assert_equal "the link", element.content
+  end
+
+  test "responds to attribute" do
+    element = Element::Link.new.locate(@dom, 'the link')
+    assert_equal 'foo', element.attribute('class')
+  end
+
+  test "responds to element_by_id" do
+    element = Element.new(:html).locate(@dom)
+    assert_equal 'bar', element.element_by_id('bar').attribute('id')
+  end
+
+  test "responds to element_by_xpath" do
+    element = Element.new(:html).locate(@dom)
+    assert_equal 'bar', element.element_by_xpath('//html/body/div[@id="bar"]').attribute('id')
+  end
+  
+  test "responds to elements_by_xpath" do
+    element = Element::Link.new.locate(@dom, 'the link')
+    assert_equal 'foo', element.attribute('class')
+  end
+
+  test "responds to ancestors" do
+    element = Element.new(:a).locate(@dom)
+    assert_equal %w(html body), element.ancestors.map { |e| e.name }
+  end
+
+  test "responds to ancestor_of?" do
+    element = Element.new(:a).locate(@dom)
+    assert_equal %w(html body), element.ancestors.map { |e| e.name }
+  end
+end

data/test/locator/dom/nokogiri_test.rb

@@ -0,0 +1,16 @@
+require File.expand_path('../../../test_helper', __FILE__)
+require 'nokogiri'
+
+class NokogiriTest < Test::Unit::TestCase
+  include Locator
+
+  # test "Element takes a Nokogiri dom" do
+  #   dom = Nokogiri::HTML::Document.parse('<a href="#">the link</a>')
+  #   assert Element.new.locate(dom, 'the link')
+  # end
+
+  test "Element takes a Nokogiri page adapter" do
+    dom = Locator::Dom::Nokogiri::Page.new('<a href="#">the link</a>')
+    assert Element.new.locate(dom, 'the link')
+  end
+end

data/test/locator/element/button_test.rb

@@ -6,22 +6,22 @@ class ElementButtonTest < Test::Unit::TestCase
 
   test "finds a button" do
     html = '<button></button>'
-    assert_equal 'button', Button.new.locate(html).tag_name
+    assert_equal 'button', Button.new.locate(html).name
   end
 
   test "finds a submit input" do
     html = '<input type="submit">'
-    assert_equal 'input', Button.new.locate(html).tag_name
+    assert_equal 'input', Button.new.locate(html).name
   end
 
   test "finds a button input" do
     html = '<input type="button">'
-    assert_equal 'input', Button.new.locate(html).tag_name
+    assert_equal 'input', Button.new.locate(html).name
   end
 
   test "finds an image input" do
     html = '<input type="image">'
-    assert_equal 'input', Button.new.locate(html).tag_name
+    assert_equal 'input', Button.new.locate(html).name
   end
 
   test "does not find a checkbox input" do

data/test/locator/element/field_test.rb

@@ -6,62 +6,62 @@ class ElementFieldTest < Test::Unit::TestCase
 
   test "finds a textarea" do
     html = '<textarea></textarea>'
-    assert_equal 'textarea', Field.new.locate(html).tag_name
+    assert_equal 'textarea', Field.new.locate(html).name
   end
   
   test "finds a text input" do
     html = '<input type="text">'
-    assert_equal 'input', Field.new.locate(html).tag_name
+    assert_equal 'input', Field.new.locate(html).name
   end
   
   test "finds a password input" do
     html = '<input type="password">'
-    assert_equal 'input', Field.new.locate(html).tag_name
+    assert_equal 'input', Field.new.locate(html).name
   end
   
   test "finds an email input" do
     html = '<input type="email">'
-    assert_equal 'input', Field.new.locate(html).tag_name
+    assert_equal 'input', Field.new.locate(html).name
   end
   
   test "finds a url input" do
     html = '<input type="url">'
-    assert_equal 'input', Field.new.locate(html).tag_name
+    assert_equal 'input', Field.new.locate(html).name
   end
   
   test "finds a search input" do
     html = '<input type="search">'
-    assert_equal 'input', Field.new.locate(html).tag_name
+    assert_equal 'input', Field.new.locate(html).name
   end
   
   test "finds a tel input" do
     html = '<input type="tel">'
-    assert_equal 'input', Field.new.locate(html).tag_name
+    assert_equal 'input', Field.new.locate(html).name
   end
   
   test "finds a color input" do
     html = '<input type="color">'
-    assert_equal 'input', Field.new.locate(html).tag_name
+    assert_equal 'input', Field.new.locate(html).name
   end
 
   test "finds a text input by name" do
     html = '<input type="text" name="foo">'
-    assert_equal 'input', Field.new.locate(html, 'foo').tag_name
+    assert_equal 'input', Field.new.locate(html, 'foo').name
   end
 
   test "finds a text input by class attribute" do
     html = '<input type="text" class="foo">'
-    assert_equal 'input', Field.new.locate(html, :class => 'foo').tag_name
+    assert_equal 'input', Field.new.locate(html, :class => 'foo').name
   end
 
   test "finds an input by label content" do
     html = '<label for="bar">foo</label><input type="text" id="bar">'
-    assert_equal 'input', Field.new.locate(html, 'foo').tag_name
+    assert_equal 'input', Field.new.locate(html, 'foo').name
   end
 
   test "finds an input by label content and input class" do
     html = '<label for="bar">foo</label><input type="text" id="bar" class="baz">'
-    assert_equal 'input', Field.new.locate(html, 'foo', :class => 'baz').tag_name
+    assert_equal 'input', Field.new.locate(html, 'foo', :class => 'baz').name
   end
 
   test "does not find a checkbox input" do

data/test/locator/element/form_test.rb

@@ -6,22 +6,22 @@ class ElementFormTest < Test::Unit::TestCase
 
   test "finds a form" do
     html = '<form></form>'
-    assert_equal 'form', Form.new.locate(html).tag_name
+    assert_equal 'form', Form.new.locate(html).name
   end
 
   test "finds a form by id" do
     html = '<form id="foo"></form>'
-    assert_equal 'form', Form.new.locate(html, 'foo').tag_name
+    assert_equal 'form', Form.new.locate(html, 'foo').name
   end
 
   test "finds a form by name" do
     html = '<form name="foo"></form>'
-    assert_equal 'form', Form.new.locate(html, 'foo').tag_name
+    assert_equal 'form', Form.new.locate(html, 'foo').name
   end
 
   test "finds a form by class" do
     html = '<form class="foo"></form>'
-    assert_equal 'form', Form.new.locate(html, :class => 'foo').tag_name
+    assert_equal 'form', Form.new.locate(html, :class => 'foo').name
   end
 
   test "does not find a form when id does not match" do

data/test/locator/element/hidden_field_test.rb

@@ -0,0 +1,36 @@
+require File.expand_path('../../../test_helper', __FILE__)
+require 'locator/element'
+
+class ElementHiddenFieldTest < Test::Unit::TestCase
+  HiddenField = Locator::Element::HiddenField
+
+  test "finds a hidden input" do
+    html = '<input type="hidden" />'
+    assert_equal 'input', HiddenField.new.locate(html).name
+  end
+
+  test "finds a hidden input by id" do
+    html = '<input type="hidden" id="foo" />'
+    assert_equal 'input', HiddenField.new.locate(html, 'foo').name
+  end
+
+  test "finds a hidden input by name" do
+    html = '<input type="hidden" name="foo" />'
+    assert_equal 'input', HiddenField.new.locate(html, 'foo').name
+  end
+
+  test "finds a hidden input by class" do
+    html = '<input type="hidden" class="foo" />'
+    assert_equal 'input', HiddenField.new.locate(html, :class => 'foo').name
+  end
+
+  test "does not find a hidden input when id does not match" do
+    html = '<input type="hidden" id="bar" />'
+    assert_nil HiddenField.new.locate(html, :class => 'foo')
+  end
+
+  test "does not find a hidden input when class does not match" do
+    html = '<input type="hidden" class="bar" />'
+    assert_nil HiddenField.new.locate(html, :class => 'foo')
+  end
+end

data/test/locator/element/label_test.rb

@@ -5,17 +5,17 @@ class ElementLabelTest < Test::Unit::TestCase
 
   test "finds a label" do
     html = '<label></label>'
-    assert_equal 'label', Label.new.locate(html).tag_name
+    assert_equal 'label', Label.new.locate(html).name
   end
 
   test "finds a label by id" do
     html = '<label id="foo"></label>'
-    assert_equal 'label', Label.new.locate(html, 'foo').tag_name
+    assert_equal 'label', Label.new.locate(html, 'foo').name
   end
 
   test "finds a label by class" do
     html = '<label class="foo"></label>'
-    assert_equal 'label', Label.new.locate(html, :class => 'foo').tag_name
+    assert_equal 'label', Label.new.locate(html, :class => 'foo').name
   end
 
   test "does not find a label when id does not match" do

data/test/locator/element/select_option_test.rb

@@ -6,27 +6,27 @@ class ElementSelectOptionOptionTest < Test::Unit::TestCase
 
   test "finds an option" do
     html = '<option></option>'
-    assert_equal 'option', SelectOption.new.locate(html).tag_name
+    assert_equal 'option', SelectOption.new.locate(html).name
   end
 
   test "finds an option by id" do
     html = '<option id="foo"></option>'
-    assert_equal 'option', SelectOption.new.locate(html, 'foo').tag_name
+    assert_equal 'option', SelectOption.new.locate(html, 'foo').name
   end
 
   test "finds an option by value" do
     html = '<option value="foo"></option>'
-    assert_equal 'option', SelectOption.new.locate(html, 'foo').tag_name
+    assert_equal 'option', SelectOption.new.locate(html, 'foo').name
   end
 
   test "finds an option by content" do
     html = '<option>foo</option>'
-    assert_equal 'option', SelectOption.new.locate(html, 'foo').tag_name
+    assert_equal 'option', SelectOption.new.locate(html, 'foo').name
   end
 
   test "finds an option by class attribute" do
     html = '<option class="foo"></option>'
-    assert_equal 'option', SelectOption.new.locate(html, :class => 'foo').tag_name
+    assert_equal 'option', SelectOption.new.locate(html, :class => 'foo').name
   end
 
   test "does not find an option when id does not match" do

data/test/locator/element/select_test.rb

@@ -5,17 +5,17 @@ class ElementSelectTest < Test::Unit::TestCase
 
   test "finds a select" do
     html = '<select id="foo" class="foo"></select><select id="bar" class="bar"></select>'
-    assert_equal 'select', Select.new.locate(html).tag_name
+    assert_equal 'select', Select.new.locate(html).name
   end
 
   test "finds a select by id" do
     html = '<select id="foo"></select>'
-    assert_equal 'select', Select.new.locate(html, 'foo').tag_name
+    assert_equal 'select', Select.new.locate(html, 'foo').name
   end
 
   test "finds a select by class" do
     html = '<select class="foo"></select>'
-    assert_equal 'select', Select.new.locate(html, :class => 'foo').tag_name
+    assert_equal 'select', Select.new.locate(html, :class => 'foo').name
   end
 
   test "does not find a select when id does not match" do

data/test/locator/element/text_area_test.rb

@@ -6,17 +6,17 @@ class ElementTextAreaTest < Test::Unit::TestCase
 
   test "finds a textarea" do
     html = '<textarea></textarea>'
-    assert_equal 'textarea', TextArea.new.locate(html).tag_name
+    assert_equal 'textarea', TextArea.new.locate(html).name
   end
 
   test "finds a textarea by id" do
     html = '<textarea id="foo"></textarea>'
-    assert_equal 'textarea', TextArea.new.locate(html, 'foo').tag_name
+    assert_equal 'textarea', TextArea.new.locate(html, 'foo').name
   end
 
   test "finds a textarea by class" do
     html = '<textarea class="foo"></textarea>'
-    assert_equal 'textarea', TextArea.new.locate(html, :class => 'foo').tag_name
+    assert_equal 'textarea', TextArea.new.locate(html, :class => 'foo').name
   end
 
   test "does not find a textarea when id does not match" do

data/test/locator/element_test.rb

@@ -15,39 +15,49 @@ class LocatorElementTest < Test::Unit::TestCase
   end
 
   test "xpath with attributes" do
-    xpath = Element.new(nil, nil, :type => 'type', :class => 'class').xpath
+    xpath = Element.new(nil, :type => 'type', :class => 'class').xpath
     assert_equal ".//*[@type=\"type\"][contains(concat(' ', @class, ' '), concat(' ', \"class\", ' '))]", xpath
   end
 
   test "xpath with node name and attributes" do
-    xpath = Element.new(:div, nil, :type => 'type', :class => 'class').xpath
+    xpath = Element.new(:div, :type => 'type', :class => 'class').xpath
     assert_equal ".//div[@type=\"type\"][contains(concat(' ', @class, ' '), concat(' ', \"class\", ' '))]", xpath
   end
 
+  test "xpath with multiple node name and attributes" do
+    xpath = Element.new([:div, :p], :type => 'type').xpath
+    assert_equal ".//div[@type=\"type\"] | .//p[@type=\"type\"]", xpath
+  end
+
+  test "xpath merges given attributes with element attributes" do
+    xpath = Element.new(:div, :foo => 'foo').xpath(:bar => 'bar')
+    assert_equal ".//div[@foo=\"foo\"][@bar=\"bar\"]", xpath
+  end
+
   # all
 
   test "all selects all elements when given no attributes" do
     html = '<a class="foo"></a><p class="bar"></p>'
     elements = Element.new.all(html)
-    assert_equal %w(html body a p), elements.map { |element| element.tag_name }
+    assert_equal %w(html body a p), elements.map { |element| element.name }
   end
 
   test "all selects all nodes with given node name" do
     html = '<a class="foo"></a><p class="bar"></p>'
     elements = Element.new('a').all(html)
-    assert_equal %w(a), elements.map { |element| element.tag_name }
+    assert_equal %w(a), elements.map { |element| element.name }
   end
 
   test "all selects all nodes with attribute given to initialize" do
     html = '<a class="foo"></a><p class="bar"></p>'
-    elements = Element.new(nil, nil, :class => 'foo').all(html)
-    assert_equal %w(a), elements.map { |element| element.tag_name }
+    elements = Element.new(:class => 'foo').all(html)
+    assert_equal %w(a), elements.map { |element| element.name }
   end
 
   test "all selects all nodes with attribute given to all" do
     html = '<a class="foo"></a><p class="bar"></p>'
     elements = Element.new.all(html, :class => 'foo')
-    assert_equal %w(a), elements.map { |element| element.tag_name }
+    assert_equal %w(a), elements.map { |element| element.name }
   end
 
   # locate

data/test/locator_test.rb

@@ -20,16 +20,16 @@ class LocatorTest < Test::Unit::TestCase
 
   # locate
 
-  test "locates an element by node name" do
-    html = '<html><body><form></form></body></html>'
+  test "locates the first element by node name" do
+    html = '<html><body><form id="foo"></form><form id="bar"></form></body></html>'
     element = Locator.locate(html, :form)
-    assert_equal 'form', element.tag_name
+    assert_equal 'foo', element.attribute('id')
   end
 
-  test "locates an element by xpath" do
-    html = '<html><body><form></form></body></html>'
+  test "locates the first element by xpath" do
+    html = '<html><body><form id="foo"></form><form id="bar"></form></body></html>'
     element = Locator.locate(html, :xpath => '//form')
-    assert_equal 'form', element.tag_name
+    assert_equal 'foo', element.attribute('id')
   end
 
   # within
@@ -77,9 +77,9 @@ class LocatorTest < Test::Unit::TestCase
   end
 
   test "locate when given a block scopes the block to the located element" do
-    html = '<form></form><div><form><p id="foo"><p></form></div>'
+    html = '<p id="foo"><p><form></form><div><form><p id="bar"><p></form></div>'
     element = locate(html, :div) { locate(html, :form)  { locate(html, :p) } }
-    assert_equal 'foo', element.attribute('id')
+    assert_equal 'bar', element.attribute('id')
   end
 
   test "locate does not yield the block when no element was found (would otherwise locate in global scope)" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: locator
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Sven Fuchs
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-13 00:00:00 +01:00
+date: 2010-02-21 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -26,10 +26,15 @@ files:
 - README.textile
 - Rakefile
 - TODO
+- lib/core_ext/hash/except.rb
+- lib/core_ext/hash/slice.rb
 - lib/core_ext/string/underscore.rb
 - lib/locator.rb
 - lib/locator/boolean.rb
 - lib/locator/dom.rb
+- lib/locator/dom/htmlunit.rb
+- lib/locator/dom/htmlunit/element.rb
+- lib/locator/dom/htmlunit/page.rb
 - lib/locator/dom/nokogiri.rb
 - lib/locator/dom/nokogiri/element.rb
 - lib/locator/dom/nokogiri/page.rb
@@ -56,9 +61,12 @@ files:
 - lib/locator/xpath.rb
 - test/all.rb
 - test/locator/boolean_test.rb
+- test/locator/dom/htmlunit_test.rb
+- test/locator/dom/nokogiri_test.rb
 - test/locator/element/button_test.rb
 - test/locator/element/field_test.rb
 - test/locator/element/form_test.rb
+- test/locator/element/hidden_field_test.rb
 - test/locator/element/label_test.rb
 - test/locator/element/link_test.rb
 - test/locator/element/select_option_test.rb
@@ -99,9 +107,12 @@ summary: Generic html element locators for integration testing
 test_files: 
 - test/all.rb
 - test/locator/boolean_test.rb
+- test/locator/dom/htmlunit_test.rb
+- test/locator/dom/nokogiri_test.rb
 - test/locator/element/button_test.rb
 - test/locator/element/field_test.rb
 - test/locator/element/form_test.rb
+- test/locator/element/hidden_field_test.rb
 - test/locator/element/label_test.rb
 - test/locator/element/link_test.rb
 - test/locator/element/select_option_test.rb