kelp 0.1.1 → 0.1.2

data/.gitignore

@@ -3,3 +3,5 @@
 coverage
 docs/_build
 .rvmrc
+doc
+.yardoc

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--markup markdown
+lib/**/*.rb
+-
+History.md
+

data/Gemfile

@@ -1,12 +1,7 @@
 source :rubygems
 
-group :capybara do
-  gem 'capybara', '>= 0.4.0'
-end
+gem 'bundler', '~> 1.0'
+
+# Get all other dependencies from the gemspec
+gemspec
 
-group :test do
-  gem 'sinatra'
-  gem 'rspec', '>= 2.2.0' # Rails 3
-  gem 'rspec-rails'
-  gem 'rcov'
-end

data/Gemfile.lock

@@ -1,3 +1,9 @@
+PATH
+  remote: .
+  specs:
+    kelp (0.1.2)
+      capybara (>= 0.4.0)
+
 GEM
   remote: http://rubygems.org/
   specs:
@@ -84,7 +90,9 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  bundler (~> 1.0)
   capybara (>= 0.4.0)
+  kelp!
   rcov
   rspec (>= 2.2.0)
   rspec-rails

data/History.md

@@ -0,0 +1,22 @@
+Kelp History
+============
+
+0.1.2
+-----
+
+- Improved namespacing for submodules, so you can be more specific about
+  requiring the helpers you need.
+- Improved documentation and formatting, and converted all docs to YARD format.
+- Added new methods fill_in_field, added scoping to field_should(_not)_contain
+- Modified scope_within to use cucumber-rails' selector_for if it's defined
+
+
+0.1.1
+-----
+
+Initial public release. Includes basic helpers for checking element visibility
+(should_see, should_not_see etc.) as well as navigation (press, follow,
+click_link_in_row), form filling and verification (fill_in_fields,
+fields_should_contain, dropdown_should_equal, etc.), with many of these
+methods supporting a :within scope.
+

data/README.md

@@ -1,16 +1,163 @@
 Kelp
 ====
 
-This project aims to package a collection of useful helper methods for
-Cucumber. Currently, the provided methods depend on Capybara, though support
-may eventually be added for Webrat, email-spec, or related tools.
+This is the documentation for [Kelp](http://github.com/wapcaplet/kelp), a
+collection of helpers that makes it easier to write step definitions for
+[Cucumber](http://cukes.info). The Kelp gem is hosted on
+[Rubygems](http://rubygems.org/gems/kelp), so you can install it with:
+
+    $ gem install kelp
+
+The name "Kelp" is a contraction of "Cuke Helpers". It was chosen because it's
+short, easy to remember, and is in keeping with the theme of greenish plants.
+Kelp is licensed under the
+[MIT License](http://www.opensource.org/licenses/mit-license.php).
+
+Please use the [issue tracker](http://github.com/wapcaplet/kelp/issues)
+to report any bugs or feature requests. Visit the `#kelp` channel on
+`irc.freenode.net` to chat.
+
+
+Usage
+-----
+
+To use Kelp's helpers in your Cucumber step definitions, simply `require` the
+helper module you're interested in:
+
+    require 'kelp/visibility'
+
+Then add the relevant modules to Cucumber's `World`:
+
+    World(Kelp::Visibility)
+
+Many of the provided helpers are designed to make it easier to do things you
+might otherwise be tempted to do with nested step definitions. For example, if
+you need to verify the presence of several text strings on a webpage, you might
+have a step definition like this:
+
+    Then /^I should see the login page$/ do
+      Then %{I should see "Welcome"}
+      And %{I should see "Thanks for visiting"}
+      And %{I should see "Login"}
+    end
+
+Using the provided helper method `should_see`, you can do this instead:
+
+    Then /^I should see the login page$/ do
+      should_see "Welcome"
+      should_see "Thanks for visiting"
+      should_see "Login"
+    end
+
+Or even this:
+
+    Then /^I should see the login page$/ do
+      should_see [
+        "Welcome",
+        "Thanks for visiting",
+        "Login"
+      ]
+    end
+
+Many of the provided methods are similar to their counterparts in the
+Cucumber-Rails generated step definitions. Following links, filling in fields,
+and pressing buttons can all be easily done with Ruby code instead of nested
+steps. Thus this:
+
+    When %{I follow "Login"}
+    And %{I fill in "Username" with "skroob"}
+    And %{I fill in "Password" with "12345"}
+    And %{I press "Log me in"}
+
+translates to this:
+
+    follow "Login"
+    fill_in_fields \
+      "Username" => "skroob",
+      "Password" => "12345"
+    press "Log me in"
+
+Several methods also accept keywords to define the scope of an action. For
+instance, if you want to look within an element with id="greeting"`, do:
+
+    should_see "Welcome", :within => "#greeting"
+
+At the moment, the `:within` keyword is the only accepted scope; the locator
+you pass to this should be in whatever format your `Capybara.default_selector`
+is set to. Other keywords like `:before` or `:after` may be supported in future
+revisions.
+
+
+Development
+-----------
+
+If you'd like to hack on Kelp, first fork the {http://github.com/wapcaplet/kelp
+repository}, then clone your fork:
+
+    $ git clone git://github.com/your_username/kelp.git
+
+Install [bundler](http://gembundler.com/):
+
+    $ gem install bundler
+
+Then install Kelp's dependencies (specified in `Gemfile`):
+
+    $ cd /path/to/kelp
+    $ bundle install
+
+It's a good idea to use [RVM](http://rvm.beginrescueend.com/)
+with a new gemset to keep things tidy.
+
+If you make changes that you'd like to share, push them into your Kelp fork,
+then [submit a pull request](http://github.com/wapcaplet/kelp/pulls).
+
+
+Testing
+-------
+
+Kelp comes with a `Rakefile`, so you can run the RSpec tests like so:
+
+    $ rake spec
+
+You can also generate an [rcov](http://eigenclass.org/hiki.rb?rcov)
+coverage report via:
+
+    $ rake rcov
+
+This will write an HTML report to `coverage/index.html`.
+
+
+Future plans
+------------
+
+* Write Cucumber integration tests
+* Support other stuff besides Capybara
+* Turn the project into a proper Rails plugin, with generators
 
-[Read the docs](http://kelp.rtfd.org/) online or view the raw documentation in
-the `docs` folder.
 
 Copyright
 ---------
 
-Copyright (c) 2010 Eric Pierce, released under the MIT license.
-See MIT-LICENSE for details.
+The MIT License
+
+Copyright (c) 2010 Eric Pierce
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 

data/kelp.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = "kelp"
-  s.version = "0.1.1"
+  s.version = "0.1.2"
   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

@@ -1 +1,8 @@
-require 'kelp/capybara'
+require 'kelp/attribute'
+require 'kelp/checkbox'
+require 'kelp/dropdown'
+require 'kelp/field'
+require 'kelp/navigation'
+require 'kelp/scoping'
+require 'kelp/visibility'
+

data/lib/kelp/attribute.rb

@@ -0,0 +1,31 @@
+module Kelp
+  # This module defines helper methods for verifying attributes of HTML
+  # elements on a web page.
+  #
+  module Attribute
+    # Verify that the HTML element with the given ID exists, and is disabled (has
+    # the `disabled` attribute).
+    #
+    # @param [String] element_id
+    #   HTML `id` attribute of the element that should be disabled
+    #
+    def should_be_disabled(element_id)
+      page.should have_xpath("//*[@id='#{element_id}']")
+      page.should have_xpath("//*[@id='#{element_id}' and @disabled]")
+    end
+
+
+    # Verify that the HTML element with the given ID exists, and is enabled (does
+    # not have the `disabled` attribute).
+    #
+    # @param [String] element_id
+    #   HTML `id` attribute of the element that should be 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
+
+  end
+
+end

data/lib/kelp/checkbox.rb

@@ -0,0 +1,31 @@
+require 'kelp/helper'
+require 'kelp/scoping'
+
+module Kelp
+  module Checkbox
+    include Scoping
+    include Helper
+
+    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
+        end
+      end
+    end
+
+    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
+        end
+      end
+    end
+  end
+end

data/lib/kelp/dropdown.rb

@@ -0,0 +1,109 @@
+require 'kelp/scoping'
+require 'kelp/helper'
+
+module Kelp
+  # This module defines methods for working with dropdown fields in a web form,
+  # including verifying their visible content as well as the `value` attribute
+  # of selected options.
+  #
+  module Dropdown
+    include Scoping
+    include Helper
+
+    # 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.
+    #
+    # @param [String] dropdown
+    #   Capybara locator for the dropdown (the `select` element)
+    # @param [String] value
+    #   Value you expect to see as the currently-selected 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 strings.
+    # This looks for the visible values in the dropdown, *not* the 'value'
+    # attribute of each option.
+    #
+    # @example
+    #   dropdown_should_include "Weekday", "Monday"
+    #   dropdown_should_include "Size", ["Small", "Medium", "Large"]
+    #
+    # @param [String] dropdown
+    #   Capybara locator for the dropdown (the `select` element)
+    # @param [Array] values
+    #   Visible contents you expect to be able to select from the dropdown
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    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()='#{value}']")
+        end
+      end
+    end
+
+
+    # Verify that a given dropdown does not include any of the given strings.
+    # This looks for the visible values in the dropdown, *not* the 'value'
+    # attribute of each option.
+    #
+    # @param [String] dropdown
+    #   Capybara locator for the dropdown (the `select` element)
+    # @param [Array] values
+    #   Visible contents you do not want to see in the dropdown
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    # @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()='#{value}']")
+        end
+      end
+    end
+
+
+    # Verify that a dropdown currently has the option with the given `value`
+    # attribute selected. Note that this differs from {#dropdown_should_equal},
+    # in that it looks at the actual `value` attribute of the selected option,
+    # rather than its visible contents.
+    #
+    # @param [String] dropdown
+    #   Capybara locator for the dropdown (the `select` element)
+    # @param [String] value
+    #   Expected `value` attribute of the selected `option`
+    #
+    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
+
+  end
+end

data/lib/kelp/field.rb

@@ -0,0 +1,159 @@
+require 'kelp/helper'
+require 'kelp/scoping'
+
+module Kelp
+  # This module defines helper methods for filling in and verifying the content
+  # of fields in a web form.
+  #
+  module Field
+    include Scoping
+    include Helper
+
+    # Fill in multiple fields according to values in a `Hash`.
+    #
+    # @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] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    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 a single field within the scope of a given selector.
+    def fill_in_field(field, value, scope={})
+      fields = {field => value}
+      fill_in_fields fields, scope
+    end
+
+
+    # Fill in multiple fields within the scope of a given selector.
+    # Alias for:
+    #
+    #   fill_in_fields fields, :within => selector
+    #
+    def fill_in_fields_within(selector, fields)
+      fill_in_fields fields, :within => selector
+    end
+
+
+    # Fill in a single fields within the scope of a given selector.
+    # Alias for:
+    #
+    #   fill_in_field field, value, :within => selector
+    #
+    def fill_in_field_within(selector, field, value)
+      fill_in_field field, value, :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 RuntimeError, "Expected field '#{field}' to be empty, but value is '#{_field.value}'"
+      end
+    end
+
+
+    # Verify that the given field contains the given value.
+    #
+    # @param [String] field
+    #   Capybara locator for the field (name, id, or label text)
+    # @param [String] value
+    #   Value you expect to see in the text field
+    #
+    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
+        # 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
+    end
+
+
+    def field_should_not_contain(field, value, scope={})
+      raise "Not implemented yet"
+      #with_scope(parent) do
+        #field = find_field(field)
+        #field_value = (field.tag_name == 'textarea') ? field.text : field.value
+        #if field_value.respond_to? :should_not
+          #field_value.should_not =~ /#{value}/
+        #else
+          #assert_no_match(/#{value}/, field_value)
+        #end
+      #end
+    end
+
+
+    # Verify the values of multiple fields given as a Hash.
+    #
+    # @param [Hash] field_values
+    #   "field" => "value" for each field you want to verify
+    # @param [Hash] scope
+    #   Scoping keywords as understood by {#in_scope}
+    #
+    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 a single field within the scope of a given selector.
+    # Alias for:
+    #
+    #   field_should_contain field, value, :within => selector
+    #
+    def field_should_contain_within(selector, field, value)
+      field_should_contain field, value, :within => selector
+    end
+
+
+    # Verify fields within the scope of a given selector.
+    # Alias for:
+    #
+    #   fields_should_contain field_values, :within => selector
+    #
+    def fields_should_contain_within(selector, field_values)
+      fields_should_contain field_values, :within => selector
+    end
+
+  end
+end