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 spec_helper.rb:

require 'rspec_form_matcher'
Spec::Runner.configure do |config|
  config.include Spec::Matchers::FormMatcher, :type => :views
end

The libxml-ruby 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 have_form call.

response.should have_form(:post => 'http://example.com/submit') { |form| 
    form.hidden 'foo', 'bar'
    form.submit_button
  }

See the spec/form_matcher_spec.rb 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
}