kelp 0.1.1 → 0.1.2

data/lib/kelp/helper.rb

@@ -0,0 +1,14 @@
+module Kelp
+  module Helper
+    # 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
+end

data/lib/kelp/navigation.rb

@@ -0,0 +1,63 @@
+require 'kelp/scoping'
+require 'kelp/xpath'
+
+module Kelp
+  # This module defines helper methods for navigating a webpage, including
+  # clicking links and pressing buttons.
+  #
+  module Navigation
+    include Scoping
+    include XPath
+
+    # Follow a link on the page.
+    #
+    # @example
+    #   follow "Login"
+    #   follow "Contact Us", :within => "#footer"
+    #
+    # @param [String] link
+    #   Capybara locator expression (id, name, or link text)
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    def follow(link, scope={})
+      in_scope(scope) do
+        click_link(link)
+      end
+    end
+
+    # Press a button on the page.
+    #
+    # @example
+    #   press "Cancel"
+    #   press "Submit", :within => "#survey"
+    #
+    # @param [String] button
+    #   Capybara locator expression (id, name, or button text)
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    def press(button, scope={})
+      in_scope(scope) do
+        click_button(button)
+      end
+    end
+
+
+    # Click a link in a table row containing the given text.
+    #
+    # @example
+    #   click_link_in_row "Edit", "Pinky"
+    #
+    # @param [String] link
+    #   Content of the link to click
+    # @param [String] text
+    #   Other content that must be in the same row
+    #
+    def click_link_in_row(link, text)
+      row = find(:xpath, xpath_row_containing([link, text]))
+      row.click_link(link)
+    end
+
+  end
+end

data/lib/kelp/scoping.rb

@@ -0,0 +1,45 @@
+module Kelp
+  # This module defines helper methods for restricting the scope of actions or
+  # verifications on a webpage.
+  #
+  module Scoping
+    # 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
+        # Use the selector_for method if it's defined
+        if defined? selector_for
+          within(*selector_for(locator)) { yield }
+        # Otherwise, remove any surrounding double-quotes
+        # and fall back on the Capybara locator syntax (CSS or XPath)
+        else
+          locator.gsub!(/^"(.*?)"$/, '\1')
+          within(locator) { yield }
+        end
+      else
+        yield
+      end
+    end
+
+
+    # Execute a block of code inside a given scope. `scope` must be a `Hash`
+    # of parameters that describes the context in which to execute the block.
+    #
+    # @example
+    #    in_scope :within => '#footer'
+    #        click_link "Contact Us"
+    #    end
+    #
+    # @param [Hash] scope
+    #   Context in which to execute the block
+    # @option scope [String] :within
+    #   Selector string
+    #
+    def in_scope(scope)
+      scope_within(scope[:within]) do
+        yield
+      end
+    end
+  end
+end

data/lib/kelp/visibility.rb

@@ -0,0 +1,176 @@
+require 'kelp/scoping'
+require 'kelp/xpath'
+
+module Kelp
+  # This module defines methods for verifying the visibility (or invisibility)
+  # of elements on a web page.
+  #
+  module Visibility
+    include Scoping
+    include XPath
+
+    # 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.
+    #
+    # @example
+    #   should_see "Animaniacs"
+    #   should_see ["Yakko", "Wakko", "Dot"]
+    #   should_see "Baloney", :within => "#slacks"
+    #   should_see /(Animaney|Totally Insaney|Pinky and the Brainy)/
+    #
+    # @param [String, Regexp, Array] texts
+    #   Text(s) or regexp(s) to look for
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    def should_see(texts, scope={})
+      texts = [texts] if (texts.class == String || texts.class == Regexp)
+      in_scope(scope) do
+        texts.each do |text|
+          page_should_contain text
+        end
+      end
+    end
+
+
+    # Verify the absence of content on the page. Passes when none of the given
+    # items are found on the page, and fails if any of them are found.
+    #
+    # @param [String, Regexp, Array] texts
+    #   Text(s) or regexp(s) to look for
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    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_contain text
+        end
+      end
+    end
+
+
+    # Ensure that the current page content includes a String or Regexp.
+    #
+    # @param [String, Regexp] text_or_regexp
+    #   Content you expect to be on the page
+    #
+    def page_should_contain(text_or_regexp)
+      if text_or_regexp.class == String
+        page_should_contain_text(text_or_regexp)
+      elsif text_or_regexp.class == Regexp
+        page_should_contain_regexp(text_or_regexp)
+      else
+        raise ArgumentError, "Expected String or Regexp, got #{text_or_regexp.class}"
+      end
+    end
+
+
+    # Ensure that the current page content does not include a String or Regexp.
+    #
+    # @param [String, Regexp] text_or_regexp
+    #   Content you expect to be missing from the page
+    #
+    def page_should_not_contain(text_or_regexp)
+      if text_or_regexp.class == String
+        page_should_not_contain_text(text_or_regexp)
+      elsif text_or_regexp.class == Regexp
+        page_should_not_contain_regexp(text_or_regexp)
+      else
+        raise ArgumentError, "Expected String or Regexp, got #{text_or_regexp.class}"
+      end
+    end
+
+
+    # Ensure that the current page content includes a String.
+    #
+    # @param [String] text
+    #   Content you expect to be on the page
+    #
+    def page_should_contain_text(text)
+      if page.respond_to? :should
+        page.should have_content(text)
+      else
+        assert page.has_content?(text)
+      end
+    end
+
+
+    # Ensure that the current page content matches a Regexp.
+    #
+    # @param [Regexp] regexp
+    #   Content you expect to match
+    #
+    def page_should_contain_regexp(regexp)
+      if page.respond_to? :should
+        page.should have_xpath('.//*', :text => regexp)
+      else
+        assert page.has_xpath?('.//*', :text => regexp)
+      end
+    end
+
+
+    # Ensure that the current page content does not include a String.
+    #
+    # @param [String] text
+    #   Content you expect to be missing from the page
+    #
+    def page_should_not_contain_text(text)
+      if page.respond_to? :should
+        page.should have_no_content(text)
+      else
+        assert page.has_no_content?(text)
+      end
+    end
+
+
+    # Ensure that the current page content does not match a Regexp.
+    #
+    # @param [Regexp] regexp
+    #   Content you expect to fail matching
+    #
+    def page_should_not_contain_regexp(regexp)
+      if page.respond_to? :should
+        page.should have_no_xpath('.//*', :text => regexp)
+      else
+        assert page.has_no_xpath?('.//*', :text => regexp)
+      end
+    end
+
+
+    # Verify that all items appear in the same table row. Passes if a `tr`
+    # element exists containing all the given `texts`, and fails if no such
+    # `tr` exists. The texts may be in any order in the row.
+    #
+    # @example
+    #   should_see_in_same_row ["Yakko", "Rob Paulsen"]
+    #   should_see_in_same_row ["Wakko", "Jess Harnell"]
+    #   should_see_in_same_row ["Dot", "Tress MacNeille"]
+    #
+    # @param [Array] texts
+    #   Array of Strings that should appear in the same row
+    #
+    def should_see_in_same_row(texts)
+      page.should have_xpath(xpath_row_containing(texts))
+    end
+
+
+    # Verify that all items do not appear in the same table row. Passes if there
+    # is no `tr` containing all the given `texts`, and fails if there exists
+    # such a `tr`.
+    #
+    # @example
+    #   should_not_see_in_same_row ["Pinky", "Maurice LaMarche"]
+    #   should_not_see_in_same_row ["Brain", "Rob Paulsen"]
+    #
+    # @param [Array] texts
+    #   Array of Strings that should not appear in the same row
+    #
+    def should_not_see_in_same_row(texts)
+      page.should have_no_xpath(xpath_row_containing(texts))
+    end
+
+
+  end
+end

data/lib/kelp/xpath.rb

@@ -0,0 +1,14 @@
+module Kelp
+  # This module defines helper methods for building XPath expressions.
+  #
+  module XPath
+    # 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
+end

data/spec/attribute_spec.rb

@@ -0,0 +1,56 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Kelp::Attribute, "should_be_disabled" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "element has the disabled attribute" do
+      should_be_disabled "readonly"
+    end
+  end
+
+  context "fails when" do
+    it "element does not exist" do
+      lambda do
+        should_be_disabled "nonexistent"
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    end
+
+    it "element does not have the disabled attribute" do
+      lambda do
+        should_be_disabled "first_name"
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    end
+  end
+end
+
+
+describe Kelp::Attribute, "should_be_enabled" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "element does not have the disabled attribute" do
+      should_be_enabled "first_name"
+    end
+  end
+
+  context "fails when" do
+    it "element does not exist" do
+      lambda do
+        should_be_enabled "nonexistent"
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    end
+
+    it "element has the disabled attribute" do
+      lambda do
+        should_be_enabled "readonly"
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    end
+  end
+end
+
+

data/spec/checkbox_spec.rb

@@ -0,0 +1,69 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Kelp::Checkbox, "checkbox_should_be_checked" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "the checkbox is checked by default" do
+      checkbox_should_be_checked "I like cheese"
+    end
+
+    it "the checkbox is checked programmatically" do
+      check "I like salami"
+      checkbox_should_be_checked "I like salami"
+    end
+  end
+
+  context "fails when" do
+    it "the checkbox is unchecked by default" do
+      lambda do
+        checkbox_should_be_checked "I like salami"
+      end.should raise_error
+    end
+
+    it "the checkbox is unchecked programmatically" do
+      uncheck "I like cheese"
+      lambda do
+        checkbox_should_be_checked "I like cheese"
+      end.should raise_error
+    end
+  end
+
+end
+
+
+describe Kelp::Checkbox, "checkbox_should_not_be_checked" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "the checkbox is unchecked by default" do
+      checkbox_should_not_be_checked "I like salami"
+    end
+
+    it "the checkbox is unchecked programmatically" do
+      uncheck "I like cheese"
+      checkbox_should_not_be_checked "I like cheese"
+    end
+  end
+
+  context "fails when" do
+    it "the checkbox is checked by default" do
+      lambda do
+        checkbox_should_not_be_checked "I like cheese"
+      end.should raise_error
+    end
+
+    it "the checkbox is checked programmatically" do
+      check "I like salami"
+      lambda do
+        checkbox_should_not_be_checked "I like salami"
+      end.should raise_error
+    end
+  end
+
+end
+

data/spec/dropdown_spec.rb

@@ -0,0 +1,176 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Kelp::Dropdown, "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 first option is selected by default" do
+      dropdown_should_equal "Weight", "Light"
+    end
+
+    it "the option is chosen programmatically" do
+      select "Short", :from => "Height"
+      dropdown_should_equal "Height", "Short"
+
+      select "Heavy", :from => "Weight"
+      dropdown_should_equal "Weight", "Heavy"
+    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(RSpec::Expectations::ExpectationNotMetError)
+    end
+
+    it "the option is not the first one selected by default" do
+      lambda do
+        dropdown_should_equal "Weight", "Medium"
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    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(RSpec::Expectations::ExpectationNotMetError)
+    end
+  end
+
+end
+
+
+describe Kelp::Dropdown, "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(RSpec::Expectations::ExpectationNotMetError)
+    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(RSpec::Expectations::ExpectationNotMetError)
+    end
+  end
+end
+
+
+describe Kelp::Dropdown, "dropdown_should_not_include" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "a single option does not exist in the dropdown" do
+      dropdown_should_not_include "Height", "Dwarf"
+      dropdown_should_not_include "Height", "Giant"
+      dropdown_should_not_include "Height", "Behemoth"
+    end
+
+    it "none of the multiple options exist in the dropdown" do
+      dropdown_should_not_include "Height", [
+        "Dwarf",
+        "Giant",
+        "Behemoth",
+      ]
+    end
+  end
+
+  context "fails when" do
+    it "a single option exists in the dropdown" do
+      lambda do
+        dropdown_should_not_include "Height", "Short"
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    end
+
+    it "any of several options exist in the dropdown" do
+      lambda do
+        dropdown_should_not_include "Height", [
+          "Dwarf",
+          "Giant",
+          "Behemoth",
+          "Tall",
+        ]
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    end
+  end
+end
+
+
+describe Kelp::Dropdown, "dropdown_value_should_equal" do
+  before(:each) do
+    visit('/form')
+  end
+
+  context "passes when" do
+    it "the option with the 'selected' attribute has the given value" do
+      dropdown_value_should_equal "Height", "2"
+    end
+
+    it "the first option selected by default has the given value" do
+      dropdown_value_should_equal "Weight", "1"
+    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 option with the 'selected' attribute has a different value" do
+      lambda do
+        dropdown_value_should_equal "Height", "99"
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    end
+
+    it "the first option selected by default does not have given value" do
+      lambda do
+        dropdown_value_should_equal "Weight", "2"
+      end.should raise_error(RSpec::Expectations::ExpectationNotMetError)
+    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(RSpec::Expectations::ExpectationNotMetError)
+    end
+  end
+end
+
+