wvanbergen-rspec_form_matcher 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+/coverage
+/tmp
+/doc

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Willem van Bergen
+ 
+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/README.rdoc

@@ -0,0 +1,72 @@
+= RSpec FormMatcher
+
+An RSpec matcher that checks views for the presence of a form, including
+the presence of specified input fields that should be within the form tag.
+This can be especially useful to test forms that submit to an external 
+website and thus cannot be included in a Cucumber story.
+
+== Setup
+
+Install the gem:
+
+  gem install wvanbergen-rspec_form_matcher -s http://gems.github.com
+
+And include it in your <tt>spec_helper.rb</tt>:
+
+  require 'rspec_form_matcher'
+  Spec::Runner.configure do |config|
+    config.include Spec::Matchers::FormMatcher, :type => :views
+  end
+  
+The <b>libxml-ruby</b> gem is required to perform the XPath Query that is used
+for checking the form.
+
+== Example
+
+With following HTML snippet:
+
+  <form action="http://example.com/submit" method="post">
+    <input type="hidden" name="foo" value="bar" />
+    <input type="submit" />
+  </form>
+  <input type="hidden" name="outside" value="form" />
+
+Consider the following specs:
+
+  response.should have_form(:post => 'http://example.com/submit') # succeeds
+  response.should have_form(:put => 'http://example.com/submit') # fails
+  response.should have_form(:post => 'http://other.com/submit') # fails
+  
+  response.should have_form(:post => 'http://example.com/submit').with(
+    :hidden, 'foo', 'bar').and_with(:submit_button) # succeeds  
+  
+  response.should have_form(:post => 'http://example.com/submit').with(
+    :hidden, 'outside', 'form').and_with(:submit_button) # fails
+
+An alternative syntax using a block is available, which is more suitable 
+to check complex forms. Note the use of curly braces instead of do ... end,
+to make sure that the block binds to the <tt>have_form</tt> call.
+
+  response.should have_form(:post => 'http://example.com/submit') { |form| 
+      form.hidden 'foo', 'bar'
+      form.submit_button
+    }
+
+See the <tt>spec/form_matcher_spec.rb</tt> file for more examples.
+
+== Supported checks
+
+  have_form(method => action) {
+    form.hidden('name')          # hidden field with name 'name'
+    form.hidden('name', 'value') # field with value
+    
+    form.text('username')            # named text input
+    form.text('username', 'default') # checks default value
+    form.password('password')        # named password field
+    
+    form.checkbox('name', 'value')              # checkbox with value
+    form.checkbox('name[]', 'value1', 'value2') # array of checkboxes
+    form.radio('name', 'value1', 'value2', ...) # radiobuttons
+    
+    form.submit_button # makes sure the form can be submitted
+  }

data/Rakefile

@@ -0,0 +1,24 @@
+require 'spec/rake/spectask'
+
+desc "Run all RSpec examples and report the result"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = Dir['spec/**/*_spec.rb']
+  t.spec_opts << '--format specdoc'
+  t.rcov = true
+end
+
+def gemspec_file
+  Dir['*.gemspec'].first
+end
+
+namespace(:gem) do
+  task(:manifest) do 
+    # update the spec file
+    spec = File.read(gemspec_file)
+    spec.gsub!(/^(\s+\w+\.files\s*=\s*)[^\s].*$/) do 
+      $1 + `git ls-files`.split("\n").inspect
+    end
+
+    File.open(gemspec_file, 'w') { |f| f << spec }
+  end
+end

data/lib/rspec_form_matcher.rb

@@ -0,0 +1,159 @@
+module Spec
+  module Matchers
+    module FormMatcher
+      class HaveForm
+        attr_reader :action, :method, :field, :submit_button
+
+        def initialize(action = nil)
+          case action
+            when Hash then action.each { |m, a| @method, @action = m, a }
+            when String, Regexp then @action = action
+          end
+      
+          @tags   = []
+          @checks = []
+        end
+
+        def with(method, *args)
+          self.send(method, *args)
+        end
+    
+        alias :and_with :with
+
+        def input(type, field_name, value = nil)
+          attributes = { :type => type, :name => field_name }
+          attributes[:value] = value if value
+          tag('input', attributes)
+        end
+
+        def tag(tag, attributes = {})
+          @checks << tag_xpath(tag, attributes)
+          return self
+        end
+
+        def hidden(field_name, value = nil)
+          input(:hidden, field_name, value)
+        end
+    
+        def submit_button
+          button_xpath = tag_xpath('button', :type => 'submit')
+          input_xpath  = tag_xpath('input',  :type => 'submit')
+          image_xpath  = tag_xpath('input',  :type => 'image')      
+          @checks << "#{input_xpath} or #{button_xpath} or #{image_xpath}"
+          return self
+        end
+    
+        def text(field_name, value = nil)
+          input(:text, field_name, value)      
+        end
+
+        def radio(field_name, *values)
+          if values.empty?
+            input(:radio, field_name)
+          else
+            values.each { |v| input(:radio, field_name, v) }
+          end
+          return self
+        end
+
+        def password(field_name, value = nil)
+          input(:password, field_name, value)
+        end
+
+        def checkbox(field_name, *values)
+          if values.empty?
+            input(:checkbox, field_name)
+          else
+            values.each { |v| input(:checkbox, field_name, v) }
+          end
+          return self
+        end
+
+        def matches?(stringlike)
+          @document = document(stringlike)
+          @xpath    = build_xpath_query
+          check_xpath!
+        end
+    
+        def failure_message
+          "Specified form (XPath: << #{@xpath} >>) not found in document: \n#{@document.to_s}"
+        end
+        
+        def negative_failure_message
+          "Unexpectedly found specified form (XPath: << #{@xpath} >>) in document: \n#{@document.to_s}"
+        end
+
+        protected
+
+        def tag_xpath(tag, attributes = {})
+          field_xpath = "descendant::#{tag}"
+          attributes.each { |k, v| field_xpath << "[@#{k}='#{v}']" }
+          return field_xpath
+        end
+
+        def build_xpath_query
+          form_xpath = "//form"
+          form_xpath << "[@method='#{method.to_s.downcase}']" if @method      # fn:lower-case(@method)
+          form_xpath << "[@action='#{@action}']" if @action
+          form_xpath << "[#{@checks.join('][')}]" unless @checks.empty?
+      
+          # puts form_xpath
+          return form_xpath
+        end
+      end
+  
+      def have_form(options = {})
+        form_matcher = HaveForm.new(options)
+        yield(form_matcher) if block_given?
+        return form_matcher
+      end
+      
+      module REXML
+        def check_xpath!
+          !@document.elements[@xpath].nil?
+        end   
+        
+        def document(subject)
+          if String === subject
+            ::REXML::Document.new(subject).root
+          elsif subject.respond_to?(:body)
+            ::REXML::Document.new(subject.body).root
+          elsif ::REXML::Element === subject
+            subject
+          else
+            raise "Cannot handle this XML input type"
+          end
+        end        
+      end
+
+      module LibXML
+        def check_xpath!
+          !@document.find_first(@xpath).nil?
+        end
+        
+        def document(subject)
+          if String === subject
+            XML::HTMLParser.string(subject).parse
+          elsif subject.respond_to?(:body)
+            XML::HTMLParser.string(subject.body).parse
+          elsif XML::Node === subject
+            subject
+          elsif XML::Document === subject
+            subject
+          else
+            raise "Cannot handle this XML input type"
+          end
+        end
+      end
+
+      begin 
+        require 'xml'
+        HaveForm.send(:include, LibXML)
+      rescue LoadError => e
+        require 'rexml/document'
+        HaveForm.send(:include, REXML)
+      end
+            
+    end
+  end
+end

data/rspec_form_matcher.gemspec

@@ -0,0 +1,23 @@
+Gem::Specification.new do |s|
+  s.name    = 'rspec_form_matcher'
+  s.version = '0.1.0'
+  s.date    = '2009-08-28'
+  
+  s.summary = "RSpec matcher to check forms including their fields."
+  s.description = <<-eos
+    The RSpec form matcher will check a string to see whether a specified form exists with the correct action and method.
+    Moreover, it will check whether the specified fields actually occur within this form tag.
+  eos
+  
+  s.author   = 'Willem van Bergen'
+  s.email    = 'willem@vanbergen.org'
+  s.homepage = 'http://github.com/wvanbergen/rspec_form_matcher'
+  
+  s.add_dependency('rspec', ['>= 1.2.4'])
+    
+  s.rdoc_options << '--title' << s.name << '--main' << 'README.rdoc' << '--line-numbers' << '--inline-source'
+  s.extra_rdoc_files = ['README.rdoc']
+  
+  s.files      = [".gitignore", "LICENSE", "README.rdoc", "Rakefile", "lib/rspec_form_matcher.rb", "rspec_form_matcher.gemspec", "spec/form_matcher_spec.rb", "spec/spec_helper.rb"]
+  s.test_files = s.files.select { |file| file =~ /^spec\/.*_spec\.rb$/ }
+end

data/spec/form_matcher_spec.rb

@@ -0,0 +1,108 @@
+require "#{File.dirname(__FILE__)}/spec_helper.rb"
+
+describe Spec::Matchers::FormMatcher do
+
+  before(:all) do
+    @correct_form = <<-eos
+      <html>
+        <form action="/endpoint" method="post">
+          <input type="hidden" name="foo" value="bar" />
+        
+          <input type="radio" name="choice" value="1" />
+          <input type="radio" name="choice" value="2" />
+        
+          <input type="hidden" name="select" value="0" />
+          <input type="checkbox" name="select" value="1" />
+          
+          <input type="text" name="username" />
+          <input type="password" name="password" />
+          
+          <button type="submit"> Submit! </button>
+        </form>
+      </html>
+    eos
+    
+    @wrong_form = <<-eos
+      <html>
+        <form action="/endpoint" method="post"></form>
+        
+        <input type="hidden" name="foo" value="bar" />
+     
+        <input type="radio" name="choice" value="1" />
+        <input type="radio" name="choice" value="2" />
+     
+        <input type="hidden" name="select" value="0" />
+        <input type="checkbox" name="select" value="1" />
+       
+        <input type="text" name="username" />
+        <input type="password" name="password" />
+       
+        <button type="submit"> Submit! </button>
+      </html>    
+    eos
+    
+  end
+  
+  it "should assert the presence of the form correctly" do
+    @correct_form.should have_form(:post => '/endpoint')
+  end
+
+  it "should not assert the presence of the form with a wrong HTTP method" do
+    @correct_form.should_not have_form(:put => '/endpoint')
+  end
+
+  it "should not assert the presence of the form with a wrong action" do
+    @correct_form.should_not have_form(:post => '/different_endpoint')
+  end
+
+  it "should assert the submit button" do
+    @correct_form.should have_form(:post => '/endpoint').with(:submit_button)
+  end
+
+  it "should not assert the submit button if it is outside the form tag" do
+    @wrong_form.should_not have_form(:post => '/endpoint').with(:submit_button)
+  end
+
+  it "should assert the hidden field 'foo' without value" do
+    @correct_form.should have_form(:post => '/endpoint').with(:hidden, 'foo')
+  end
+
+  it "should assert the hidden field 'foo' when it is outside the form tag" do
+    @wrong_form.should_not have_form(:post => '/endpoint').with(:hidden, 'foo')
+  end
+
+  it "should assert the hidden field 'foo' with value 'bar'" do
+    @correct_form.should have_form(:post => '/endpoint').with(:hidden, 'foo', 'bar')
+  end
+
+  it "should assert the presence of different radio buttons" do
+    @correct_form.should have_form(:post => '/endpoint').with(:radio, 'choice', '1', '2')
+  end
+
+  it "should not assert the presence of different radio buttons when outside the form tag" do
+    @wrong_form.should_not have_form(:post => '/endpoint').with(:radio, 'choice', '1', '2')
+  end
+
+  it "should assert the presence of different radio buttons with one too much values" do
+    @correct_form.should_not have_form(:post => '/endpoint').with(:radio, 'choice', '1', '2', '3')
+  end
+
+  it "should assert the presence of the checkbox" do
+    @correct_form.should have_form(:post => '/endpoint').with(:checkbox, 'select', '1')
+  end
+
+  it "should not assert the presence of the checkbox when outside the form tag" do
+    @correct_form.should have_form(:post => '/endpoint').with(:checkbox, 'select', '1')
+  end
+  
+  it "should assert a form using a block syntax" do
+    @correct_form.should have_form(:post => '/endpoint') { |form| 
+        form.hidden 'foo', 'bar'
+        form.checkbox 'select', '1'
+        form.radio 'choice', '1', '2'
+        form.text :username
+        form.password :password
+      }
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'spec'
+require 'spec/autorun'
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require "rspec_form_matcher"
+
+Spec::Runner.configure do |config|
+  # Include matchers for view specs
+  config.include Spec::Matchers::FormMatcher
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: wvanbergen-rspec_form_matcher
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Willem van Bergen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-28 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.4
+    version: 
+description: The RSpec form matcher will check a string to see whether a specified form exists with the correct action and method. Moreover, it will check whether the specified fields actually occur within this form tag.
+email: willem@vanbergen.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/rspec_form_matcher.rb
+- rspec_form_matcher.gemspec
+- spec/form_matcher_spec.rb
+- spec/spec_helper.rb
+has_rdoc: false
+homepage: http://github.com/wvanbergen/rspec_form_matcher
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --title
+- rspec_form_matcher
+- --main
+- README.rdoc
+- --line-numbers
+- --inline-source
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: RSpec matcher to check forms including their fields.
+test_files: 
+- spec/form_matcher_spec.rb