dill 0.5.2 → 0.6.0

data/lib/dill/{form.rb → widgets/form.rb}

@@ -11,5 +11,14 @@ module Dill
       set attributes
       submit
     end
+
+    def to_table
+      info = self.
+        class.
+        field_names.
+        each_with_object({}) { |e, a| a[e.to_s] = widget(e).to_cell }
+
+      [info]
+    end
   end
 end

data/lib/dill/{list.rb → widgets/list.rb}

@@ -78,7 +78,7 @@ module Dill
   class List < Widget
     include Enumerable
 
-    def_delegators :items, :size, :include?, :each, :empty?, :first, :last
+    def_delegators :items, :each, :first, :last
 
     class << self
       # Configures the List item selector and class.
@@ -142,19 +142,53 @@ module Dill
       end
 
       def selector
-        super ||
-          begin
-            root 'ul'
+        begin
+          super
+        rescue Widget::MissingSelector
+          root 'ul'
 
-            super
-          end
+          super
+        end
       end
     end
 
+    def count
+      items.count
+    end
+
+    # TODO: Convert value to primitive data structures.
+    def empty?
+      items.empty?
+    end
+
+    def exclude?(element)
+      ! include?(element)
+    end
+
+    def include?(element)
+      value.include?(element)
+    end
+
+    def length
+      items.length
+    end
+
+    def size
+      items.size
+    end
+
+    def to_row
+      items.map(&:to_cell)
+    end
+
     def to_table
       items.map(&:to_row)
     end
 
+    def value
+      items.map(&:value)
+    end
+
     protected
 
     def_delegator 'self.class', :item_factory

data/lib/dill/widgets/parts/container.rb

@@ -0,0 +1,29 @@
+module Dill
+  module WidgetParts
+    module Container
+      def has_no_widget?(name)
+        widget(name).absent?
+      end
+
+      def has_widget?(name, *args)
+        widget(name, *args).present?
+      end
+
+      def widget(name, *args)
+        widget_class(name).find_in(self, *args)
+      end
+
+      private
+
+      attr_writer :widget_lookup_scope
+
+      def widget_class(name)
+        WidgetName.new(name).to_class(widget_lookup_scope)
+      end
+
+      def widget_lookup_scope
+        @widget_lookup_scope || self.class
+      end
+    end
+  end
+end

data/lib/dill/widgets/parts/struct.rb

@@ -0,0 +1,117 @@
+module Dill
+  module WidgetParts
+    module Struct
+      def self.included(target)
+        target.extend ClassMethods
+      end
+
+      module ClassMethods
+        def attribute(name, selector, &block)
+          child = widget(name, selector, &block)
+
+          class_eval <<-WIDGET
+            def #{name}
+              widget(:#{name}).value
+            end
+          WIDGET
+
+          child
+        end
+
+        def boolean(name, selector, &block)
+          child = widget(name, selector, &block)
+
+          class_eval <<-WIDGET
+            def #{name}?
+              widget(:#{name}).value
+            end
+          WIDGET
+
+          child.class_eval <<-VALUE
+            def value
+              Dill::Conversions::Boolean(text)
+            end
+          VALUE
+
+          child
+        end
+
+        def date(name, selector, &block)
+          child = attribute(name, selector, &block)
+
+          child.class_eval <<-VALUE
+            def value
+              Date.parse(text)
+            end
+          VALUE
+
+          child
+        end
+
+        def float(name, selector, &block)
+          child = attribute(name, selector, &block)
+
+          child.class_eval <<-VALUE
+            def value
+              Float(text)
+            end
+          VALUE
+
+          child
+        end
+
+        def integer(name, selector, &block)
+          child = attribute(name, selector, &block)
+
+          child.class_eval <<-VALUE
+            def value
+              Integer(text)
+            end
+          VALUE
+
+          child
+        end
+
+        def list(name, selector, options = {}, &block)
+          child = widget(name, selector, Dill::List) do
+            item options[:item_selector], options[:item_class] || ListItem
+          end
+
+          class_eval <<-WIDGET
+            def #{name}
+              widget(:#{name}).value
+            end
+          WIDGET
+
+          child.class_eval(&block) if block_given?
+
+          child
+        end
+
+        def string(name, *args, &block)
+          child = attribute(name, *args, &block)
+
+          child.class_eval <<-VALUE
+            def value
+              text
+            end
+          VALUE
+
+          child
+        end
+
+        def time(name, *args, &block)
+          child = attribute(name, *args, &block)
+
+          child.class_eval <<-VALUE
+            def value
+              Time.parse(text)
+            end
+          VALUE
+
+          child
+        end
+      end
+    end
+  end
+end

data/lib/dill/widgets/select.rb

@@ -0,0 +1,29 @@
+module Dill
+  # A select.
+  class Select < Field
+    # @return [String] The text of the selected option.
+    def get
+      option = root.find('[selected]') rescue nil
+
+      option && option.text
+    end
+
+    # Selects the given +option+.
+    #
+    # You may pass in the option text or value.
+    def set(option)
+      root.
+        find(:xpath, "option[@value = '#{option}' or . = '#{option}']").
+        select_option
+    end
+
+    # @!method to_s
+    #   @return the text of the selected option, or the empty string if
+    #     no option is selected.
+    def_delegator :get, :to_s
+
+    def to_cell
+      get
+    end
+  end
+end

data/lib/dill/{table.rb → widgets/table.rb}

@@ -24,7 +24,7 @@ module Dill
       attr_writer :header, :transform
 
       def node_text(node)
-        NodeText.new(node)
+        node.text.strip
       end
 
       def transform

data/lib/dill/widgets/text_field.rb

@@ -0,0 +1,23 @@
+module Dill
+  # A text field.
+  class TextField < Field
+    # @!method get
+    #   @return The text field value.
+    def_delegator :root, :value, :get
+
+    # @!method set(value)
+    #   Sets the text field value.
+    #
+    #   @param value [String] the value to set.
+    def_delegator :root, :set
+
+    # @!method to_s
+    #   @return the text field value, or the empty string if the field is
+    #     empty.
+    def_delegator :get, :to_s
+
+    def to_cell
+      get
+    end
+  end
+end

data/lib/dill/widgets/widget.rb

@@ -0,0 +1,404 @@
+module Dill
+  class Widget
+    extend Forwardable
+
+    include WidgetParts::Struct
+    include WidgetParts::Container
+
+    class Removed < StandardError; end
+
+    # @!group Widget macros
+
+    # Defines a new action.
+    #
+    # This is a shortcut to help defining a widget and a method that clicks
+    # 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
+    #   #
+    #   # <div id="profile">
+    #   #  <a href="/profiles/1/edit" rel="edit">Edit</a>
+    #   # </div>
+    #   class PirateProfile < Dill::Widget
+    #     root "#profile"
+    #
+    #     # Declare the action
+    #     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
+    #   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)
+      wname = :"#{name}_widget"
+
+      widget wname, selector
+
+      define_method name do
+        widget(wname).click
+
+        self
+      end
+    end
+
+    # 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.
+    #
+    #   @param name the child widget's name.
+    #   @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)
+    #
+    #   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, *rest, &block)
+      raise ArgumentError, "`#{name}' is a reserved name" \
+        if WidgetParts::Container.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, Array, Proc
+        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 = WidgetClass.new(selector, type, &block)
+
+      const_set(Dill::WidgetName.new(name).to_sym, child)
+
+      child
+    end
+
+    # Creates a delegator for one child widget message.
+    #
+    # Since widgets are accessed through {WidgetParts::Container#widget}, we
+    # can't use {Forwardable} to delegate messages to widgets.
+    #
+    # @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)
+      method_name = method_name || widget_message
+
+      class_eval <<-RUBY
+        def #{method_name}(*args)
+          if args.size == 1
+            widget(:#{name}).#{widget_message} args.first
+          else
+            widget(:#{name}).#{widget_message} *args
+          end
+        end
+      RUBY
+    end
+
+    # @!endgroup
+
+    # Finds a single instance of the current widget in +node+.
+    #
+    # @param node the node we want to search in
+    #
+    # @return a new instance of the current widget class.
+    #
+    # @raise [Capybara::ElementNotFoundError] if the widget can't be found
+    def self.find_in(parent, *args)
+      new { parent.root.find(*selector(*args)) }
+    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)
+      find_in(parent).present?
+    end
+
+    # Sets this widget's default 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, &block)
+      @selector = block ? [block] : selector.flatten
+    end
+
+    class MissingSelector < StandardError
+    end
+
+    # Returns the selector specified with +root+.
+    def self.selector(*args)
+      if @selector
+        fst = @selector.first
+
+        fst.respond_to?(:call) ? fst.call(*args) : @selector
+      else
+        if superclass.respond_to?(:selector)
+          superclass.selector
+        else
+          raise MissingSelector, 'no selector defined'
+        end
+      end
+    end
+
+    def initialize(node = nil, &query)
+      self.node = node
+      self.query = query
+    end
+
+    # Alias for #gone?
+    def absent?
+      gone?
+    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(*args)
+      if args.empty?
+        root.click
+      else
+        widget(*args).click
+      end
+    end
+
+    # Compares this widget with the given Cucumber +table+.
+    #
+    # === Example
+    #
+    #   Then(/^some step that takes in a cucumber table$/) do |table|
+    #     widget(:my_widget).diff table
+    #   end
+    def diff(table, wait_time = Capybara.default_wait_time)
+      table.diff!(to_table) || true
+    end
+
+    # Returns +true+ if the widget is not visible, or has been removed from the
+    # DOM.
+    def gone?
+      ! root rescue true
+    end
+
+    # Determines if the widget underlying an action exists.
+    #
+    # @param name the name of the action
+    #
+    # @raise Missing if an action with +name+ can't be found.
+    #
+    # @return [Boolean] +true+ if the action widget is found, +false+
+    #   otherwise.
+    def has_action?(name)
+      raise Missing, "couldn't find `#{name}' action" unless respond_to?(name)
+
+      has_widget?(:"#{name}_widget")
+    end
+
+    def inspect
+      inspection = "<!-- #{self.class.name}: -->\n"
+
+      begin
+        root = self.root
+        xml = Nokogiri::HTML(page.body).at(root.path).to_xml
+
+        inspection << Nokogiri::XML(xml, &:noblanks).to_xhtml
+      rescue Capybara::NotSupportedByDriverError
+        inspection << "<#{root.tag_name}>\n#{to_s}"
+      rescue Capybara::ElementNotFound, *page.driver.invalid_element_errors
+        "#<DETACHED>"
+      end
+    end
+
+    # Returns +true+ if widget is visible.
+    def present?
+      !! root rescue false
+    end
+
+    def root
+      node || query.()
+    end
+
+    def text
+      root.text.strip
+    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
+      text
+    end
+
+    def to_s
+      text
+    end
+
+    def value
+      text
+    end
+
+    private
+
+    attr_accessor :node, :query
+
+    def page
+      Capybara.current_session
+    end
+  end
+end