dill 0.4.0

data/lib/dill.rb

@@ -0,0 +1,28 @@
+require 'chronic'
+require 'nokogiri'
+require 'capybara'
+
+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'
+require 'dill/base_table'
+require 'dill/auto_table'
+require 'dill/table'
+require 'dill/field_group'
+require 'dill/form'
+require 'dill/document'
+require 'dill/text_table'
+require 'dill/text_table/mapping'
+require 'dill/text_table/void_mapping'
+require 'dill/text_table/transformations'
+require 'dill/text_table/cell_text'
+require 'dill/dsl'
+
+module Dill
+  # An exception that signals that something is missing.
+  class Missing < StandardError; end
+end

data/lib/dill/auto_table.rb

@@ -0,0 +1,73 @@
+module Dill
+  class AutoTable < BaseTable
+
+    # don't include footer in to_table, because footer column configuration is very
+    # often different from the headers & values.
+    def footers
+      @footers ||= root.all(footer_selector).map { |n| node_text(n) }
+    end
+
+    protected
+
+    def ensure_table_loaded
+      root.find(data_row_selector)
+    rescue Capybara::Ambiguous
+    end
+
+    private
+
+    def data_cell_selector
+      'td'
+    end
+
+    def data_row(node)
+      Row.new(root: node, cell_selector: data_cell_selector)
+    end
+
+    def data_row_selector
+      'tbody tr'
+    end
+
+    def data_rows
+      @data_rows ||= root.all(data_row_selector).map { |n| data_row(n) }
+    end
+
+    def header_selector
+      'thead th'
+    end
+
+    def headers
+      @headers ||= root.all(header_selector).map { |n| node_text(n).downcase }
+    end
+
+    def footer_selector
+      'tfoot td'
+    end
+
+    def values
+      @values ||= data_rows.map(&:values)
+    end
+
+    class Row < Widget
+      def initialize(settings)
+        s = settings.dup
+
+        self.cell_selector = s.delete(:cell_selector)
+
+        super s
+      end
+
+      def values
+        root.all(cell_selector).map { |n| node_text(n) }
+      end
+
+      private
+
+      attr_accessor :cell_selector
+
+      def node_text(node)
+        NodeText.new(node)
+      end
+    end
+  end
+end

data/lib/dill/base_table.rb

@@ -0,0 +1,9 @@
+module Dill
+  class BaseTable < Widget
+    def to_table
+      ensure_table_loaded
+
+      headers.any? ? [headers, *values] : values
+    end
+  end
+end

data/lib/dill/conversions.rb

@@ -0,0 +1,29 @@
+module Dill
+  module Conversions
+    def Boolean(val)
+      case val
+      when 'yes', 'true', true
+        true
+      when 'no', 'false', false, nil, ''
+        false
+      else
+        raise ArgumentError, "can't convert #{val.inspect} to boolean"
+      end
+    end
+
+    def List(valstr, &block)
+      vs = valstr.strip.split(/\s*,\s*/)
+
+      block ? vs.map(&block) : vs
+    end
+
+    def Timeish(val)
+      raise ArgumentError, "can't convert nil to Timeish" if val.nil?
+
+      return val if Date === val || Time === val || DateTime === val
+
+      Chronic.parse(val) or
+        raise ArgumentError, "can't parse #{val.inspect} to Timeish"
+    end
+  end
+end

data/lib/dill/cucumber.rb

@@ -0,0 +1,3 @@
+require 'dill'
+
+World(Dill::DSL)

data/lib/dill/document.rb

@@ -0,0 +1,14 @@
+module Dill
+  class Document
+    include WidgetContainer
+
+    def initialize(options)
+      self.widget_lookup_scope =
+        options.delete(:widget_lookup_scope) or raise "No scope given"
+    end
+
+    def root
+      Capybara.current_session
+    end
+  end
+end

data/lib/dill/dsl.rb

@@ -0,0 +1,34 @@
+module Dill
+  module DSL
+    attr_writer :widget_lookup_scope
+
+    # @return [Document] the current document with the class of the
+    #   current object set as the widget lookup scope.
+    def document
+      Document.new(widget_lookup_scope: widget_lookup_scope)
+    end
+
+    # @return [Boolean] Whether one or more widgets exist in the current
+    #   document.
+    def has_widget?(name)
+      document.has_widget?(name)
+    end
+
+    # Returns a widget instance for the given name.
+    #
+    # @param name [String, Symbol]
+    def widget(name, options = {})
+      document.widget(name, options)
+    end
+
+    def widget_lookup_scope
+      @widget_lookup_scope ||= default_widget_lookup_scope
+    end
+
+    private
+
+    def default_widget_lookup_scope
+      Module === self ? self : self.class
+    end
+  end
+end

data/lib/dill/field_group.rb

@@ -0,0 +1,331 @@
+module Dill
+  # A group of form fields.
+  #
+  # @todo Explain how to use locators when defining fields, including what
+  #   happens when locators are omitted.
+  class FieldGroup < Widget
+    root 'fieldset'
+
+    def self.default_locator(type = nil, &block)
+      alias_method :name_to_locator, type if type
+
+      define_method :name_to_locator, &block if block
+    end
+
+    # The names of all the fields that belong to this field group.
+    #
+    # Field names are automatically added to this group as long as you use
+    # the field definition macros.
+    #
+    # @return [Set] the field names.
+    #
+    # @see field
+    def self.field_names
+      @field_names ||= Set.new
+    end
+
+    # @!group Field definition macros
+
+    # Creates a new checkbox accessor.
+    #
+    # Adds the following methods to the widget:
+    #
+    # <name>:: Gets the current checkbox state, as a boolean. Returns +true+
+    #          if the corresponding check box is checked, +false+ otherwise.
+    # <name>=:: Sets the current checkbox state. Pass +true+ to check the
+    #           checkbox, +false+ otherwise.
+    #
+    # @example
+    #   # Given the following HTML:
+    #   #
+    #   # <form>
+    #   #   <p>
+    #   #     <label for="checked-box">
+    #   #     <input type="checkbox" value="1" id="checked-box" checked>
+    #   #   </p>
+    #   #   <p>
+    #   #     <label for="unchecked-box">
+    #   #     <input type="checkbox" value="1" id="unchecked-box">
+    #   #   </p>
+    #   # </form>
+    #   class MyFieldGroup < Dill::FieldGroup
+    #     root 'form'
+    #
+    #     check_box :checked_box, 'checked-box'
+    #     check_box :unchecked_box, 'unchecked-box'
+    #   end
+    #
+    #   form = widget(:my_field_group)
+    #
+    #   form.checked_box          #=> true
+    #   form.unchecked_box        #=> false
+    #
+    #   form.unchecked_box = true
+    #   form.unchecked_box        #=> true
+    #
+    # @param name the name of the checkbox accessor.
+    # @param locator the locator for the checkbox. If +nil+ the locator will
+    #   be derived from +name+.
+    #
+    # @todo Handle checkbox access when the field is disabled (raise an
+    #   exception?)
+    def self.check_box(name, locator = nil)
+      field name, locator, CheckBox
+    end
+
+    # Defines a new field.
+    #
+    # @param name the name of the field accessor.
+    # @param locator the field locator.
+    # @param type the field class name.
+    #
+    # @api private
+    def self.field(name, locator, type)
+      raise TypeError, "can't convert `#{name}' to Symbol" \
+        unless name.respond_to?(:to_sym)
+
+      field_names << name.to_sym
+
+      label     = name.to_s.gsub(/_/, ' ').capitalize
+      locator ||= label
+
+      widget name, locator, type do
+        define_method :label do
+          label
+        end
+      end
+
+      define_method "#{name}=" do |val|
+        widget(name).set val
+      end
+
+      define_method name do
+        widget(name).get
+      end
+    end
+
+    # Creates a new select accessor.
+    #
+    # Adds the following methods to the widget:
+    #
+    # <name>:: Gets the current selected option. Returns the label of the
+    #          selected option, or +nil+, if no option is selected.
+    # <name>=:: Selects an option on the current select. Pass the label of
+    #           the option you want to select.
+    #
+    # @example
+    #   # Given the following HTML:
+    #   #
+    #   # <form>
+    #   #   <p>
+    #   #     <label for="selected">
+    #   #     <select id="selected">
+    #   #       <option selected>Selected option</option>
+    #   #       <option>Another option</option>
+    #   #     </select>
+    #   #   </p>
+    #   #   <p>
+    #   #     <label for="deselected">
+    #   #     <select id="deselected">
+    #   #       <option>Deselected option</option>
+    #   #       <option>Another option</option>
+    #   #     </select>
+    #   #   </p>
+    #   # </form>
+    #   class MyFieldGroup < Dill::FieldGroup
+    #     root 'form'
+    #
+    #     select :selected, 'selected'
+    #     select :deselected, 'deselected'
+    #   end
+    #
+    #   form = widget(:my_field_group)
+    #
+    #   form.selected                         #=> "Selected option"
+    #   form.deselected                       #=> nil
+    #
+    #   form.deselected = "Deselected option"
+    #   form.unchecked_box                    #=> "Deselected option"
+    #
+    # @param name the name of the select accessor.
+    # @param locator the locator for the select. If +nil+ the locator will
+    #   be derived from +name+.
+    #
+    # @todo Handle select access when the field is disabled (raise an
+    #   exception?)
+    # @todo Raise an exception when an option doesn't exist.
+    # @todo Allow passing the option value to set an option.
+    # @todo Ensure an option with no text returns the empty string.
+    # @todo What to do when +nil+ is passed to the writer?
+    def self.select(name, locator = nil)
+      field name, locator, Select
+    end
+
+    # Creates a new text field accessor.
+    #
+    # Adds the following methods to the widget:
+    #
+    # <name>:: Returns the current text field value, or +nil+ if no value
+    #          has been set.
+    # <name>=:: Sets the current text field value.
+    #
+    # @example
+    #   # Given the following HTML:
+    #   #
+    #   # <form>
+    #   #   <p>
+    #   #     <label for="text-field">
+    #   #     <input type="text" value="Content" id="text-field">
+    #   #   </p>
+    #   #   <p>
+    #   #     <label for="empty-field">
+    #   #     <input type="text" id="empty-field">
+    #   #   </p>
+    #   # </form>
+    #   class MyFieldGroup < Dill::FieldGroup
+    #     root 'form'
+    #
+    #     text_field :filled_field, 'text-field'
+    #     text_field :empty_field, 'empty-field'
+    #   end
+    #
+    #   form = widget(:my_field_group)
+    #
+    #   form.filled_field                #=> "Content"
+    #   form.empty_field                 #=> nil
+    #
+    #   form.empty_field = "Not anymore"
+    #   form.empty_field                 #=> "Not anymore"
+    #
+    # @param name the name of the text field accessor.
+    # @param locator the locator for the text field. If +nil+ the locator
+    #   will be derived from +name+.
+    #
+    # @todo Handle text field access when the field is disabled (raise an
+    #   exception?)
+    def self.text_field(name, locator = nil)
+      field name, locator, TextField
+    end
+
+    # @!endgroup
+
+    # @return This field group's field widgets.
+    def fields
+      self.class.field_names.map { |name| widget(name) }
+    end
+
+    # Sets the given form attributes.
+    #
+    # @param attributes [Hash] the attributes and values we want to set.
+    #
+    # @return the current widget.
+    def set(attributes)
+      attributes.each do |k, v|
+        send "#{k}=", v
+      end
+
+      self
+    end
+
+    # Converts the current field group into a table suitable for diff'ing
+    # with Cucumber::Ast::Table.
+    #
+    # Field labels are determined by the widget name.
+    #
+    # Field values correspond to the return value of each field's +to_s+.
+    #
+    # @return [Array<Array>] the table.
+    def to_table
+      headers = fields.map { |field| field.label.downcase }
+      body    = fields.map { |field| field.to_s.downcase }
+
+      [headers, body]
+    end
+
+    # A form field.
+    class Field < Widget
+      def self.find_in(parent, options)
+        new({root: parent.find_field(selector)}.merge(options))
+      end
+
+      def self.present_in?(parent)
+        parent.has_field?(selector)
+      end
+
+      # @return This field's value.
+      #
+      # Override this to get the actual value.
+      def get
+        raise NotImplementedError
+      end
+
+      # Sets the field value.
+      #
+      # Override this to set the value.
+      def set(value)
+        raise NotImplementedError
+      end
+    end
+
+    # A check box.
+    class CheckBox < Field
+      # @!method set(value)
+      #   Checks or unchecks the current checkbox.
+      #
+      #   @param value [Boolean] +true+ to check the checkbox, +false+
+      #     otherwise.
+      def_delegator :root, :set
+
+      # @return [Boolean] +true+ if the checkbox is checked, +false+
+      #   otherwise.
+      def get
+        !! root.checked?
+      end
+
+      # @return +"yes"+ if the checkbox is checked, +"no"+ otherwise.
+      def to_s
+        get ? 'yes' : 'no'
+      end
+    end
+
+    # 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.
+      #
+      # @param option [String] The text of the option to select.
+      def set(option)
+        root.find('option', text: 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
+    end
+
+    # 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
+    end
+  end
+end

data/lib/dill/form.rb

@@ -0,0 +1,15 @@
+module Dill
+  class Form < FieldGroup
+    action :submit, '[type = submit]'
+
+    # Submit form with +attributes+.
+    #
+    # @param attributes [Hash] the form fields and their values
+    #
+    # @return the current widget
+    def submit_with(attributes)
+      set attributes
+      submit
+    end
+  end
+end

data/lib/dill/instance_conversions.rb

@@ -0,0 +1,19 @@
+module Dill
+  module InstanceConversions
+    def self.included(base)
+      base.send :include, Dill::Conversions
+    end
+
+    def to_boolean
+      Boolean(self)
+    end
+
+    def to_a
+      List(self)
+    end
+
+    def to_time
+      Timeish(self)
+    end
+  end
+end

data/lib/dill/list.rb

@@ -0,0 +1,47 @@
+module Dill
+  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
+      end
+
+      if block_given?
+        define_method :item_for, &item_for
+      else
+        define_method :item_factory do
+          type
+        end
+      end
+    end
+
+    def to_table
+      items.map { |e| Array(e) }
+    end
+
+    protected
+
+    attr_writer :item_selector
+
+    def item_factory
+      DEFAULT_TYPE
+    end
+
+    def item_for(node)
+      item_factory.new(root: node)
+    end
+
+    def item_selector
+      'li'
+    end
+
+    def items
+      root.all(item_selector).map { |node| item_for(node) }
+    end
+  end
+end

data/lib/dill/node_text.rb

@@ -0,0 +1,9 @@
+module Dill
+  class NodeText < String
+    include InstanceConversions
+
+    def initialize(node)
+      super node.text.strip
+    end
+  end
+end

data/lib/dill/table.rb

@@ -0,0 +1,66 @@
+module Dill
+  class Table < BaseTable
+    class ColumnDefinition
+      attr_reader :header
+
+      def initialize(selector, header, transform)
+        self.selector  = selector
+        self.header    = header
+        self.transform = transform
+      end
+
+      def ensure_loaded(container)
+        container.find(selector)
+      rescue Capybara::Ambiguous
+      end
+
+      def values(container)
+        container.all(selector).map { |n| transform.(node_text(n)).to_s }
+      end
+
+      private
+
+      attr_accessor :selector
+      attr_writer :header, :transform
+
+      def node_text(node)
+        NodeText.new(node)
+      end
+
+      def transform
+        @transform ||= ->(v) { v }
+      end
+    end
+
+    class << self
+      attr_accessor :column_selector, :header_selector
+    end
+
+    def self.column(selector, header = nil, &transform)
+      column_definitions << ColumnDefinition.new(selector, header, transform)
+    end
+
+    def self.column_definitions
+      @column_definitions ||= []
+    end
+
+    protected
+
+    def ensure_table_loaded
+      column_definitions.first.ensure_loaded(self)
+    end
+
+    private
+
+    def_delegators 'self.class', :column_selector, :column_definitions,
+                                 :header_selector
+
+    def headers
+      @headers ||= column_definitions.map(&:header)
+    end
+
+    def values
+      @values ||= column_definitions.map { |d| d.values(root) }.transpose
+    end
+  end
+end

data/lib/dill/text_table.rb

@@ -0,0 +1,107 @@
+module Dill
+  class TextTable
+    extend Forwardable
+
+    include Enumerable
+    include Conversions
+
+    class << self
+      def Array(table)
+        new(table).to_a
+      end
+
+      def Hash(table)
+        new(table).to_h
+      end
+
+      def map(name, options = {}, &block)
+        case name
+        when :*
+          set_default_mapping options, &block
+        else
+          set_mapping name, options, &block
+        end
+      end
+
+      def mappings
+        @mappings ||= Hash.
+         new { |h, k| h[k] = Mapping.new }.
+         merge(with_parent_mappings)
+      end
+
+      def skip(name)
+        case name
+        when :*
+          set_default_mapping VoidMapping
+        else
+          raise ArgumentError, "can't convert #{name.inspect} to name"
+        end
+      end
+
+      private
+
+      def set_default_mapping(options, &block)
+        case options
+        when Hash
+          @mappings = Hash.
+           new { |h, k|
+            h[k] = Mapping.new(key_transformer:   options[:to],
+                               value_transformer: block) }.
+           merge(mappings)
+        when Class
+          @mappings = Hash.new { |h, k| h[k] = options.new }.merge(mappings)
+        else
+          raise ArgumentError, "can't convert #{options.inspect} to mapping"
+        end
+      end
+
+      def set_mapping(name, options, &block)
+        mappings[name] = Mapping.
+         new(key: options[:to], value_transformer: block)
+      end
+
+      def with_parent_mappings
+        if superclass.respond_to?(:mappings)
+          superclass.send(:mappings).dup
+        else
+          {}
+        end
+      end
+    end
+
+    def_delegators 'self.class', :mappings
+
+    def initialize(table)
+      self.table = table
+    end
+
+    def each(&block)
+      rows.each(&block)
+    end
+
+    def rows
+      @rows ||= table.hashes.map { |h| new_row(h) }
+    end
+
+    def single_row
+      @single_row ||= new_row(table.rows_hash)
+    end
+
+    alias_method :to_a, :rows
+    alias_method :to_h, :single_row
+
+    private
+
+    attr_accessor :table
+
+    def new_row(hash)
+      hash.each_with_object({}) { |(k, v), h|
+        mapping_for(k).set(self, h, k, CellText.new(v))
+      }
+    end
+
+    def mapping_for(header)
+      mappings[header]
+    end
+  end
+end

data/lib/dill/text_table/cell_text.rb

@@ -0,0 +1,7 @@
+module Dill
+  class TextTable
+    class CellText < String
+      include InstanceConversions
+    end
+  end
+end

data/lib/dill/text_table/mapping.rb

@@ -0,0 +1,40 @@
+module Dill
+  class TextTable
+    class Mapping
+      def initialize(settings = {})
+        self.key               = settings[:key]
+        self.value_transformer = transformer(settings[:value_transformer], :pass)
+        self.key_transformer   = transformer(settings[:key_transformer], :keyword)
+      end
+
+      def set(instance, row, key, value)
+        row[transform_key(instance, key)] = transform_value(instance, value)
+      end
+
+      private
+
+      attr_accessor :key, :value_transformer, :key_transformer
+
+      def transform_key(_, k)
+        key || key_transformer.(k)
+      end
+
+      def transform_value(instance, value)
+        instance.instance_exec(value, &value_transformer)
+      end
+
+      def transformer(set, fallback)
+        case set
+        when Symbol
+          Transformations.send(set)
+        when Proc
+          set
+        when nil
+          Transformations.send(fallback)
+        else
+          raise ArgumentError, "can't convert #{set.inspect} to transformer"
+        end
+      end
+    end
+  end
+end

data/lib/dill/text_table/transformations.rb

@@ -0,0 +1,13 @@
+module Dill
+  class TextTable
+    module Transformations
+      def self.keyword
+        ->(val) { val.squeeze(' ').strip.gsub(' ', '_').sub(/\?$/, '').to_sym }
+      end
+
+      def self.pass
+        ->(val) { val }
+      end
+    end
+  end
+end

data/lib/dill/text_table/void_mapping.rb

@@ -0,0 +1,8 @@
+module Dill
+  class TextTable
+    class VoidMapping
+      def set(*)
+      end
+    end
+  end
+end

data/lib/dill/version.rb

@@ -0,0 +1,3 @@
+module Dill
+  VERSION = "0.4.0"
+end

data/lib/dill/widget.rb

@@ -0,0 +1,212 @@
+module Dill
+  class Widget
+    extend Forwardable
+
+    include WidgetContainer
+
+    # @!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+.
+      #
+      # @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
+      #
+      #   # Click the link
+      #   widget(: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
+
+        define_method name do
+          widget(name).click
+
+          self
+        end
+      end
+
+      # Declares a new sub-widget.
+      #
+      # Sub-widgets are accessible inside the container widget using the
+      # +widget+ message.
+      #
+      # @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
+      #
+      # @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
+        }
+
+        type.class_eval(&block) if block_given?
+
+        const_set(Dill::WidgetName.new(name).to_sym, type)
+      end
+
+      # Creates a delegator for one sub-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 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
+
+    # 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
+    #
+    # @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)))
+    end
+
+    # Sets this widget's default selector.
+    #
+    # @param selector [String] a CSS or XPath query
+    def self.root(selector)
+      @selector = selector
+    end
+
+    # @return The selector specified with +root+.
+    def self.selector
+      @selector
+    end
+
+    # @return The root node of the current widget
+    attr_reader :root
+
+    def_delegators :root, :click
+
+    def initialize(settings = {})
+      self.root = settings.fetch(:root)
+    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)
+    end
+
+    def inspect
+      xml = Nokogiri::HTML(page.body).at(root.path).to_xml
+
+      "<!-- #{self.class.name}: -->\n" <<
+       Nokogiri::XML(xml, &:noblanks).to_xhtml
+    end
+
+    class Reload < Capybara::ElementNotFound; end
+
+    # Reloads the widget, waiting for its contents to change (by default),
+    # or until +wait_time+ expires.
+    #
+    # Call this method to make sure a widget has enough time to update
+    # itself.
+    #
+    # You can pass a block to this method to control what it means for the
+    # widget to be reloaded.
+    #
+    # *Note: does not account for multiple changes to the widget yet.*
+    #
+    # @param wait_time [Numeric] how long we should wait for changes, in
+    #   seconds.
+    #
+    # @yield A block that determines what it means for a widget to be
+    #   reloaded.
+    # @yieldreturn [Boolean] +true+ if the widget is considered to be
+    #   reloaded, +false+ otherwise.
+    #
+    # @return the current widget
+    def reload(wait_time = Capybara.default_wait_time, &test)
+      unless test
+        old_inspect = inspect
+        test        = ->{ old_inspect != inspect }
+      end
+
+      root.synchronize(wait_time) do
+        raise Reload unless test.()
+      end
+
+      self
+    rescue Reload
+      # raised on timeout
+
+      self
+    end
+
+    def to_s
+      node_text(root)
+    end
+
+    alias_method :w, :widget
+
+    protected
+
+    def node_text(node)
+      NodeText.new(node)
+    end
+
+    private
+
+    attr_writer :root
+
+    def page
+      Capybara.current_session
+    end
+  end
+end

data/lib/dill/widget_container.rb

@@ -0,0 +1,23 @@
+module Dill
+  module WidgetContainer
+    def has_widget?(name)
+      widget_class(name).present_in?(root)
+    end
+
+    def widget(name, options = {})
+      widget_class(name).find_in(root, options)
+    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

data/lib/dill/widget_name.rb

@@ -0,0 +1,56 @@
+module Dill
+  # The name of a widget in a format-independent representation.
+  class WidgetName < String
+    CAMEL_CASE_FORMAT = /\A([A-Z][a-z]*)+\Z/
+    SNAKE_CASE_FORMAT = /\A\w+\Z/
+
+    # Constructs the widget name.
+    #
+    # @param name [String, Symbol] the name of the widget in primitive form
+    def initialize(name)
+      @name      = name
+      @canonical = canonical(@name)
+    end
+
+    # Returns the class for this widget name, in the given scope.
+    def to_class(scope = Object)
+      const = scope.const_get(@canonical)
+
+      raise TypeError, "`#{@canonical}' is not a widget in this scope" \
+        unless const < Widget
+
+      const
+    rescue NameError
+      raise Missing, "couldn't find `#{@name}' widget in this scope"
+    end
+
+    def to_sym
+      @canonical.to_sym
+    end
+
+    private
+
+    def canonical(name)
+      str = name.to_s
+
+      case str
+      when SNAKE_CASE_FORMAT
+        camel_case_from_snake_case(str)
+      when CAMEL_CASE_FORMAT
+        str
+      else
+        raise ArgumentError, "can't convert `#{str.inspect}' to canonical form"
+      end
+    end
+
+    def camel_case_from_snake_case(name)
+      capitalize_word = ->(word) { word[0].upcase + word[1..-1] }
+      word_separator  = '_'
+
+      name
+        .split(word_separator)
+        .map(&capitalize_word)
+        .join
+    end
+  end
+end

metadata

@@ -0,0 +1,165 @@
+--- !ruby/object:Gem::Specification
+name: dill
+version: !ruby/object:Gem::Version
+  prerelease: 
+  version: 0.4.0
+platform: ruby
+authors:
+- David Leal
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-30 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:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  name: chronic
+  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:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    none: false
+  name: capybara
+  type: :runtime
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+    none: false
+  name: rspec-given
+  type: :development
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+    none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  name: sinatra
+  type: :development
+  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:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    none: false
+  name: capybara-webkit
+  type: :development
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+    none: false
+description: See https://github.com/mojotech/dill/README.md
+email:
+- dleal@mojotech.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/dill.rb
+- lib/dill/auto_table.rb
+- lib/dill/base_table.rb
+- lib/dill/conversions.rb
+- lib/dill/cucumber.rb
+- lib/dill/document.rb
+- lib/dill/dsl.rb
+- lib/dill/field_group.rb
+- lib/dill/form.rb
+- lib/dill/instance_conversions.rb
+- lib/dill/list.rb
+- lib/dill/node_text.rb
+- lib/dill/table.rb
+- lib/dill/text_table.rb
+- lib/dill/text_table/cell_text.rb
+- lib/dill/text_table/mapping.rb
+- lib/dill/text_table/transformations.rb
+- lib/dill/text_table/void_mapping.rb
+- lib/dill/version.rb
+- lib/dill/widget.rb
+- lib/dill/widget_container.rb
+- lib/dill/widget_name.rb
+homepage: https://github.com/mojotech/dill
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project: ! '[none]'
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A set of helpers to ease integration testing
+test_files: []
+has_rdoc: