kelp 0.1.1

data/lib/kelp/capybara/form_helper.rb

@@ -0,0 +1,131 @@
+module FormHelper
+  # Fill in multiple fields according to values in a Hash.
+  # Scope may be defined per the #in_scope method.
+  def fill_in_fields(fields, scope={})
+    in_scope(scope) do
+      fields.each do |name, value|
+        fill_in name, :with => value
+      end
+    end
+  end
+
+  # Fill in multiple fields within the scope of a given selector.
+  # Syntactic sugar for #fill_in_fields.
+  def fill_in_fields_within(selector, fields)
+    fill_in_fields fields, :within => selector
+  end
+
+  # Verify that the given field is empty or nil.
+  def field_should_be_empty(field)
+    _field = nice_find_field(field)
+    if _field.nil? || _field.value.nil?
+      return true
+    else
+      raise "Expected field '#{field}' to be empty, but it has a value '#{_field.value}'"
+    end
+  end
+
+  # Verify that the selected option in a dropdown has the given
+  # value. Note that this is the *visible* content of the dropdown
+  # (the content of the <option> element), rather than the
+  # 'value' attribute of the option.
+  def dropdown_should_equal(dropdown, value)
+    field = nice_find_field(dropdown)
+    # See if there's a 'selected' option
+    begin
+      selected = field.find(:xpath, ".//option[@selected='selected']")
+    # If not, find the option matching the first field value
+    rescue Capybara::ElementNotFound
+      selected = field.find(:xpath, ".//option[@value='#{field.value.first}']")
+    end
+    selected.text.should =~ /#{value}/
+  end
+
+  # Verify that a given dropdown includes all of the given values. Search
+  # first by the 'value' attribute, then by the content of each option; if
+  # values are not found in either place, an error occurs.
+  # Scope may be defined per the #in_scope method.
+  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|
+        begin
+          option = field.find(:xpath, ".//option[@value='#{value}']")
+        rescue Capybara::ElementNotFound
+          option = field.find(:xpath, ".//option[contains(., '#{value}')]")
+        end
+      end
+    end
+  end
+
+  # Verify that the given <select> element has a given value selected. Works
+  # with single- or multi-select elements. This verifies the 'value' attribute
+  # of the selected option, rather than its visible content.
+  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)
+  end
+
+  # Verify that the given field contains the given value.
+  def field_should_contain(field, value)
+    field = find_field(field)
+    field_value = (field.tag_name == 'textarea') ? field.text : field.value
+    # If field value is an Array, take the first item
+    if field_value.class == Array
+      field_value = field_value.first
+    end
+    # 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)
+    end
+  end
+
+  # Verify the values of multiple fields given as a Hash.
+  # Scope may be defined per the #in_scope method.
+  def fields_should_contain(field_values, scope={})
+    in_scope(scope) do
+      field_values.each do |field, value|
+        _field = find_field(field)
+        # For nil/empty, check for nil field or nil value
+        if value.nil? or value.empty?
+          field_should_be_empty(field)
+        # If field is a dropdown
+        elsif _field.tag_name == 'select'
+          dropdown_should_equal(field, value)
+        # Otherwise treat as a text field
+        else
+          field_should_contain(field, value)
+        end
+      end
+    end
+  end
+
+  # Verify fields within the scope of a given selector.
+  # Syntactic sugar for #fields_should_contain.
+  def fields_should_contain_within(selector, field_values)
+    fields_should_contain field_values, :within => selector
+  end
+
+  private
+
+  # 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).
+  def nice_find_field(locator)
+    begin
+      field = find_field(locator)
+    rescue Capybara::ElementNotFound
+      raise "Could not find field with locator: '#{locator}'"
+    end
+  end
+end
+

data/lib/kelp/capybara/web_helper.rb

@@ -0,0 +1,148 @@
+
+module WebHelper
+  # Execute a block of code within a given scope.
+  # +locator+ may be in css or xpath form, depending on what type
+  # is set in Capybara.default_locator.
+  def scope_within(locator)
+    if locator
+      within(locator) do
+        yield
+      end
+    else
+      yield
+    end
+  end
+
+  # Execute a block of code inside a given scope. The +scope+ Hash
+  # may include:
+  #
+  #   :within => locator    within the given selector
+  #
+  # Other scopes such as :before, :after and so on may be supported later
+  def in_scope(scope)
+    scope_within(scope[:within]) do
+      yield
+    end
+  end
+
+  # Verify the presence of one or more text strings.
+  # Scope may be defined per the #in_scope method.
+  def should_see(texts, scope={})
+    texts = [texts] if (texts.class == String || texts.class == Regexp)
+    in_scope(scope) do
+      texts.each do |text|
+        page_should_have text
+      end
+    end
+  end
+
+  # Verify the absence of one or more text strings.
+  # Scope may be defined per the #in_scope method.
+  def should_not_see(texts, scope={})
+    texts = [texts] if (texts.class == String || texts.class == Regexp)
+    in_scope(scope) do
+      texts.each do |text|
+        page_should_not_have text
+      end
+    end
+  end
+
+  # Follow a link.
+  # Scope may be defined per the #in_scope method.
+  def follow(link, scope={})
+    in_scope(scope) do
+      click_link(link)
+    end
+  end
+
+  # Press a button.
+  # Scope may be defined per the #in_scope method.
+  def press(button, scope={})
+    in_scope(scope) do
+      click_button(button)
+    end
+  end
+
+  # Verify that a table row exists containing all the given text strings.
+  def should_see_in_same_row(texts)
+    page.should have_xpath(xpath_row_containing(texts))
+  end
+
+  # Verify that a table row does NOT exist containing all the given text strings.
+  def should_not_see_in_same_row(texts)
+    page.should have_no_xpath(xpath_row_containing(texts))
+  end
+
+  # Click a link in a table row containing the given text.
+  def click_link_in_row(link, text)
+    row = find(:xpath, xpath_row_containing([link, text]))
+    row.click_link(link)
+  end
+
+  # Ensure that the element with the given HTML id is disabled.
+  def should_be_disabled(element_id)
+    page.should have_xpath("//*[@id='#{element_id}']")
+    page.should have_xpath("//*[@id='#{element_id}' and @disabled]")
+  end
+
+  # Ensure that the element with the given HTML id is enabled.
+  def should_be_enabled(element_id)
+    page.should have_xpath("//*[@id='#{element_id}']")
+    page.should have_no_xpath("//*[@id='#{element_id}' and @disabled]")
+  end
+
+  # Ensure that the current page content includes a String or Regexp.
+  def page_should_have(text_or_regexp)
+    if text_or_regexp.class == String
+      if page.respond_to? :should
+        page.should have_content(text_or_regexp)
+      else
+        assert page.has_content?(text_or_regexp)
+      end
+    elsif text_or_regexp.class == Regexp
+      if page.respond_to? :should
+        page.should have_xpath('.//*', :text => text_or_regexp)
+      else
+        assert page.has_xpath?('.//*', :text => text_or_regexp)
+      end
+    else
+      raise "Expected String or Regexp, got #{text_or_regexp.class}"
+    end
+  end
+
+  # Ensure that the current page content does not include a String or Regexp.
+  def page_should_not_have(text_or_regexp)
+    if text_or_regexp.class == String
+      if page.respond_to? :should
+        page.should have_no_content(text_or_regexp)
+      else
+        assert page.has_no_content?(text_or_regexp)
+      end
+    elsif text_or_regexp.class == Regexp
+      if page.respond_to? :should
+        page.should have_no_xpath('.//*', :text => text_or_regexp)
+      else
+        assert page.has_no_xpath?('.//*', :text => text_or_regexp)
+      end
+    else
+      raise "Expected String or Regexp, got #{text_or_regexp.class}"
+    end
+  end
+
+
+  private
+
+  # Return an XPath for any table row containing all strings in +texts+.
+  def xpath_row_containing(texts)
+    texts = [texts] if texts.class == String
+    conditions = texts.collect do |text|
+      "contains(., '#{text}')"
+    end.join(' and ')
+    return "//table//tr[#{conditions}]"
+  end
+
+end
+
+# TODO: Put this in a generator
+#World(WebHelper)
+

data/spec/capybara/click_link_in_row_spec.rb

@@ -0,0 +1,24 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe WebHelper, "#click_link_in_row" do
+  before(:each) do
+    visit('/home')
+  end
+
+  context "passes when" do
+    it "link exists in the row" do
+      click_link_in_row "Edit", "Eric"
+      should_see "You are editing record 1"
+    end
+  end
+
+  context "fails when" do
+    it "link does not exist in the row" do
+      lambda do
+        click_link_in_row "Frob", "Eric"
+      end.should raise_error
+    end
+  end
+end
+
+

data/spec/capybara/dropdown_spec.rb

@@ -0,0 +1,112 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe FormHelper, "#dropdown_should_equal" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "the option has the selected attribute" do
+      dropdown_should_equal "Height", "Average"
+    end
+
+    it "the option is chosen programmatically" do
+      select "Short", :from => "Height"
+      dropdown_should_equal "Height", "Short"
+
+      select "Tall", :from => "Height"
+      dropdown_should_equal "Height", "Tall"
+    end
+  end
+
+  context "fails when" do
+    it "the option does not have the selected attribute" do
+      lambda do
+        dropdown_should_equal "Height", "Tall"
+      end.should raise_error
+    end
+
+    it "the option was not the one chosen programmatically" do
+      select "Tall", :from => "Height"
+      lambda do
+        dropdown_should_equal "Height", "Average"
+      end.should raise_error
+    end
+  end
+
+end
+
+describe FormHelper, "#dropdown_should_include" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "a single option exists in the dropdown" do
+      dropdown_should_include "Height", "Short"
+      dropdown_should_include "Height", "Average"
+      dropdown_should_include "Height", "Tall"
+    end
+
+    it "multiple options exist in the dropdown" do
+      dropdown_should_include "Height", [
+        "Short",
+        "Average",
+        "Tall",
+      ]
+    end
+  end
+
+  context "fails when" do
+    it "a single option does not exist in the dropdown" do
+      lambda do
+        dropdown_should_include "Height", "Midget"
+      end.should raise_error
+    end
+
+    it "any of several options do not exist in the dropdown" do
+      lambda do
+        dropdown_should_include "Height", [
+          "Short",
+          "Average",
+          "Tall",
+          "Giant",
+        ]
+      end.should raise_error
+    end
+  end
+
+end
+
+describe FormHelper, "#dropdown_value_should_equal" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "the selected option has the given value" do
+      dropdown_value_should_equal "Height", "2"
+    end
+
+    it "the programmatically chosen option has the given value" do
+      select "Tall", :from => "Height"
+      dropdown_value_should_equal "Height", "3"
+    end
+  end
+
+  context "fails when" do
+    it "the selected option has a different value" do
+      lambda do
+        dropdown_value_should_equal "Height", "99"
+      end.should raise_error
+    end
+
+    it "the programmatically chosen option has a different value" do
+      select "Tall", :from => "Height"
+      lambda do
+        dropdown_value_should_equal "Height", "2"
+      end.should raise_error
+    end
+  end
+end
+

data/spec/capybara/field_should_be_empty_spec.rb

@@ -0,0 +1,44 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe FormHelper, "#field_should_be_empty" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    context "field with id" do
+      it "is empty" do
+        field_should_be_empty "first_name"
+        field_should_be_empty "last_name"
+      end
+    end
+
+    context "field with label" do
+      it "is empty" do
+        field_should_be_empty "First name"
+        field_should_be_empty "Last name"
+      end
+    end
+  end
+
+  context "fails when" do
+    context "field with id" do
+      it "has a value" do
+        fill_in "first_name", :with => "Brian"
+        lambda do
+          field_should_be_empty "first_name"
+        end.should raise_error
+      end
+    end
+
+    context "field with label" do
+      it "has a value" do
+        fill_in "First name", :with => "Brian"
+        lambda do
+          field_should_be_empty "First name"
+        end.should raise_error
+      end
+    end
+  end
+end
+