kelp 0.1.9 → 0.2.0

data/features/step_definitions/app_steps.rb

@@ -24,14 +24,30 @@ When /^I run cucumber on "(.+)"$/ do |feature|
 end
 
 
-Then /^the results should include:$/ do |expected_results|
-  # Remove leading whitespace before comparison
-  got = @output.gsub(/^\s*/, '')
-  want = expected_results.gsub(/^\s*/, '')
-  if !got.include?(want)
-    got = @output.collect {|line| "  #{line}"}.join
-    want = expected_results.collect {|line| "  #{line}"}.join
-    raise("Expected:\n#{want}\nGot:\n#{got}")
+# Ensure that the results include the expected lines, in the same order.
+# Extra lines in the results are ignored.
+Then /^the results should include:$/ do |expected_lines|
+  # Full actual output, for error reporting
+  got = @output.collect {|line| "  #{line}"}.join
+  # Remove leading whitespace and split into lines
+  got_lines = @output.gsub(/^\s*/, '').split("\n")
+  want_lines = expected_lines.gsub(/^\s*/, '').split("\n")
+  last_index = -1
+  # Ensure that each wanted line is present in the output,
+  # and that it comes after any preceding expected lines.
+  want_lines.each do |want|
+    if !want.empty?
+      index = got_lines.index(want)
+      # Not found?
+      if index.nil?
+        raise("Got:\n#{got}\nExpected line not found:\n  #{want}")
+      # Not in order?
+      elsif index < last_index
+        raise("Got:\n#{got}\nExpected line found, but out of order:\n  #{want}")
+      else
+        last_index = index
+      end
+    end
   end
 end
 

data/kelp.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "kelp"
-  s.version = "0.1.9"
+  s.version = "0.2.0"
   s.summary = "Cucumber helper methods"
   s.description = <<-EOS
     Kelp is a collection of helper methods for Cucumber to ease the process of

data/lib/kelp.rb

@@ -7,20 +7,5 @@ require 'kelp/scoping'
 require 'kelp/visibility'
 
 module Kelp
-  class << self
-    attr_writer :driver
-
-    # @return [Symbol]
-    #   Name of the default driver used by Kelp
-    def default_driver
-      :capybara
-    end
-
-    # @return [Symbol]
-    #   Name of the current driver used by Kelp (:capybara or :webrat)
-    def driver
-      @driver || default_driver
-    end
-  end
 end
 

data/lib/kelp/attribute.rb

@@ -9,9 +9,20 @@ module Kelp
     # @param [String] element_id
     #   HTML `id` attribute of the element that should be disabled
     #
+    # @raise [Kelp::Unexpected]
+    #   If the given element id is not found, or the element is not disabled
+    #
     def should_be_disabled(element_id)
-      page.should have_xpath("//*[@id='#{element_id}']")
-      page.should have_xpath("//*[@id='#{element_id}' and @disabled]")
+      if page.has_xpath?("//*[@id='#{element_id}']")
+        if !page.has_xpath?("//*[@id='#{element_id}' and @disabled]")
+          raise Kelp::Unexpected,
+            "Expected element with id='#{element_id}' to be disabled," + \
+            " but the 'disabled' attribute is not present."
+        end
+      else
+        raise Kelp::Unexpected,
+          "Element with id='#{element_id}' not found."
+      end
     end
 
 
@@ -21,9 +32,20 @@ module Kelp
     # @param [String] element_id
     #   HTML `id` attribute of the element that should be enabled
     #
+    # @raise [Kelp::Unexpected]
+    #   If the given element id is not found, or the element is not enabled
+    #
     def should_be_enabled(element_id)
-      page.should have_xpath("//*[@id='#{element_id}']")
-      page.should have_no_xpath("//*[@id='#{element_id}' and @disabled]")
+      if page.has_xpath?("//*[@id='#{element_id}']")
+        if page.has_xpath?("//*[@id='#{element_id}' and @disabled]")
+          raise Kelp::Unexpected,
+            "Expected element with id='#{element_id}' to be enabled," + \
+            " but the 'disabled' attribute is present."
+        end
+      else
+        raise Kelp::Unexpected,
+          "Element with id='#{element_id}' not found."
+      end
     end
 
   end

data/lib/kelp/checkbox.rb

@@ -1,29 +1,54 @@
 require 'kelp/helper'
 require 'kelp/scoping'
+require 'kelp/exceptions'
 
 module Kelp
   module Checkbox
     include Scoping
     include Helper
 
+    # Verify that the given checkbox is checked.
+    #
+    # @param [String] checkbox
+    #   Capybara locator for the checkbox
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    # @raise [Kelp::Unexpected]
+    #   If the given checkbox is not checked
+    #
+    # @since 0.1.2
+    #
     def checkbox_should_be_checked(checkbox, scope={})
       in_scope(scope) do
         field_checked = find_field(checkbox)['checked']
-        if field_checked.respond_to? :should
-          field_checked.should be_true
-        else
-          assert field_checked
+        puts field_checked.inspect
+        if !field_checked
+          raise Kelp::Unexpected,
+            "Expected '#{checkbox}' to be checked, but it is unchecked."
         end
       end
     end
 
+
+    # Verify that the given checkbox is not checked.
+    #
+    # @param [String] checkbox
+    #   Capybara locator for the checkbox
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    # @raise [Kelp::Unexpected]
+    #   If the given checkbox is checked
+    #
+    # @since 0.1.2
+    #
     def checkbox_should_not_be_checked(checkbox, scope={})
       in_scope(scope) do
         field_checked = find_field(checkbox)['checked']
-        if field_checked.respond_to? :should
-          field_checked.should be_false
-        else
-          assert !field_checked
+        if field_checked
+          raise Kelp::Unexpected,
+            "Expected '#{checkbox}' to be unchecked, but it is checked."
         end
       end
     end

data/lib/kelp/dropdown.rb

@@ -22,6 +22,9 @@ module Kelp
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
+    # @raise [Kelp::Unexpected]
+    #   If the given dropdown does not equal `value`
+    #
     def dropdown_should_equal(dropdown, value, scope={})
       in_scope(scope) do
         field = nice_find_field(dropdown)
@@ -37,7 +40,10 @@ module Kelp
           field_value = xpath_sanitize(field.value)
           selected = field.find(:xpath, ".//option[@value=#{field_value}]")
         end
-        selected.text.should =~ /#{value}/
+        if selected.text != value
+          raise Kelp::Unexpected,
+            "Expected '#{dropdown}' dropdown to equal '#{value}'\nGot '#{selected.text}' instead"
+        end
       end
     end
 
@@ -57,15 +63,22 @@ module Kelp
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
+    # @raise [Kelp::Unexpected]
+    #   If the given dropdown does not include all `values`
+    #
     def dropdown_should_include(dropdown, values, scope={})
       in_scope(scope) do
         # If values is a String, convert it to an Array
         values = [values] if values.class == String
-
         field = nice_find_field(dropdown)
-        # Look for each value
-        values.each do |value|
-          page.should have_xpath(".//option[text()=#{xpath_sanitize(value)}]")
+        # Select all expected values that don't appear in the dropdown
+        unexpected = values.select do |value|
+          !page.has_xpath?(".//option[text()=#{xpath_sanitize(value)}]")
+        end
+        if !unexpected.empty?
+          raise Kelp::Unexpected,
+            "Expected '#{dropdown}' dropdown to include: #{values.inspect}" + \
+            "\nMissing: #{unexpected.inspect}"
         end
       end
     end
@@ -82,17 +95,24 @@ module Kelp
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
+    # @raise [Kelp::Unexpected]
+    #   If the given dropdown includes any value in `values`
+    #
     # @since 0.1.2
     #
     def dropdown_should_not_include(dropdown, values, scope={})
       in_scope(scope) do
         # If values is a String, convert it to an Array
         values = [values] if values.class == String
-
         field = nice_find_field(dropdown)
-        # Look for each value
-        values.each do |value|
-          page.should have_no_xpath(".//option[text()=#{xpath_sanitize(value)}]")
+        # Select all not-expected values that do appear in the dropdown
+        unexpected = values.select do |value|
+          page.has_xpath?(".//option[text()=#{xpath_sanitize(value)}]")
+        end
+        if !unexpected.empty?
+          raise Kelp::Unexpected,
+            "Expected '#{dropdown}' dropdown to not include: #{values.inspect}" + \
+            "\nDid include: #{unexpected.inspect}"
         end
       end
     end
@@ -108,10 +128,16 @@ module Kelp
     # @param [String] value
     #   Expected `value` attribute of the selected `option`
     #
+    # @raise [Kelp::Unexpected]
+    #   If the given dropdown's 'value' attribute is not equal to `value`
+    #
     def dropdown_value_should_equal(dropdown, value)
-      # FIXME: When this returns False, does that fail the step?
       field = find_field(dropdown)
-      field.value.should include(value)
+      if field.value != value
+        raise Kelp::Unexpected,
+          "Expected '#{dropdown}' dropdown's value to equal '#{value}'" + \
+          "\nGot '#{field.value}' instead"
+      end
     end
 
   end

data/lib/kelp/exceptions.rb

@@ -1,5 +1,7 @@
 module Kelp
-  class Unexpected < RuntimeError
-  end
+  class KelpError < StandardError; end
+  class Unexpected < KelpError; end
+  class FieldNotFound < KelpError; end
+  class OptionNotFound < KelpError; end
 end
 

data/lib/kelp/field.rb

@@ -19,13 +19,35 @@ module Kelp
     # @param [String] value
     #   Text to select from a dropdown or enter in a text box
     #
+    # @raise [Kelp::FieldNotFound]
+    #   If no field matching `field` is found
+    # @raise [Kelp::OptionNotFound]
+    #   If a dropdown matching `field` is found, but it has no
+    #   option matching `value`
+    #
     # @since 0.1.9
     #
     def select_or_fill(field, value)
       begin
         select(value, :from => field)
-      rescue
-        fill_in(field, :with => value)
+      rescue Capybara::ElementNotFound => err
+        # The select method may raise ElementNotFound in two cases:
+        # (1) The given field does not exist, in which case try a text field
+        if err.message =~ /no select box with id, name, or label/
+          begin
+            fill_in(field, :with => value)
+          rescue Capybara::ElementNotFound
+            raise Kelp::FieldNotFound,
+              "No field with id, name, or label '#{field}' found"
+          end
+        # (2) The field exists, but the value does not
+        elsif err.message =~ /no option with text/
+          raise Kelp::OptionNotFound,
+            "Field '#{field}' has no option '#{value}'"
+        # And just in case...
+        else
+          raise
+        end
       end
     end
 
@@ -41,70 +63,77 @@ module Kelp
     #   Text to select from a dropdown or enter in a text box, or
     #   `checked` or `unchecked` to operate on a checkbox
     #
+    # @raise [Kelp::Nonexistent]
+    #   If no checkbox, dropdown, or text box is found with the given
+    #   identifier
+    #
     # @since 0.1.9
     #
     def check_or_select_or_fill(field, value)
       # If value is "checked" or "unchecked", assume
       # field is a checkbox
-      if value == "checked"
-        begin
+      begin
+        if value == "checked"
           check(field)
-        rescue
-          select_or_fill(field, value)
-        end
-      elsif value == "unchecked"
-        begin
+        elsif value == "unchecked"
           uncheck(field)
-        rescue
+        else
           select_or_fill(field, value)
         end
-      else
+      rescue Capybara::ElementNotFound
         select_or_fill(field, value)
       end
     end
 
 
-    # Fill in multiple fields according to values in a `Hash`.
-    # Fields may be text boxes, dropdowns/listboxes, or checkboxes.
+    # Fill in a single field within the scope of a given selector.
+    # The field may be a text box, dropdown/listbox, or checkbox.
     # See {#check_or_select_or_fill} for details.
     #
     # @example
-    #   fill_in_fields "First name" => "Otto", "Last name" => "Scratchansniff"
-    #   fill_in_fields "phone" => "303-224-7428", :within => "#home"
+    #   fill_in_field "Email", "otto@scratchansniff.wb"
+    #   fill_in_field "Send me junk email", "unchecked"
     #
-    # @param [Hash] field_values
-    #   "field" => "value" for each field to fill in, select, or check/uncheck
+    # @param [String] field
+    #   Capybara locator for the field (name, id, or label text)
+    # @param [String] value
+    #   Text to select from a dropdown or enter in a text box, or
+    #   `checked` or `unchecked` to operate on a checkbox
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
-    def fill_in_fields(field_values, scope={})
+    # @raise [Kelp::FieldNotFound]
+    #   If no field is found matching the given identifier
+    #
+    def fill_in_field(field, value, scope={})
       in_scope(scope) do
-        field_values.each do |field, value|
-          check_or_select_or_fill(field, value)
-        end
+        check_or_select_or_fill(field, value)
       end
     end
 
 
-    # Fill in a single field within the scope of a given selector.
-    # The field may be a text box, dropdown/listbox, or checkbox.
+    # Fill in multiple fields according to values in a `Hash`.
+    # Fields may be text boxes, dropdowns/listboxes, or checkboxes.
     # See {#check_or_select_or_fill} for details.
     #
     # @example
-    #   fill_in_field "Email", "otto@scratchansniff.wb"
-    #   fill_in_field "Send me junk email", "unchecked"
+    #   fill_in_fields "First name" => "Otto", "Last name" => "Scratchansniff"
+    #   fill_in_fields "phone" => "303-224-7428", :within => "#home"
     #
-    # @param [String] field
-    #   Capybara locator for the field (name, id, or label text)
-    # @param [String] value
-    #   Text to select from a dropdown or enter in a text box, or
-    #   `checked` or `unchecked` to operate on a checkbox
+    # @param [Hash] field_values
+    #   "field" => "value" for each field to fill in, select, or check/uncheck
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
-    def fill_in_field(field, value, scope={})
-      fields = {field => value}
-      fill_in_fields fields, scope
+    # @raise [Kelp::Nonexistent]
+    #   If any field could not be found
+    #
+    def fill_in_fields(field_values, scope={})
+      in_scope(scope) do
+        field_values.each do |field, value|
+          check_or_select_or_fill(field, value)
+        end
+      end
     end
 
 
@@ -135,11 +164,15 @@ module Kelp
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
+    # @raise [Kelp::Unexpected]
+    #   If the given field is not empty or nil
+    #
     def field_should_be_empty(field, scope={})
       in_scope(scope) do
         _field = nice_find_field(field)
         if !(_field.nil? || _field.value.nil? || _field.value == '')
-          raise RuntimeError, "Expected field '#{field}' to be empty, but value is '#{_field.value}'"
+          raise Kelp::Unexpected,
+            "Expected field '#{field}' to be empty, but value is '#{_field.value}'"
         end
       end
     end
@@ -154,12 +187,15 @@ module Kelp
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
+    # @raise [Kelp::Unexpected]
+    #   If the given field does not contain `value`
+    #
     def field_should_contain(field, value, scope={})
       in_scope(scope) do
         # TODO: Make this work equally well with any kind of field
         # (text, single-select, multi-select)
-        field = find_field(field)
-        field_value = (field.tag_name == 'textarea') ? field.text : field.value
+        element = find_field(field)
+        field_value = (element.tag_name == 'textarea') ? element.text : element.value
         # If field value is an Array, take the first item
         if field_value.class == Array
           field_value = field_value.first
@@ -167,17 +203,17 @@ module Kelp
         # Escape any problematic characters in the expected value
         value = Regexp.escape(value)
         # Match actual to expected
-        if field_value.respond_to? :should
-          field_value.should =~ /#{value}/
-        else
-          assert_match(/#{value}/, field_value)
+        if !(field_value =~ /#{value}/)
+          raise Kelp::Unexpected,
+            "Expected '#{field}' to contain '#{value}'" + \
+            "\nGot '#{field_value}'"
         end
       end
     end
 
 
     def field_should_not_contain(field, value, scope={})
-      raise "Not implemented yet"
+      raise NotImplementedError, "Not implemented yet"
       #with_scope(parent) do
         #field = find_field(field)
         #field_value = (field.tag_name == 'textarea') ? field.text : field.value
@@ -197,6 +233,9 @@ module Kelp
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
+    # @raise [Kelp::Unexpected]
+    #   If any field does not contain the expected value
+    #
     def fields_should_contain(field_values, scope={})
       in_scope(scope) do
         field_values.each do |field, value|