dill 0.4.4 → 0.5.0

data/lib/dill.rb

@@ -3,12 +3,15 @@ require 'nokogiri'
 require 'capybara'
 
 require 'dill/checkpoint'
+require 'dill/widget_class'
+require 'dill/widget_checkpoint'
 require 'dill/widget_container'
 require 'dill/conversions'
 require 'dill/instance_conversions'
 require 'dill/node_text'
 require 'dill/widget_name'
 require 'dill/widget'
+require 'dill/list_item'
 require 'dill/list'
 require 'dill/base_table'
 require 'dill/auto_table'

data/lib/dill/auto_table.rb

@@ -50,11 +50,11 @@ module Dill
 
     class Row < Widget
       def initialize(settings)
-        s = settings.dup
+        root = settings.delete(:root)
 
-        self.cell_selector = s.delete(:cell_selector)
+        self.cell_selector = settings.delete(:cell_selector)
 
-        super s
+        super root
       end
 
       def values

data/lib/dill/checkpoint.rb

@@ -5,25 +5,15 @@ module Dill
   # @see http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Base#synchronize-instance_method,
   #   which inspired this class.
   class Checkpoint
-    class ConditionNotMet < Capybara::ElementNotFound; end
+    class ConditionNotMet < StandardError; end
     class TimeFrozen < StandardError; end
 
     # @return the configured wait time, in seconds.
     attr_reader :wait_time
 
-    # @return the Capybara driver in use.
-    def self.driver
-      Capybara.current_session.driver
-    end
-
-    # Executes +block+ repeatedly until it returns a "truthy" value or +timeout+
-    # expires.
-    #
-    # TODO: Expand documentation.
-    def self.wait_for(wait_time = Capybara.default_wait_time,
-                      raise_errors = true,
-                      &block)
-      new(wait_time).wait_for(raise_errors, &block)
+    # Shortcut for instance level wait_for.
+    def self.wait_for(wait_time = Capybara.default_wait_time, &block)
+      new(wait_time).wait_for(&block)
     end
 
     # Initializes a new Checkpoint.
@@ -34,47 +24,24 @@ module Dill
       @wait_time = wait_time
     end
 
-    # Waits until the condition encapsulated by the block is met.
-    #
-    # Automatically rescues some exceptions ({Capybara::ElementNotFound}, and
-    # driver specific exceptions) until {wait_time} is exceeded. At that point
-    # it raises whatever exception was raised in the condition block, or
-    # {ConditionNotMet}, if no exception was raised inside the block. However,
-    # if +raise_errors+ is set to +false+, returns +false+ instead of
-    # propagating any of the automatically rescued exceptions.
-    #
-    # If an "unknown" exception is raised, it is propagated immediately, without
-    # waiting for {wait_time} to expire.
-    #
-    # If a driver that doesn't support waiting is used, any exception raised is
-    # immediately propagated.
+    # Executes +block+ repeatedly until it returns a "truthy" value or
+    # +wait_time+ expires.
     #
-    # @param raise_errors [Boolean] whether to propagate exceptions that are
-    #   "rescuable" when {wait_time} expires.
+    # Swallows any StandardError or StandardError descendent until +wait_time+
+    # expires. If an exception is raised and the time has expired, that
+    # exception will be raised again.
     #
-    # @yield a block encapsulating the condition to be evaluated.
-    # @yieldreturn a truthy value, if condition is met, a falsey value otherwise.
+    # If the block does not return a "truthy" value until +wait_time+ expires,
+    # raises a Dill::Checkpoint::ConditionNotMet error.
     #
-    # @return whatever the condition block returns if the condition is
-    #   successful. If the condition is not met, returns +false+ if
-    #   +rescue_errors+ is false.
-    def wait_for(raise_errors = true, &condition)
+    # Returns whatever value is returned by the block.
+    def wait_for(&condition)
       start
 
       begin
         yield or raise ConditionNotMet
-      rescue *rescuable_errors => e
-        if immediate?
-          raise e if raise_errors
-
-          return false
-        end
-
-        if expired?
-          raise e if raise_errors
-
-          return false
-        end
+      rescue *rescuable_errors
+        raise if expired?
 
         wait
 
@@ -84,34 +51,22 @@ module Dill
       end
     end
 
+    def rescuable_errors
+      StandardError
+    end
+
     private
 
     attr_reader :start_time
 
-    def driver
-      self.class.driver
-    end
-
-    def driver_errors
-      driver.invalid_element_errors
-    end
-
     def expired?
       remaining_time > wait_time
     end
 
-    def immediate?
-      ! driver.wait?
-    end
-
     def remaining_time
       Time.now - start_time
     end
 
-    def rescuable_errors
-      @rescuable_errors ||= [Capybara::ElementNotFound, *driver_errors]
-    end
-
     def start
       @start_time = Time.now
     end

data/lib/dill/dsl.rb

@@ -17,8 +17,8 @@ module Dill
     # Returns a widget instance for the given name.
     #
     # @param name [String, Symbol]
-    def widget(name, options = {})
-      document.widget(name, options)
+    def widget(name)
+      document.widget(name)
     end
 
     def widget_lookup_scope

data/lib/dill/field_group.rb

@@ -244,12 +244,12 @@ module Dill
 
     # A form field.
     class Field < Widget
-      def self.find_in(parent, options)
-        new({root: parent.find_field(selector)}.merge(options))
+      def self.find_in(parent)
+        new(parent.find_field(*selector))
       end
 
       def self.present_in?(parent)
-        parent.has_field?(selector)
+        parent.has_field?(*selector)
       end
 
       # @return This field's value.

data/lib/dill/list.rb

@@ -1,47 +1,174 @@
 module Dill
+  # Use a List when you want to treat repeating elements as a unit.
+  #
+  # === Usage
+  #
+  # Consider the following HTML:
+  #
+  #   <ul id="colors">
+  #     <li>Red <span class="pt">Vermelho</span></li>
+  #     <li>Green <span class="pt">Verde</span></li>
+  #     <li>Blue <span class="pt">Azul</span></li>
+  #   </ul>
+  #
+  # You can then define the following widget:
+  #
+  #   class Colors < Dill::List
+  #     root '#colors'
+  #     item 'li'
+  #   end
+  #
+  # Now you'll be able to iterate over each item:
+  #
+  #   # prints:
+  #   # Red Vermelho
+  #   # Green Verde
+  #   # Blue Azul
+  #   widget(:colors).each do |e|
+  #     puts e
+  #   end
+  #
+  # This is the same as doing the following in Capybara:
+  #
+  #   all('#colors li').each do |e|
+  #     puts e.text.strip
+  #   end
+  #
+  # Not that, by default, the root selector of a List is +ul+ and the list
+  # item selector is +li+. So you could wrap the +<ul>+ above simply by using
+  # the following:
+  #
+  #   class Colors < Dill::List
+  #   end
+  #
+  # ==== Narrowing items
+  #
+  # You can define the root selector for your list items using the ::item macro:
+  #
+  #   class PortugueseColors < Dill::List
+  #     root '#colors
+  #     item '.pt'
+  #   end
+  #
+  # If you iterate over this list you get the following:
+  #
+  #   # prints:
+  #   # Vermelho
+  #   # Verde
+  #   # Azul
+  #   widget(:portuguese_colors).each do |e|
+  #     puts e
+  #   end
+  #
+  # You can make a list out of any repeating elements, as long as you can define
+  # parent and child selectors.
+  #
+  #   <div id="not-a-list-colors">
+  #     <div class=".child">Red</div>
+  #     <div class=".child">Green</div>
+  #     <div class=".child">Blue</div>
+  #   </div>
+  #
+  # You can define the following widget:
+  #
+  #   class NotAListColors < Dill::List
+  #     root '#not-a-list-colors'
+  #     item '.child'
+  #   end
   class List < Widget
-    DEFAULT_TYPE = Widget
-
     include Enumerable
 
     def_delegators :items, :size, :include?, :each, :empty?, :first, :last
 
-    def self.item(selector, type = DEFAULT_TYPE, &item_for)
-      define_method :item_selector do
-        @item_selector ||= selector
+    class << self
+      # Configures the List item selector and class.
+      #
+      # === Usage
+      #
+      # Given the following HTML:
+      #
+      #   <ul>
+      #     <li>One</li>
+      #     <li>Two</li>
+      #     <li>Three</li>
+      #   </ul>
+      #
+      # In its most basic form, allows you to configure the list item selector,
+      # using the default list item class (Dill::ListItem):
+      #
+      #   class Numbers < Dill::List
+      #     root 'ul'
+      #     item 'li'
+      #   end
+      #
+      # ==== Extending the list item class
+      #
+      # You can define the list item class for the current List:
+      #
+      #   class Number < Dill::Widget
+      #     # ...
+      #   end
+      #
+      #   class Numbers < Dill::List
+      #     root 'ul'
+      #     item 'li', Number
+      #   end
+      #
+      #   widget(:numbers).first.class < Number #=> true
+      #
+      # Alternatively, you can extend the list item type inline. This is useful
+      # when you want to add small extensions to the default list item class.
+      # The extensions will apply only to list items of the current List.
+      #
+      #   class Numbers < Dill::List
+      #     root 'ul'
+      #
+      #     item 'li' do
+      #       def upcase
+      #         text.upcase
+      #       end
+      #     end
+      #
+      #     widget(:numbers).first.upcase #=> "ONE"
+      #   end
+      def item(selector, type = ListItem, &block)
+        self.item_factory = WidgetClass.new(selector, type, &block)
       end
 
-      if block_given?
-        define_method :item_for, &item_for
-      else
-        define_method :item_factory do
-          type
-        end
+      attr_writer :item_factory
+
+      def item_factory
+        @item_factory ||= WidgetClass.new('li', ListItem)
+      end
+
+      def selector
+        super ||
+          begin
+            root 'ul'
+
+            super
+          end
       end
     end
 
     def to_table
-      items.map { |e| Array(e) }
+      items.map(&:to_row)
     end
 
     protected
 
-    attr_writer :item_selector
-
-    def item_factory
-      DEFAULT_TYPE
-    end
+    def_delegator 'self.class', :item_factory
 
     def item_for(node)
-      item_factory.new(root: node)
+      item_factory.new(node)
     end
 
     def item_selector
-      'li'
+      item_factory.selector
     end
 
     def items
-      root.all(item_selector).map { |node| item_for(node) }
+      root.all(*item_selector).map { |node| item_for(node) }
     end
   end
 end

data/lib/dill/list_item.rb

@@ -0,0 +1,22 @@
+module Dill
+  class ListItem < Widget
+    # Returns this ListItem's contents formatted as a row, for comparison with a
+    # Cucumber::Ast::Table. By default, it simply returns an array with a single
+    # element--the widget's text.
+    #
+    # In general, this method will be called by List#to_table.
+    #
+    # === Overriding
+    #
+    # Feel free to override this method to return whatever you need it to.
+    # Usually, if the default return value isn't what you want, you'll probably
+    # want to return a Hash where both keys and values are strings, so that you
+    # don't need to worry about column order when you pass the table to
+    # Cucumber::Ast::Table#diff!.
+    #
+    # See List#to_table for more information.
+    def to_row
+      [to_cell]
+    end
+  end
+end

data/lib/dill/version.rb

@@ -1,3 +1,3 @@
 module Dill
-  VERSION = "0.4.4"
+  VERSION = "0.5.0"
 end

data/lib/dill/widget.rb

@@ -86,7 +86,8 @@ module Dill
       #   root selector, if +type+ has one defined.
       #
       #   @param name the child widget's name.
-      #   @param selector the child widget's selector.
+      #   @param selector the child widget's selector. You can pass either a
+      #     String or, if you want to use a composite selector, an Array.
       #   @param type the child widget's parent class.
       #
       # @overload widget(name, type)
@@ -119,7 +120,7 @@ module Dill
             unless type.selector
 
           selector = type.selector
-        when String
+        when String, Array
           arg_count = rest.size + 1
 
           case arg_count
@@ -139,8 +140,7 @@ module Dill
           raise ArgumentError, "unknown method signature: #{rest.inspect}"
         end
 
-        child = Class.new(type) { root selector }
-        child.class_eval(&block) if block_given?
+        child = WidgetClass.new(selector, type, &block)
 
         const_set(Dill::WidgetName.new(name).to_sym, child)
 
@@ -181,8 +181,8 @@ module Dill
     # @return a new instance of the current widget class.
     #
     # @raise [Capybara::ElementNotFoundError] if the widget can't be found
-    def self.find_in(node, options = {})
-      new(options.merge(root: node.find(selector)))
+    def self.find_in(node)
+      new(node.find(*selector))
     end
 
     # Determines if an instance of this widget class exists in
@@ -192,50 +192,192 @@ module Dill
     #
     # @return +true+ if a widget instance is found, +false+ otherwise.
     def self.present_in?(parent_node)
-      parent_node.has_selector?(selector)
+      parent_node.has_selector?(*selector)
     end
 
     # Sets this widget's default selector.
     #
-    # @param selector [String] a CSS or XPath query
-    def self.root(selector)
-      @selector = selector
+    # You can pass more than one argument to it, or a single Array. Any valid
+    # Capybara selector accepted by Capybara::Node::Finders#find will work.
+    #
+    # === Examples
+    #
+    # Most of the time, your selectors will be Strings:
+    #
+    #   class MyWidget < Dill::Widget
+    #     root '.selector'
+    #   end
+    #
+    # This will match any element with a class of "selector". For example:
+    #
+    #   <span class="selector">Pick me!</span>
+    #
+    # ==== Composite selectors
+    #
+    # If you're using CSS as the query language, it's useful to be able to use
+    # +text: 'Some text'+ to zero in on a specific node:
+    #
+    #   class MySpecificWidget < Dill::Widget
+    #     root '.selector', text: 'Pick me!'
+    #   end
+    #
+    # This is especially useful, e.g., when you want to create a widget
+    # to match a specific error or notification:
+    #
+    #   class NoFreeSpace < Dill::Widget
+    #     root '.error', text: 'No free space left!'
+    #   end
+    #
+    # So, given the following HTML:
+    #
+    #   <body>
+    #     <div class="error">No free space left!</div>
+    #
+    #     <!-- ... -->
+    #   </body>
+    #
+    # You can test for the error's present using the following code:
+    #
+    #   document.has_widget?(:no_free_space) #=> true
+    #
+    # Note: When you want to match text, consider using +I18n.t+ instead of
+    # hard-coding the text, so that your tests don't break when the text changes.
+    #
+    # Finally, you may want to override the query language:
+    #
+    #   class MyWidgetUsesXPath < Dill::Widget
+    #     root :xpath, '//some/node'
+    #   end
+    def self.root(*selector)
+      @selector = selector.flatten
     end
 
-    # @return The selector specified with +root+.
+    # Returns the selector specified with +root+.
     def self.selector
       @selector
     end
 
-    # @return The root node of the current widget
+    # Returns the root node (a Capybara::Node::Element) of the current widget.
     attr_reader :root
 
-    def_delegators :root, :click
+    def initialize(root)
+      self.root = root
+    end
+
+    # Returns +true+ if this widget's representation is less than +value+.
+    #
+    # Waits for the result to be +true+ for the time defined in
+    # `Capybara.default_wait_time`.
+    def <(value)
+      test { cast_to_type_of(value) < value }
+    end
 
-    def initialize(settings = {})
-      self.root = settings.fetch(:root)
+    # Returns +true+ if this widget's representation is less than or equal to
+    # +value+.
+    #
+    # Waits for the result to be +true+ for the time defined in
+    # `Capybara.default_wait_time`.
+    def <=(value)
+      test { cast_to_type_of(value) <= value }
+    end
+
+    # Returns +true+ if this widget's representation is greater than +value+.
+    #
+    # Waits for the result to be +true+ for the time defined in
+    # `Capybara.default_wait_time`.
+    def >(value)
+      test { cast_to_type_of(value) > value }
+    end
+
+    # Returns +true+ if this widget's representation is greater than or equal to
+    # +value+.
+    #
+    # Waits for the result to be +true+ for the time defined in
+    # `Capybara.default_wait_time`.
+    def >=(value)
+      test { cast_to_type_of(value) >= value }
     end
 
     # Compares the current widget with +value+, waiting for the comparison
     # to return +true+.
     def ==(value)
-      wait_for { cast_to_type_of(value) == value }
+      test { cast_to_type_of(value) == value }
     end
 
     # Calls +=~+ on this widget's text content.
     def =~(regexp)
-      wait_for { to_s =~ regexp }
+      test { to_s =~ regexp }
     end
 
     # Calls +!~+ on this widget's text content.
     def !~(regexp)
-      wait_for { to_s !~ regexp }
+      test { to_s !~ regexp }
     end
 
     # Compares the current widget with +value+, waiting for the comparison
     # to return +false+.
     def !=(value)
-      wait_for { cast_to_type_of(value) != value }
+      test { cast_to_type_of(value) != value }
+    end
+
+    # Clicks the current widget, or the child widget given by +name+.
+    #
+    # === Usage
+    #
+    # Given the following widget definition:
+    #
+    #   class Container < Dill::Widget
+    #     root '#container'
+    #
+    #     widget :link, 'a'
+    #   end
+    #
+    # Send +click+ with no arguments to trigger a +click+ event on +#container+.
+    #
+    #   widget(:container).click
+    #
+    # This is the equivalent of doing the following using Capybara:
+    #
+    #   find('#container').click
+    #
+    # Send +click :link+ to trigger a +click+ event on +a+:
+    #
+    #   widget(:container).click :link
+    #
+    # This is the equivalent of doing the following using Capybara:
+    #
+    #   find('#container a').click
+    def click(name = nil)
+      if name
+        widget(name).click
+      else
+        root.click
+      end
+    end
+
+    # Compares this widget with the given +diffable+, as long as it responds to
+    # the same protocol as Cucumber::Ast::Table#diff!.
+    #
+    # Waits +wait_time+ seconds for the comparison to be successful, otherwise
+    # raises Cucumber::Ast::Table::Different on failure.
+    #
+    # This is especially useful when you're not sure if the widget is in the
+    # proper state to be compared with the table.
+    #
+    # === Example
+    #
+    #   Then(/^some step that takes in a cucumber table$/) do |table|
+    #     widget(:my_widget).diff table
+    #   end
+    def diff(diffable, wait_time = Capybara.default_wait_time)
+      # #diff! raises an exception if the comparison fails, or returns nil if it
+      # doesn't. We don't need to worry about failure, because that will be
+      # propagated, but we need to return +true+ when it succeeds, to end the
+      # comparison.
+      #
+      # We use WidgetCheckpoint instead of #test because we want the
+      # succeed-or-raise behavior.
+      WidgetCheckpoint.wait_for(wait_time) { diffable.diff!(to_table) || true }
     end
 
     # Determines if the widget underlying an action exists.
@@ -265,8 +407,6 @@ module Dill
       end
     end
 
-    class Reload < Capybara::ElementNotFound; end
-
     # Reloads the widget, waiting for its contents to change (by default),
     # or until +wait_time+ expires.
     #
@@ -289,13 +429,13 @@ module Dill
     # @return the current widget
     #
     # @see Checkpoint
-    def reload(wait_time = Capybara.default_wait_time, &test)
+    def reload(wait_time = Capybara.default_wait_time, &condition)
       unless test
         old_root = root
         test     = ->{ old_root != root }
       end
 
-      wait_for(wait_time, false, &test)
+      test wait_time, &condition
 
       begin
         root.inspect
@@ -317,7 +457,23 @@ module Dill
     #
     # @return [MatchData] the match data from running +match+ on the text.
     def match(pattern, position = 0, &block)
-      wait_for { to_s.match(pattern, position, &block) }
+      test { to_s.match(pattern, position, &block) }
+    end
+
+    def text
+      NodeText.new(root)
+    end
+
+    # Converts this widget into a string representation suitable to be displayed
+    # in a Cucumber table cell. By default calls #text.
+    #
+    # This method will be called by methods that build tables or rows (usually
+    # #to_table or #to_row) so, in general, you won't call it directly, but feel
+    # free to override it when needed.
+    #
+    # Returns a String.
+    def to_cell
+      to_s
     end
 
     def to_i
@@ -328,9 +484,7 @@ module Dill
       to_s.to_f
     end
 
-    def to_s
-      node_text(root)
-    end
+    alias_method :to_s, :text
 
     protected
 
@@ -347,16 +501,12 @@ module Dill
       end
     end
 
-    def node_text(node)
-      NodeText.new(node)
-    end
-
     private
 
     attr_writer :root
 
-    def wait_for(wait_time = Capybara.default_wait_time, raise_errors = false, &block)
-      Checkpoint.wait_for(wait_time, raise_errors, &block)
+    def test(wait_time = Capybara.default_wait_time, &block)
+      WidgetCheckpoint.wait_for(wait_time, &block) rescue nil
     end
 
     def page

data/lib/dill/widget_checkpoint.rb

@@ -0,0 +1,30 @@
+module Dill
+  # A Checkpoint that bypasses the standard wait time if the current
+  # Capybara driver doesn't support waiting.
+  class WidgetCheckpoint < Checkpoint
+    # Returns the Capybara driver in use.
+    def driver
+      Capybara.current_session.driver
+    end
+
+    def initialize(*)
+      if immediate?
+        super 0
+      else
+        super
+      end
+    end
+
+    protected
+
+    def rescuable_errors
+      @rescuable_errors ||= Array(super) + driver.invalid_element_errors
+    end
+
+    private
+
+    def immediate?
+      ! driver.wait?
+    end
+  end
+end

data/lib/dill/widget_class.rb

@@ -0,0 +1,11 @@
+module Dill
+  module WidgetClass
+    def self.new(selector, parent = Widget, &extensions)
+      klass = Class.new(parent) { root selector }
+
+      klass.class_eval(&extensions) if block_given?
+
+      klass
+    end
+  end
+end

data/lib/dill/widget_container.rb

@@ -4,8 +4,8 @@ module Dill
       widget_class(name).present_in?(root)
     end
 
-    def widget(name, options = {})
-      widget_class(name).find_in(root, options)
+    def widget(name)
+      widget_class(name).find_in(root)
     end
 
     private

metadata

@@ -2,14 +2,14 @@
 name: dill
 version: !ruby/object:Gem::Version
   prerelease: 
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors:
 - David Leal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-08 00:00:00.000000000 Z
+date: 2013-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
@@ -107,6 +107,22 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.3.0
     none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+    none: false
+  name: cucumber
+  type: :development
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+    none: false
 description: See https://github.com/mojotech/dill/README.md
 email:
 - dleal@mojotech.com
@@ -126,6 +142,7 @@ files:
 - lib/dill/form.rb
 - lib/dill/instance_conversions.rb
 - lib/dill/list.rb
+- lib/dill/list_item.rb
 - lib/dill/node_text.rb
 - lib/dill/table.rb
 - lib/dill/text_table.rb
@@ -135,6 +152,8 @@ files:
 - lib/dill/text_table/void_mapping.rb
 - lib/dill/version.rb
 - lib/dill/widget.rb
+- lib/dill/widget_checkpoint.rb
+- lib/dill/widget_class.rb
 - lib/dill/widget_container.rb
 - lib/dill/widget_name.rb
 homepage: https://github.com/mojotech/dill