dill 0.4.1 → 0.4.2

data/lib/dill/checkpoint.rb

@@ -0,0 +1,117 @@
+module Dill
+  # A point in time where some condition, or some set of conditions, should be
+  # verified.
+  #
+  # @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 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
+
+    # Initializes a new Checkpoint.
+    #
+    # @param wait_time how long this checkpoint will wait for its conditions to
+    #   be met, in seconds.
+    def initialize(wait_time = Capybara.default_wait_time)
+      @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.
+    #
+    # @param raise_errors [Boolean] whether to propagate exceptions that are
+    #   "rescuable" when {wait_time} expires.
+    #
+    # @yield a block encapsulating the condition to be evaluated.
+    # @yieldreturn a truthy value, if condition is met, a falsey value otherwise.
+    #
+    # @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_until(raise_errors = true, &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
+
+        wait
+
+        raise TimeFrozen, 'time appears to be frozen' if time_frozen?
+
+        retry
+      end
+    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
+
+    def wait
+      sleep 0.05
+    end
+
+    def time_frozen?
+      Time.now == start_time
+    end
+  end
+end

data/lib/dill/version.rb

@@ -1,3 +1,3 @@
 module Dill
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/lib/dill/widget.rb

@@ -4,6 +4,8 @@ module Dill
 
     include WidgetContainer
 
+    class Removed < StandardError; end
+
     # @!group Widget macros
 
       # Defines a new action.
@@ -12,6 +14,9 @@ module Dill
       # on that widget. You can then send a widget instance the message given
       # by +name+.
       #
+      # You can access the underlying widget by appending "_widget" to the
+      # action name.
+      #
       # @example
       #   # Consider the widget will encapsulate the following HTML
       #   #
@@ -25,50 +30,132 @@ module Dill
       #     action :edit, '[rel = edit]'
       #   end
       #
+      #   pirate_profile = widget(:pirate_profile)
+      #
+      #   # Access the action widget
+      #   action_widget = pirate_profile.widget(:edit_widget)
+      #   action_widget = pirate_profile.edit_widget
+      #
       #   # Click the link
-      #   widget(:pirate_profile).edit
+      #   pirate_profile.edit
       #
       # @param name the name of the action
       # @param selector the selector for the widget that will be clicked
       def self.action(name, selector)
-        widget name, selector
+        wname = :"#{name}_widget"
+
+        widget wname, selector
 
         define_method name do
-          widget(name).click
+          widget(wname).click
 
           self
         end
       end
 
-      # Declares a new sub-widget.
+      # Declares a new child widget.
+      #
+      # Child widgets are accessible inside the container widget using the
+      # {#widget} message, or by sending a message +name+. They
+      # are automatically scoped to the parent widget's root node.
+      #
+      # @example Defining a widget
+      #   # Given the following HTML:
+      #   #
+      #   # <div id="root">
+      #   #   <span id="child">Child</span>
+      #   # </div>
+      #   class Container < Dill::Widget
+      #     root '#root'
+      #
+      #     widget :my_widget, '#child'
+      #   end
+      #
+      #   container = widget(:container)
+      #
+      #   # accessing using #widget
+      #   my_widget = container.widget(:my_widget)
+      #
+      #   # accessing using #my_widget
+      #   my_widget = container.my_widget
+      #
+      # @overload widget(name, selector, type = Widget)
+      #
+      #   The most common form, it allows you to pass in a selector as well as a
+      #   type for the child widget. The selector will override +type+'s
+      #   root selector, if +type+ has one defined.
       #
-      # Sub-widgets are accessible inside the container widget using the
-      # +widget+ message.
+      #   @param name the child widget's name.
+      #   @param selector the child widget's selector.
+      #   @param type the child widget's parent class.
       #
-      # @param name the name of the sub-widget
-      # @param selector the sub-widget selector
-      # @param parent [Class] the parent class of the new sub-widget
+      # @overload widget(name, type)
+      #
+      #   This form allows you to omit +selector+ from the arguments. It will
+      #   reuse +type+'s root selector.
+      #
+      #   @param name the child widget's name.
+      #   @param type the child widget's parent class.
+      #
+      #   @raise ArgumentError if +type+ has no root selector defined.
       #
       # @yield A block allowing you to further customize the widget behavior.
       #
       # @see #widget
-      def self.widget(name, selector, parent = Widget, &block)
-        type = Class.new(parent) {
-          root selector
-        }
+      def self.widget(name, *rest, &block)
+        raise ArgumentError, "`#{name}' is a reserved name" \
+          if WidgetContainer.instance_methods.include?(name.to_sym)
+
+        case rest.first
+        when Class
+          arg_count = rest.size + 1
+          raise ArgumentError, "wrong number of arguments (#{arg_count} for 2)" \
+            unless arg_count == 2
+
+          type = rest.first
+          raise TypeError, "can't convert `#{type}' to Widget" \
+            unless type.methods.include?(:selector)
+          raise ArgumentError, "missing root selector for `#{type}'" \
+            unless type.selector
+
+          selector = type.selector
+        when String
+          arg_count = rest.size + 1
+
+          case arg_count
+          when 0, 1
+            raise ArgumentError, "wrong number of arguments (#{arg_count} for 2)"
+          when 2
+            selector, type = [*rest, Widget]
+          when 3
+            selector, type = rest
+
+            raise TypeError, "can't convert `#{type}' to Widget" \
+              unless Class === type
+          else
+            raise ArgumentError, "wrong number of arguments (#{arg_count} for 3)"
+          end
+        else
+          raise ArgumentError, "unknown method signature: #{rest.inspect}"
+        end
+
+        child = Class.new(type) { root selector }
+        child.class_eval(&block) if block_given?
 
-        type.class_eval(&block) if block_given?
+        const_set(Dill::WidgetName.new(name).to_sym, child)
 
-        const_set(Dill::WidgetName.new(name).to_sym, type)
+        define_method name do
+          widget(name)
+        end
       end
 
-      # Creates a delegator for one sub-widget message.
+      # Creates a delegator for one child widget message.
       #
       # Since widgets are accessed through {WidgetContainer#widget}, we can't
       # use {Forwardable} to delegate messages to widgets.
       #
-      # @param name the name of the receiver sub-widget
-      # @param widget_message the name of the message to be sent to the sub-widget
+      # @param name the name of the receiver child widget
+      # @param widget_message the name of the message to be sent to the child widget
       # @param method_name the name of the delegator. If +nil+ the method will
       #   have the same name as the message it will send.
       def self.widget_delegator(name, widget_message, method_name = nil)
@@ -87,16 +174,6 @@ module Dill
 
     # @!endgroup
 
-    # Determines if an instance of this widget class exists in
-    # +parent_node+.
-    #
-    # @param parent_node [Capybara::Node] the node we want to search in
-    #
-    # @return +true+ if a widget instance is found, +false+ otherwise.
-    def self.present_in?(parent_node)
-      parent_node.has_selector?(selector)
-    end
-
     # Finds a single instance of the current widget in +node+.
     #
     # @param node the node we want to search in
@@ -108,6 +185,16 @@ module Dill
       new(options.merge(root: node.find(selector)))
     end
 
+    # Determines if an instance of this widget class exists in
+    # +parent_node+.
+    #
+    # @param parent_node [Capybara::Node] the node we want to search in
+    #
+    # @return +true+ if a widget instance is found, +false+ otherwise.
+    def self.present_in?(parent_node)
+      parent_node.has_selector?(selector)
+    end
+
     # Sets this widget's default selector.
     #
     # @param selector [String] a CSS or XPath query
@@ -129,6 +216,22 @@ module Dill
       self.root = settings.fetch(:root)
     end
 
+    # Compares the current widget with +value+, waiting for the comparison
+    # to return +true+.
+    def ==(value)
+      checkpoint.wait_until(false) { cast_to(value) == value }
+    end
+
+    # Compares the current widget with +value+, waiting for the comparison
+    # to return +false+.
+    def !=(value)
+      checkpoint.wait_until(false) { cast_to(value) != value }
+    end
+
+    def checkpoint(wait_time)
+      Checkpoint.new(wait_time)
+    end
+
     # Determines if the widget underlying an action exists.
     #
     # @param name the name of the action
@@ -140,14 +243,18 @@ module Dill
     def has_action?(name)
       raise Missing, "couldn't find `#{name}' action" unless respond_to?(name)
 
-      has_widget?(name)
+      has_widget?(:"#{name}_widget")
     end
 
     def inspect
+      root = self.root
+
       xml = Nokogiri::HTML(page.body).at(root.path).to_xml
 
       "<!-- #{self.class.name}: -->\n" <<
        Nokogiri::XML(xml, &:noblanks).to_xhtml
+    rescue Capybara::NotSupportedByDriverError
+      root.inspect
     end
 
     class Reload < Capybara::ElementNotFound; end
@@ -172,21 +279,31 @@ module Dill
     #   reloaded, +false+ otherwise.
     #
     # @return the current widget
+    #
+    # @see Checkpoint
     def reload(wait_time = Capybara.default_wait_time, &test)
       unless test
-        old_inspect = inspect
-        test        = ->{ old_inspect != inspect }
+        old_root = root
+        test     = ->{ old_root != root }
       end
 
-      root.synchronize(wait_time) do
-        raise Reload unless test.()
+      checkpoint(wait_time).wait_until(false, &test)
+
+      begin
+        root.inspect
+      rescue
+        raise Removed, "widget was removed"
       end
 
       self
-    rescue Reload
-      # raised on timeout
+    end
 
-      self
+    def to_i
+      to_s.to_i
+    end
+
+    def to_f
+      to_s.to_f
     end
 
     def to_s
@@ -197,6 +314,19 @@ module Dill
 
     protected
 
+    def cast_to(value)
+      case value
+      when Float
+        to_f
+      when Integer
+        to_i
+      when String
+        to_s
+      else
+        raise TypeError, "can't convert this widget to `#{klass}'"
+      end
+    end
+
     def node_text(node)
       NodeText.new(node)
     end
@@ -205,6 +335,10 @@ module Dill
 
     attr_writer :root
 
+    def checkpoint(wait_time = Capybara.default_wait_time)
+      Checkpoint.new(wait_time)
+    end
+
     def page
       Capybara.current_session
     end

data/lib/dill.rb

@@ -2,6 +2,7 @@ require 'chronic'
 require 'nokogiri'
 require 'capybara'
 
+require 'dill/checkpoint'
 require 'dill/widget_container'
 require 'dill/conversions'
 require 'dill/instance_conversions'

metadata

@@ -2,31 +2,15 @@
 name: dill
 version: !ruby/object:Gem::Version
   prerelease: 
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - David Leal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-30 00:00:00.000000000 Z
+date: 2013-08-05 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-    none: false
-  name: cucumber
-  type: :runtime
-  prerelease: false
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-    none: false
 - !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -107,6 +91,22 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.0.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: poltergeist
+  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
@@ -117,6 +117,7 @@ files:
 - lib/dill.rb
 - lib/dill/auto_table.rb
 - lib/dill/base_table.rb
+- lib/dill/checkpoint.rb
 - lib/dill/conversions.rb
 - lib/dill/cucumber.rb
 - lib/dill/document.rb