cucumber-salad 0.3.1 → 0.4.0

data/lib/cucumber/salad.rb

@@ -1,4 +1,6 @@
 require 'chronic'
+require 'nokogiri'
+require 'capybara'
 
 require 'cucumber/salad/widget_container'
 require 'cucumber/salad/widget_macros'
@@ -15,4 +17,9 @@ require 'cucumber/salad/table/cell_text'
 require 'cucumber/salad/widgets/document'
 require 'cucumber/salad/dsl'
 
-class UnknownWidgetError < StandardError; end
+module Cucumber
+  module Salad
+    # An exception that signals that something is missing.
+    class Missing < StandardError; end
+  end
+end

data/lib/cucumber/salad/version.rb

@@ -1,5 +1,5 @@
 module Cucumber
   module Salad
-    VERSION = "0.3.1"
+    VERSION = "0.4.0"
   end
 end

data/lib/cucumber/salad/widget_container.rb

@@ -2,7 +2,7 @@ module Cucumber
   module Salad
     module WidgetContainer
       def has_widget?(name)
-        widget_class(name).has_instance?(root)
+        widget_class(name).present_in?(root)
       end
 
       def widget(name, options = {})

data/lib/cucumber/salad/widget_name.rb

@@ -22,8 +22,7 @@ module Cucumber
 
         const
       rescue NameError
-        raise UnknownWidgetError,
-              "couldn't find `#{@name}' widget in this scope"
+        raise Missing, "couldn't find `#{@name}' widget in this scope"
       end
 
       def to_sym

data/lib/cucumber/salad/widgets.rb

@@ -3,4 +3,5 @@ require 'cucumber/salad/widgets/list'
 require 'cucumber/salad/widgets/base_table'
 require 'cucumber/salad/widgets/auto_table'
 require 'cucumber/salad/widgets/table'
+require 'cucumber/salad/widgets/field_group'
 require 'cucumber/salad/widgets/form'

data/lib/cucumber/salad/widgets/field_group.rb

@@ -0,0 +1,342 @@
+module Cucumber
+  module Salad
+    module Widgets
+      # 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 < Cucumber::Salad::Widgets::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 || name_to_locator(name), 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
+
+          widget name, locator, type do
+            define_method :label do
+              name.to_s.gsub(/_/, ' ').capitalize
+            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 < Cucumber::Salad::Widgets::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 || name_to_locator(name), 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 < Cucumber::Salad::Widgets::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 || name_to_locator(name), 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
+
+        private
+
+        def label(name)
+          name.to_s.humanize
+        end
+
+        def name_to_locator(name)
+          label(name)
+        end
+      end
+    end
+  end
+end

data/lib/cucumber/salad/widgets/form.rb

@@ -1,79 +1,18 @@
 module Cucumber
   module Salad
     module Widgets
-      class Form < Widget
-        def self.default_locator(type = nil, &block)
-          alias_method :name_to_locator, type if type
-
-          define_method :name_to_locator, &block if block
-        end
-
-        def self.check_box(name, label = nil)
-          define_method "#{name}=" do |val|
-            l = label || name_to_locator(name)
-
-            if val
-              root.check l
-            else
-              root.uncheck l
-            end
-          end
-        end
-
-        def self.select(name, *args)
-          opts   = args.extract_options!
-          label, = args
-
-          define_method "#{name}=" do |val|
-            l = label || name_to_locator(name)
-            w = opts.fetch(:writer) { ->(v) { v } }
-
-            root.select w.(val).to_s, from: l
-          end
-        end
-
-        def self.text_field(name, label = nil)
-          define_method "#{name}=" do |val|
-            l = label || name_to_locator(name)
-
-            root.fill_in l, with: val.to_s
-          end
-        end
-
+      class Form < FieldGroup
         action :submit, '[type = submit]'
 
-        # 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
-
         # Submit form with +attributes+.
         #
-        # @param attrs [Hash] the form fields and their values
+        # @param attributes [Hash] the form fields and their values
         #
         # @return the current widget
         def submit_with(attributes)
           set attributes
           submit
         end
-
-        private
-
-        def label(name)
-          name.to_s.humanize
-        end
-
-        def name_to_locator(name)
-          label(name)
-        end
       end
     end
   end

data/lib/cucumber/salad/widgets/widget.rb

@@ -7,7 +7,13 @@ module Cucumber
 
         include WidgetContainer
 
-        def self.has_instance?(parent_node)
+        # 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
 
@@ -43,6 +49,20 @@ module Cucumber
           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
 
@@ -50,6 +70,45 @@ module Cucumber
            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

metadata

@@ -2,14 +2,14 @@
 name: cucumber-salad
 version: !ruby/object:Gem::Version
   prerelease: 
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - David Leal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-21 00:00:00.000000000 Z
+date: 2013-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
@@ -62,18 +62,18 @@ dependencies:
 - !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 2.11.0
+        version: 3.0.0
     none: false
-  name: rspec
+  name: rspec-given
   type: :development
   prerelease: false
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 2.11.0
+        version: 3.0.0
     none: false
 - !ruby/object:Gem::Dependency
   version_requirements: !ruby/object:Gem::Requirement
@@ -91,6 +91,22 @@ dependencies:
       - !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/cucumber-salad/README.md
 email:
 - dleal@mojotech.com
@@ -117,12 +133,14 @@ files:
 - lib/cucumber/salad/widgets/auto_table.rb
 - lib/cucumber/salad/widgets/base_table.rb
 - lib/cucumber/salad/widgets/document.rb
+- lib/cucumber/salad/widgets/field_group.rb
 - lib/cucumber/salad/widgets/form.rb
 - lib/cucumber/salad/widgets/list.rb
 - lib/cucumber/salad/widgets/table.rb
 - lib/cucumber/salad/widgets/widget.rb
 homepage: https://github.com/mojotech/cucumber-salad
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths: