kelp 0.1.8 → 0.1.9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kelp (0.1.8)
+    kelp (0.1.9)
       capybara (>= 0.4.0)
 
 GEM

data/History.md

@@ -1,6 +1,15 @@
 Kelp History
 ============
 
+0.1.9
+-----
+
+- Fill-in methods now accept checkbox and dropdown fields
+- Generated step definitions now replace those of cucumber-rails (web_steps.rb)
+- should_be_on_page and should_have_query methods added
+- should_see_button and should_not_see_button visibility methods added
+
+
 0.1.8
 -----
 

data/README.md

@@ -97,13 +97,20 @@ for more information.
 Rails generator
 ---------------
 
-Kelp provides a generator for Rails 2.x projects, to quickly add some generic
-step definitions. Simply run:
+Kelp provides a generator for Rails 2.x projects, which writes step definitions
+to `features/step_definitions/web_steps.rb`. This file provides all of the same
+step definitions normally provided by
+[cucumber-rails](http://github.com/aslakhellesoy/cucumber-rails), with several
+enhancements. If you have made customizations to your `web_steps.rb`, they will
+be overwritten! Consider yourself warned.
+
+To generate `web_steps.rb`, simply run:
 
     $ script/generate kelp
 
-This will create `features/step_definitions/kelp_steps.rb` with some example
-step definitions using Kelp's helper methods.
+*Note*: If you are upgrading from a version of Kelp prior to 0.1.9, you should
+remove `kelp_steps.rb` from your `features/step_definitions` directory; these
+are obsolete, and conflict with the newer step definitions in `web_steps.rb`.
 
 A Rails 3.x generator is not currently provided. Contributions are welcome!
 
@@ -142,7 +149,7 @@ Kelp comes with a `Rakefile`, so you can run the RSpec tests and generate an
     $ rake spec
 
 This will write an HTML report to `coverage/index.html`. Finally, there are
-some Cucumber self-tests included, mainly for testing the `kelp_steps.rb`
+some Cucumber self-tests included, mainly for testing the `web_steps.rb`
 file used by the Rails generator. Run via:
 
     $ rake cucumber

data/examples/sinatra_app/views/form.erb

@@ -33,14 +33,12 @@
           <option value="heavy">Heavy</option>
         </select>
       </p>
-      <p>
-        <label for="quotes">Quotes</label>
-        <select id="quotes">
-          <option value="1">Single 'quotes'</option>
-          <option value="2">"Double" quotes</option>
-          <option value="3">'Single' and "Double" quotes</option>
-        </select>
-      </p>
+      <p><button value="Submit person form" /></p>
+    </div>
+  </form>
+
+  <div id="preferences_form">
+    <form action="/thanks" method="get">
       <p>
         <label for="favorite_colors">Favorite Colors</label>
         <select id="favorite_colors" multiple="multiple">
@@ -57,23 +55,6 @@
         <label for="like_salami">I like salami</label>
         <input id="like_salami" type="checkbox" />
       </p>
-      <p>
-        <label for="message">Message</label>
-        <input id="message" type="text" value="Your message goes here" />
-      </p>
-      <p><input type="submit" value="Submit" /></p>
-    </form>
-  </div>
-
-  <div id="other_form">
-    <form action="/thanks" method="get">
-      <p><input id="readonly" type="text" disabled="disabled" /></p>
-      <p><input type="submit" value="Submit" disabled="disabled" /></p>
-    </form>
-  </div>
-
-  <div id="checkbox_form">
-    <form action="/thanks" method="get">
       <table>
         <tr>
           <th>Apple</th>
@@ -90,6 +71,26 @@
           </td>
         </tr>
       </table>
+      <p>
+        <label for="message">Message</label>
+        <input id="message" type="text" value="Your message goes here" />
+      </p>
+      <p><input type="submit" value="Save preferences" /></p>
+    </form>
+  </div>
+
+  <div id="other_form">
+    <form action="/thanks" method="get">
+      <p>
+        <label for="quotes">Quotes</label>
+        <select id="quotes">
+          <option value="1">Single 'quotes'</option>
+          <option value="2">"Double" quotes</option>
+          <option value="3">'Single' and "Double" quotes</option>
+        </select>
+      </p>
+      <p><input id="readonly" type="text" disabled="disabled" /></p>
+      <p><input type="submit" value="Save is disabled" disabled="disabled" /></p>
     </form>
   </div>
 

data/examples/sinatra_app/views/home.erb

@@ -20,7 +20,7 @@
   <div id="fields">
     <form action="/thanks" method="get">
       <input type="text" name="message" />
-      <input type="submit" value="Submit" />
+      <input type="submit" value="Submit message" />
     </form>
   </div>
 

data/features/step_definitions/app_steps.rb

@@ -4,9 +4,9 @@ require 'fileutils'
 
 Given /^the latest Kelp step definitions$/ do
   app_dir = File.join(root_dir, 'examples', "sinatra_app")
-  installed_steps = File.join(app_dir, 'features', 'step_definitions', 'kelp_steps.rb')
-  latest_steps = File.join(root_dir, 'rails_generators', 'kelp', 'templates', 'kelp_steps.rb')
-  # Remove the installed kelp_steps.rb, if any, then install the latest one
+  installed_steps = File.join(app_dir, 'features', 'step_definitions', 'web_steps.rb')
+  latest_steps = File.join(root_dir, 'rails_generators', 'kelp', 'templates', 'web_steps.rb')
+  # Remove the installed web_steps.rb, if any, then install the latest one
   FileUtils.mkdir_p(File.dirname(installed_steps))
   FileUtils.rm(installed_steps) if File.exists?(installed_steps)
   FileUtils.cp_r(latest_steps, installed_steps)

data/kelp.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "kelp"
-  s.version = "0.1.8"
+  s.version = "0.1.9"
   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/field.rb

@@ -9,27 +9,99 @@ module Kelp
     include Scoping
     include Helper
 
+    # Select a value from a dropdown or listbox, or fill in a text field,
+    # depending on what kind of form field is available. If `field` is a
+    # dropdown or listbox, select `value` from that; otherwise, assume
+    # `field` is a text box.
+    #
+    # @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
+    #
+    # @since 0.1.9
+    #
+    def select_or_fill(field, value)
+      begin
+        select(value, :from => field)
+      rescue
+        fill_in(field, :with => value)
+      end
+    end
+
+
+    # Check a checkbox, select from a dropdown or listbox, or fill in a text
+    # field, depending on what kind of form field is available. If value
+    # is `checked` or `unchecked`, assume `field` is a checkbox; otherwise,
+    # fall back on {#select_or_fill}.
+    #
+    # @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
+    #
+    # @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
+          check(field)
+        rescue
+          select_or_fill(field, value)
+        end
+      elsif value == "unchecked"
+        begin
+          uncheck(field)
+        rescue
+          select_or_fill(field, value)
+        end
+      else
+        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.
+    # 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"
     #
-    # @param [Hash] fields
-    #   "field" => "value" for each field to fill in
+    # @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_fields(fields, scope={})
+    def fill_in_fields(field_values, scope={})
       in_scope(scope) do
-        fields.each do |name, value|
-          fill_in name, :with => value
+        field_values.each do |field, value|
+          check_or_select_or_fill(field, value)
         end
       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.
+    # See {#check_or_select_or_fill} for details.
+    #
+    # @example
+    #   fill_in_field "Email", "otto@scratchansniff.wb"
+    #   fill_in_field "Send me junk email", "unchecked"
+    #
+    # @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_field(field, value, scope={})
       fields = {field => value}
       fill_in_fields fields, scope
@@ -57,6 +129,12 @@ module Kelp
 
 
     # Verify that the given field is empty or nil.
+    #
+    # @param [String] field
+    #   Capybara locator for the field (name, id, or label text)
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
     def field_should_be_empty(field, scope={})
       in_scope(scope) do
         _field = nice_find_field(field)
@@ -73,6 +151,8 @@ module Kelp
     #   Capybara locator for the field (name, id, or label text)
     # @param [String] value
     #   Value you expect to see in the text field
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
     #
     def field_should_contain(field, value, scope={})
       in_scope(scope) do

data/lib/kelp/helper.rb

@@ -1,5 +1,16 @@
 module Kelp
   module Helper
+    # Convert a Cucumber::Ast::Table or multiline string into
+    # a list of strings
+    def listify(items)
+      if items.class == Cucumber::Ast::Table
+        strings = items.raw.flatten
+      else
+        strings = items.split(/[\r\n]+/)
+      end
+    end
+
+
     # A slightly friendlier version of Capybara's `find_field`, which actually
     # tells you which locator failed to match (instead of giving a useless
     # Unable to find '#<XPath::Union:0xXXXXXXX>' message).
@@ -11,6 +22,7 @@ module Kelp
       end
     end
 
+
     # Return the appropriate "ExpectationNotMetError" class for the current
     # version of RSpec
     def rspec_unexpected
@@ -20,5 +32,6 @@ module Kelp
         Spec::Expectations::ExpectationNotMetError
       end
     end
+
   end
 end

data/lib/kelp/navigation.rb

@@ -1,13 +1,16 @@
+require 'uri'
+require 'cgi'
 require 'kelp/scoping'
 require 'kelp/xpath'
 
 module Kelp
   # This module defines helper methods for navigating a webpage, including
-  # clicking links and pressing buttons.
+  # clicking links and pressing buttons, and for verifying the current
+  # page's path and query parameters.
   #
   module Navigation
     include Scoping
-    include XPath
+    include XPaths
 
     # Follow a link on the page.
     #
@@ -59,5 +62,60 @@ module Kelp
       row.click_link(link)
     end
 
+
+    # Verify that the current page matches the path of `page_name_or_path`. The
+    # cucumber-generated `path_to` function will be used, if it's defined, to
+    # translate human-readable names into URL paths. Otherwise, assume a raw,
+    # absolute path string.
+    #
+    # @example
+    #   should_be_on_page 'home page'
+    #   should_be_on_page '/admin/login'
+    #
+    # @param [String] page_name_or_path
+    #   Human-readable page name (mapped to a pathname by your `path_to` function),
+    #   or an absolute path beginning with `/`.
+    #
+    # @since 0.1.9
+    #
+    def should_be_on_page(page_name_or_path)
+      # Use the path_to translator function if it's defined
+      # (normally in features/support/paths.rb)
+      if defined? path_to
+        expect_path = path_to(page_name_or_path)
+      # Otherwise, expect a raw path string
+      else
+        expect_path = page_name_or_path
+      end
+      actual_path = URI.parse(current_url).path
+      if actual_path.respond_to? :should
+        actual_path.should == expect_path
+      else
+        assert_equal actual_path, expect_path
+      end
+    end
+
+
+    # Verify that the current page has the given query parameters.
+    #
+    # @param [Hash] params
+    #   Key => value parameters, as they would appear in the URL
+    #
+    # @since 0.1.9
+    #
+    def should_have_query(params)
+      query = URI.parse(current_url).query
+      actual_params = query ? CGI.parse(query) : {}
+      expected_params = {}
+      params.each_pair do |k,v|
+        expected_params[k] = v.split(',')
+      end
+      if actual_params.respond_to? :should
+        actual_params.should == expected_params
+      else
+        assert_equal expected_params, actual_params
+      end
+    end
+
   end
 end

data/lib/kelp/scoping.rb

@@ -8,7 +8,8 @@ module Kelp
     # assumed to be a CSS selector.
     def scope_within(locator)
       if locator
-        # Use the selector_for method if it's defined
+        # Use the selector_for method if it's defined. This may be provided
+        # by features/support/selectors.rb, generated by cucumber-rails.
         if defined? selector_for
           within(*selector_for(locator)) { yield }
         # Otherwise, remove any surrounding double-quotes
@@ -32,7 +33,7 @@ module Kelp
     #
     # @example
     #    in_scope :within => '#footer'
-    #        click_link "Contact Us"
+    #      click_link "Contact Us"
     #    end
     #
     # @param [Hash] scope

data/lib/kelp/visibility.rb

@@ -1,3 +1,4 @@
+require 'xpath'
 require 'kelp/scoping'
 require 'kelp/xpath'
 require 'kelp/exceptions'
@@ -9,7 +10,7 @@ module Kelp
   #
   module Visibility
     include Scoping
-    include XPath
+    include XPaths
 
     # Verify the presence of content on the page. Passes when all the given items
     # are found on the page, and fails if any of them are not found.
@@ -25,6 +26,9 @@ module Kelp
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
+    # @raise [Kelp::Unexpected]
+    #   If any of the expected text strings are not seen in the given scope
+    #
     def should_see(texts, scope={})
       texts = [texts] if (texts.class == String || texts.class == Regexp)
       unexpected = []
@@ -52,6 +56,9 @@ module Kelp
     # @param [Hash] scope
     #   Scoping keywords as understood by {#in_scope}
     #
+    # @raise [Kelp::Unexpected]
+    #   If any of the expected text strings are seen in the given scope
+    #
     def should_not_see(texts, scope={})
       texts = [texts] if (texts.class == String || texts.class == Regexp)
       unexpected = []
@@ -248,6 +255,64 @@ module Kelp
       end
     end
 
+
+    # Verify that a button with the given text appears on the page.
+    # Works for `<input...>` as well as `<button...>` elements.
+    #
+    # @example
+    #   should_see_button "Submit"
+    #   should_see_button "Save changes", :within => "#preferences"
+    #
+    # @param [String] button_text
+    #   Visible button text to look for
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    # @raise [Kelp::Unexpected]
+    #   If no button with the given text exists in the given scope
+    #
+    # @since 0.1.9
+    #
+    def should_see_button(button_text, scope={})
+      in_scope(scope) do
+        xpath = XPath::HTML.button(button_text)
+        begin
+          page.should have_xpath(xpath)
+        rescue rspec_unexpected
+          raise Kelp::Unexpected, "Expected to see button '#{button_text}', but button does not exist."
+        end
+      end
+    end
+
+
+    # Verify that a button with the given text does not appear on the page.
+    # Works for `<input...>` as well as `<button...>` elements.
+    #
+    # @example
+    #   should_not_see_button "Delete"
+    #   should_not_see_button "Save changes", :within => "#read_only"
+    #
+    # @param [String] button_text
+    #   Visible button text to look for
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    # @raise [Kelp::Unexpected]
+    #   If a button with the given text does exist in the given scope
+    #
+    # @since 0.1.9
+    #
+    def should_not_see_button(button_text, scope={})
+      in_scope(scope) do
+        xpath = XPath::HTML.button(button_text)
+        begin
+          page.should have_no_xpath(xpath)
+        rescue rspec_unexpected
+          raise Kelp::Unexpected, "Did not expect to see button '#{button_text}', but button exists."
+        end
+      end
+    end
+
   end
 end
 

data/lib/kelp/xpath.rb

@@ -1,7 +1,7 @@
 module Kelp
   # This module defines helper methods for building XPath expressions.
   #
-  module XPath
+  module XPaths
     # Return an XPath for any table row containing all strings in `texts`,
     # within the current context.
     def xpath_row_containing(texts)

data/rails_generators/kelp/kelp_generator.rb

@@ -1,4 +1,5 @@
-# This generator adds Kelp steps to the step_definitions directory
+# This generator adds web_steps.rb to the step_definitions directory,
+# replacing any web_steps.rb added by cucumber-rails.
 
 generator_base = defined?(Rails) ? Rails::Generator::Base : RubiGen::Base
 
@@ -6,7 +7,7 @@ class KelpGenerator < generator_base
   def manifest
     record do |m|
       m.directory 'features/step_definitions'
-      m.file 'kelp_steps.rb', 'features/step_definitions/kelp_steps.rb'
+      m.file 'web_steps.rb', 'features/step_definitions/web_steps.rb'
     end
   end
 

data/rails_generators/kelp/templates/capybara_steps.rb

@@ -1,7 +1,6 @@
 
-require 'uri'
-require 'cgi'
-require File.expand_path(File.join(File.dirname(__FILE__), "..", "support", "paths"))
+# May not be needed?
+#require File.expand_path(File.join(File.dirname(__FILE__), "..", "support", "paths"))
 #require File.expand_path(File.join(File.dirname(__FILE__), "..", "support", "selectors"))
 
 # Single-line step scoper
@@ -14,119 +13,4 @@ When /^(.*) within ([^:]+):$/ do |step, parent, table_or_string|
   scope_within(parent) { When "#{step}:", table_or_string }
 end
 
-Given /^(?:|I )am on (.+)$/ do |page_name|
-  visit path_to(page_name)
-end
-
-When /^(?:|I )go to (.+)$/ do |page_name|
-  visit path_to(page_name)
-end
-
-When /^(?:|I )press "([^"]*)"$/ do |button|
-  click_button button
-end
-
-When /^(?:|I )follow "([^"]*)"$/ do |link|
-  click_link link
-end
-
-When /^(?:|I )fill in "([^"]*)" with "([^"]*)"$/ do |field, value|
-  fill_in field, :with => value
-end
-
-When /^(?:|I )fill in "([^"]*)" for "([^"]*)"$/ do |value, field|
-  fill_in field, :with => value
-end
-
-# Use this to fill in an entire form with data from a table. Example:
-#
-#   When I fill in the following:
-#     | Account Number | 5002       |
-#     | Expiry date    | 2009-11-01 |
-#     | Note           | Nice guy   |
-#     | Wants Email?   |            |
-#
-# TODO: Add support for checkbox, select og option
-# based on naming conventions.
-#
-When /^(?:|I )fill in the following:$/ do |fields|
-  fill_in_fields fields.rows_hash
-end
-
-When /^(?:|I )select "([^"]*)" from "([^"]*)"$/ do |value, field|
-  select value, :from => field
-end
-
-When /^(?:|I )check "([^"]*)"$/ do |field|
-  check field
-end
-
-When /^(?:|I )uncheck "([^"]*)"$/ do |field|
-  uncheck field
-end
-
-When /^(?:|I )choose "([^"]*)"$/ do |field|
-  choose field
-end
-
-When /^(?:|I )attach the file "([^"]*)" to "([^"]*)"$/ do |path, field|
-  attach_file field, File.expand_path(path)
-end
 
-Then /^(?:|I )should see "([^"]*)"$/ do |text|
-  should_see text
-end
-
-Then /^(?:|I )should see \/([^\/]*)\/$/ do |regexp|
-  should_see Regexp.new(regexp)
-end
-
-Then /^(?:|I )should not see "([^"]*)"$/ do |text|
-  should_not_see text
-end
-
-Then /^(?:|I )should not see \/([^\/]*)\/$/ do |regexp|
-  should_not_see Regexp.new(regexp)
-end
-
-Then /^the "([^"]*)" field(?: within (.*))? should contain "([^"]*)"$/ do |field, parent, value|
-  field_should_contain field, value, :within => parent
-end
-
-Then /^the "([^"]*)" field(?: within (.*))? should not contain "([^"]*)"$/ do |field, parent, value|
-  field_should_not_contain field, value, :within => parent
-end
-
-Then /^the "([^"]*)" checkbox(?: within (.*))? should be checked$/ do |label, parent|
-  checkbox_should_be_checked label, :within => parent
-end
-
-Then /^the "([^"]*)" checkbox(?: within (.*))? should not be checked$/ do |label, parent|
-  checkbox_should_not_be_checked label, :within => parent
-end
-
-Then /^(?:|I )should be on (.+)$/ do |page_name|
-  current_path = URI.parse(current_url).path
-  if current_path.respond_to? :should
-    current_path.should == path_to(page_name)
-  else
-    assert_equal path_to(page_name), current_path
-  end
-end
-
-Then /^(?:|I )should have the following query string:$/ do |expected_pairs|
-  query = URI.parse(current_url).query
-  actual_params = query ? CGI.parse(query) : {}
-  expected_params = {}
-  expected_pairs.rows_hash.each_pair{|k,v| expected_params[k] = v.split(',')}
-
-  if actual_params.respond_to? :should
-    actual_params.should == expected_params
-  else
-    assert_equal expected_params, actual_params
-  end
-end
-
-Then /^show me the page$/ do
-  save_and_open_page
-end