locator 0.0.1 → 0.0.2

data/README.textile

@@ -1,5 +1,13 @@
 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.
+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.
 
-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.
+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.
+
+h3. Building an XPath
+
+h3. Locating an element
+
+h3. Scoping to an element

data/TODO

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

data/lib/locator/boolean.rb

@@ -1,4 +1,4 @@
-class Locator
+module Locator
   module Boolean
     class Terms < Array
       def and!(other)

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

@@ -1,20 +1,29 @@
-class Locator
+module Locator
   module Dom
     module Nokogiri
       class Element
-        attr_reader :element
+        attr_reader :element, :matches
 
         def initialize(element)
           @element = element
+          @matches = []
         end
-        
+
+        def <=>(other)
+          to_s.length <=> other.to_s.length
+        end
+
         def xpath
           element.path.to_s
         end
-        
+
         def css_path
           element.css_path.to_s
         end
+        
+        def content
+          element.content
+        end
 
         def inner_html
           element.inner_html
@@ -39,7 +48,7 @@ class Locator
         def attributes(names)
           names.map { |name| attribute(name) }
         end
-        
+
         def elements_by_xpath(xpath)
           element.xpath(xpath).map { |element| Element.new(element) }
         end

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

@@ -1,4 +1,4 @@
-class Locator
+module Locator
   module Dom
     module Nokogiri
       class Page
@@ -12,8 +12,12 @@ class Locator
           elements_by_xpath("//*[@id='#{id}']").first
         end
 
-        def elements_by_xpath(xpath)
-          @dom.xpath(xpath).map { |element| Element.new(element) }
+        def elements_by_css(*rules)
+          @dom.css(*rules).map { |element| Element.new(element) }
+        end
+
+        def elements_by_xpath(*xpaths)
+          @dom.xpath(*xpaths).map { |element| Element.new(element) }
         end
 
         def to_s

data/lib/locator/dom/nokogiri.rb

@@ -1,6 +1,6 @@
 require 'nokogiri'
 
-class Locator
+module Locator
   module Dom
     module Nokogiri
       autoload :Element, 'locator/dom/nokogiri/element'

data/lib/locator/dom.rb

@@ -1,6 +1,6 @@
 require 'nokogiri'
 
-class Locator
+module Locator
   module Dom
     autoload :Nokogiri, 'locator/dom/nokogiri'
     

data/lib/locator/element/area.rb

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

data/lib/locator/element/button.rb

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

data/lib/locator/element/check_box.rb

@@ -0,0 +1,9 @@
+module Locator
+  class Element
+    class CheckBox < Input
+      def initialize
+        super(:type => :checkbox)
+      end
+    end
+  end
+end

data/lib/locator/element/elements_list.rb

@@ -1,14 +1,14 @@
-class Locator
+module Locator
   class Element
-    class ElementsList
+    class ElementsList < Element
       attr_reader :elements
-      
+
       def initialize(*elements)
         @elements = elements
       end
-      
-      def xpath(*args)
-        elements.map { |element| element.xpath(*args) }.join(' | ')
+
+      def lookup(dom, selector, attributes)
+        Result.new(elements.map { |element| element.send(:lookup, dom, selector, attributes) }.flatten)
       end
     end
   end

data/lib/locator/element/field.rb

@@ -1,9 +1,8 @@
-class Locator
+module Locator
   class Element
     class Field < ElementsList
       def initialize
-        types = [:text, :password , :email, :url, :search, :tel, :color]
-        super(LabeledElement.new('input', [:id, :name], :type => types), TextArea.new)
+        super(Input.new, TextArea.new)
       end
     end
   end

data/lib/locator/element/file.rb

@@ -0,0 +1,9 @@
+module Locator
+  class Element
+    class File < Input
+      def initialize
+        super('input', :type => :file)
+      end
+    end
+  end
+end

data/lib/locator/element/form.rb

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

data/lib/locator/element/form_element.rb

@@ -0,0 +1,9 @@
+module Locator
+  class Element
+    class FormElement < Element
+      def lookup(dom, selector, attributes)
+        super(dom, selector, attributes) + LabeledElement.new(name).send(:lookup, dom, selector, attributes)
+      end
+    end
+  end
+end

data/lib/locator/element/hidden_field.rb

@@ -0,0 +1,9 @@
+module Locator
+  class Element
+    class HiddenField < Input
+      def initialize
+        super(:type => :hidden)
+      end
+    end
+  end
+end

data/lib/locator/element/input.rb

@@ -0,0 +1,11 @@
+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)
+      end
+    end
+  end
+end

data/lib/locator/element/label.rb

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

data/lib/locator/element/labeled_element.rb

@@ -1,16 +1,14 @@
-class Locator
+module Locator
   class Element
     class LabeledElement < Element
-      attr_reader :labeled
-
-      def initialize(name = '*', locatables = [], attributes = {})
-        @labeled = Element.new(name, [], attributes)
-        super
+      def lookup(dom, selector, attributes)
+        ids = element_ids(dom, selector)
+        result = ids.empty? ? Result.new : super(dom, nil, attributes.merge(:id => ids))
+        result.each { |element| element.matches << selector }
       end
-
-      def compose(selector, attributes)
-        super
-        replace(self + labeled.and("[@id=//label[contains(.,\"#{selector}\")]/@for]")) if selector
+      
+      def element_ids(dom, selector)
+        Label.new.send(:lookup, dom, selector).map { |element| element.attribute('for') }
       end
     end
   end

data/lib/locator/element/link.rb

@@ -1,8 +1,8 @@
-class Locator
+module Locator
   class Element
     class Link < Element
       def initialize
-        super('a', [:id, :content], :href => true)
+        super('a', nil, :href => true)
       end
     end
   end

data/lib/locator/element/radio_button.rb

@@ -0,0 +1,9 @@
+module Locator
+  class Element
+    class RadioButton < Input
+      def initialize
+        super(:type => :radio)
+      end
+    end
+  end
+end

data/lib/locator/element/select.rb

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

data/lib/locator/element/select_option.rb

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

data/lib/locator/element/text_area.rb

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

data/lib/locator/element.rb

@@ -1,45 +1,52 @@
-class Locator
-  class Element < Xpath
+module Locator
+  class Element
     autoload :Area,           'locator/element/area'
     autoload :Button,         'locator/element/button'
+    autoload :CheckBox,       'locator/element/check_box'
     autoload :ElementsList,   'locator/element/elements_list'
     autoload :Field,          'locator/element/field'
+    autoload :File,           'locator/element/file'
     autoload :Form,           'locator/element/form'
+    autoload :FormElement,    'locator/element/form_element'
+    autoload :HiddenField,    'locator/element/hidden_field'
+    autoload :Input,          'locator/element/input'
     autoload :Label,          'locator/element/label'
     autoload :LabeledElement, 'locator/element/labeled_element'
     autoload :Link,           'locator/element/link'
+    autoload :RadioButton,    'locator/element/radio_button'
     autoload :Select,         'locator/element/select'
     autoload :SelectOption,   'locator/element/select_option'
     autoload :TextArea,       'locator/element/text_area'
-    
-    attr_reader :locatables
 
-    def initialize(name = '*', locatables = [], attributes = {})
-      super(name)
-      @content = !!locatables.delete(:content)
-      @locatables = locatables
-      @attributes = attributes
+    attr_reader :name, :locatables, :attributes
+
+    def initialize(name = nil, locatables = nil, attributes = nil)
+      @name = name || '*'
+      @locatables = { :equals => :id, :matches => :content }.merge(locatables || {})
+      @attributes = attributes || {}
+    end
+
+    def locate(*args)
+      all(*args).first
     end
 
-    def xpath(*args)
-      attributes = Hash === args.last ? args.pop : {}
-      compose(args.pop, attributes)
-      to_s
+    def all(dom, *args)
+      attributes, selector = args.last.is_a?(Hash) ? args.pop : {}, args.pop
+      result = lookup(dom, selector, attributes)
+      result.sort! if selector
+      result
+    end
+
+    def xpath(attributes = {})
+      Xpath.new(name, self.attributes.merge(attributes)).to_s
     end
 
     protected
-    
-      def content?
-        @content
-      end
 
-      def compose(selector, attributes)
-        attributes = @attributes.merge(attributes)
-        attributes.each { |name, value| and! equals(name, value) }
-        terms = []
-        terms << equals(locatables, selector) if selector
-        terms << contains(selector) if content? && selector
-        and!(terms) unless terms.empty?
+      def lookup(dom, selector, attributes = {})
+        dom = dom.respond_to?(:elements_by_xpath) ? dom : Locator::Dom.page(dom)
+        elements = dom.elements_by_xpath(xpath(attributes))
+        Result.new(elements).filter!(selector, locatables)
       end
   end
 end

data/lib/locator/result.rb

@@ -0,0 +1,46 @@
+module Locator
+  class Result < Array
+    class << self
+      def equals?(value, selector)
+        value == selector
+      end
+
+      def matches?(value, selector)
+        value = normalize_whitespace(value)
+        Regexp === selector ? value =~ selector : value.include?(selector)
+      end
+
+      def normalize_whitespace(value)
+        value.gsub(/\s+/, ' ').strip
+      end
+    end
+
+    def filter!(selector, locatables)
+      selector ? replace(filter(selector, locatables)) : self
+    end
+
+    def filter(selector, locatables)
+      selector ? locatables.map { |(type, attrs)| filter_by(type, selector, attrs) }.flatten : self
+    end
+
+    def sort!
+      each  { |element| element.matches.sort! }
+      super { |lft, rgt| lft.matches.first.length <=> rgt.matches.first.length }
+    end
+
+    def +(other)
+      replace(super)
+    end
+
+    protected
+
+      def filter_by(type, 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)
+          end
+        end
+      end
+  end
+end

data/lib/locator/version.rb

@@ -1,3 +1,3 @@
-class Locator
-  VERSION = "0.0.1"
+module Locator
+  VERSION = "0.0.2"
 end

data/lib/locator/xpath.rb

@@ -1,13 +1,20 @@
-class Locator
-  autoload :Boolean, 'locator/boolean'
-
+module Locator
   Boolean::Or.operator, Boolean::And.operator = ' | ', ''
 
-  class Xpath < Boolean::Terms
+  class Xpath < Array
     def initialize(name = nil, attributes = {})
-      names = Array(name || '*').map { |name| xpath?(name) ? name : ".//#{name}" }
-      super(names)
-      attributes.each { |name, value| and!(equals(name, value)) }
+      super(Array(name || '*').map { |name| xpath?(name) ? name : ".//#{name}" })
+
+      attributes.each do |name, value|
+        case name
+        when :class
+          and!(has_class(name, value))
+        else
+          and!(equals(name, value))
+        end
+      end
+
+      flatten!
     end
 
     def equals(names, values)
@@ -15,24 +22,36 @@ class Locator
       when TrueClass
         "[@#{names}]"
       else
-        values = Array(values).map { |value| xpath?(value) ? value : "\"#{value}\"" }
-        expr = Array(names).map { |name| values.map { |value| "@#{name}=#{value}" } }
-        expr.empty? ? '' : '[' + expr.flatten.join(' or ') + ']'
+        values = Array(values).map { |value| quote(value) }
+        expr= Array(names).map { |name| values.map { |value| "@#{name}=#{value}" } }.flatten
+        expr.empty? ? '' : '[' + expr.join(' or ') + ']'
       end
     end
 
-    def matches(name, value)
-      "[contains(@#{name},\"#{value}\")]"
+    def has_class(name, value)
+      "[contains(concat(' ', @#{name}, ' '), concat(' ', \"#{value}\", ' '))]"
     end
 
     def contains(value)
-      "/descendant-or-self::*[contains(.,\"#{value}\")]"
+      "/descendant-or-self::*[contains(., \"#{value}\")]"
+    end
+
+    def and!(other)
+      replace(self.map { |l| other.map { |r| "#{l}#{r}" } })
+    end
+
+    def to_s
+      flatten.join(' | ')
     end
 
     protected
 
+      def quote(value)
+        xpath?(value) ? value : "\"#{value}\""
+      end
+
       def xpath?(string)
-        string.to_s[0, 1] == '/'
+        string =~ %r(^\.?//)
       end
   end
 end

data/lib/locator.rb

@@ -1,18 +1,20 @@
 require 'core_ext/string/underscore'
 
-class Locator
-  autoload :Actions, 'locator/actions'
+module Locator
+  autoload :Boolean, 'locator/boolean'
   autoload :Dom,     'locator/dom'
   autoload :Element, 'locator/element'
+  autoload :Result,  'locator/result'
   autoload :Xpath,   'locator/xpath'
 
   class << self
     def [](type)
-      locators[type.to_sym]
+      locators[type.to_sym] || raise("unknown locator type: #{type}")
     end
 
-    def xpath(type, *args)
-      Locator[type].new.xpath(*args)
+    def build(type)
+      locator = locators[type.to_sym] if type
+      locator ? locator.new : Locator::Element.new(type)
     end
 
     protected
@@ -24,29 +26,49 @@ class Locator
       end
   end
 
-  attr_reader :dom, :scopes
-
-  def initialize(dom)
-    @dom = dom.respond_to?(:elements_by_xpath) ? dom : Dom.page(dom)
-    @scopes = []
+  def xpath(type, *args)
+    Locator[type].new.xpath(*args)
   end
 
-  def locate(type, *args)
+  def locate(dom, *args, &block)
+    return args.first if args.first.respond_to?(:elements_by_xpath)
+
     options = Hash === args.last ? args.last : {}
-    if scope = options.delete(:within)
-      within(scope) { locate(type, *args) }
+    result = if scope = options.delete(:within)
+      within(*Array(scope)) { locate(dom, *args) }
     else
-      path = type.is_a?(Symbol) ? Locator.xpath(type, *args) : type
-      scope = scopes.pop || dom
-      scope.elements_by_xpath(path).first
+      type = args.shift if args.first.is_a?(Symbol)
+      Locator.build(type).locate(current_scope(dom), *args)
     end
+
+    result && block_given? ? within(result) { yield(self) } : result
   end
 
-  # TODO currently only take an xpath or element
-  def within(scope, &block)
-    scope = scope.is_a?(Hash) ? scope.delete(:xpath) : scope
-    scope = locate(scope) unless scope.respond_to?(:xpath)
+  def within(*scope)
     scopes.push(scope)
-    instance_eval(&block)
+    yield(self)
   end
+
+  protected
+
+    def current_scope(dom)
+      dom = Locator::Dom.page(dom) unless dom.respond_to?(:elements_by_xpath)
+
+      case (scope = scopes.pop) && scope.first
+      when NilClass
+        dom
+      when %r(^\.?//)
+        dom.elements_by_xpath(scope.first).first
+      when String
+        dom.elements_by_css(scope.first).first
+      else
+        locate(dom, *scope)
+      end
+    end
+
+    def scopes
+      @scopes ||= []
+    end
+
+  extend(self)
 end

data/test/all.rb

@@ -1,3 +1,3 @@
 Dir[File.dirname(__FILE__) + '/**/*_test.rb'].each do |filename|
-  require filename
+  require filename unless filename.include?('_locator')
 end