HpricotForms
============

I love to use HtmlUnit to do web-based navigation tests, back in Java land. So
I'm attempting to re-create a similar testing experience here.

== Installation

./script/plugin install http://choonkeat.svnrepository.com/svn/rails-plugins/hpricot_forms

== Examples

In a hypothetical application login application, we write the functional test
like this:

def test_login_logout
  page = get :new            # first, let's get to the login page
  form = page.forms.first    # next, get a reference to the form
  
  # form.field_names => ["user[login]", "user[password]"] 
                             # form.field_names returns you the input fields
                             # available in the form

  form["options[]"]        = ["secure", "remember"] 
  							 # e.g. options[] fields are checkboxes
  							 
  form["user[login]"]    = "Joe"
  form["user[password]"] = "topsecret"
  							 # these are single-value inputs
  							 
  page = form.submit(self)   # after setting the form values, submit it
                             # 'page' now references the page after login
                             
  assert_response :success
  
  # page.links               # returns you an array of links found on the page

  page = page.links("@id='signout'").first.click(self)
                             # locate the sign-out link by its html ID 
                             # attribute and click it
                             
  assert_response :success
end

Notice we didn't need to handle things like session and where the form submits
to explicitly. It simply goes to where its supposed to - as rendered. And yes,
as you do submit() and click() you might actually cross different controllers.
HpricotForms handles that for you. 

The main thing I like about this API is, the field names in the form are real.
When you modify your action template (.rhtml files) but forgot to change your
test and controllers - traditionally, your tests will still pass because you 
were passing in parameters explicitly, e.g.

  post :login, {:user => {:login => "Joe", :password => "topsecret"}}

even though your HTML form fields might have been changed to "account[login]" 
and "account[passwd]".

But HpricotForms will raise an exception when you try to set values into fields
that does not exist in the rendered form.

== Notes

I don't really like doing 'instance_variable_get' but that's how I can get it 
to work now. Even worse, I don't like the explicit 'self' argument required to 
do submit() and click(). Any suggestion will be appreciated.

== Tests

Not implemented

== Rake

Not implemented

== Thanks to

HtmlUnit's API [http://htmlunit.sourceforge.net/gettingStarted.html]
_why's Hpricot library [http://redhanded.hobix.com/inspect/hpricot01.html]

== License

HpricotForms is released under the MIT license.

== Author

Chew Choon Keat <choonkeat at gmail>
http://blog.yanime.org/

19 July 2006