h1. Mechanical Cuke

mechanical-cuke re-implements the Cucumber step definitions provided by cucumber-rails' web_steps.rb in Mechanize.  This allows Cucumber features to be written for any site by running the tests over HTTP.

mechanical-cuke also provides a driver for Capybara with enough support to run the cucumber-rails web_steps.rb.  This allows you use Mechanize in conjunction with Capybara other drivers (handy if you need to do some Javascript testing).

h2. Rational

Webrat and Capybara both can drive tests over HTML.  However, Webrat's Mechanize support is limited (doesn't work with multipart forms, can't submit empty form fields, no support for basic auth).  Capybara drives tests over HTTP using browsers, excellent for testing Javascript, but slow for test that only involve HTML.

h2. Usage

To use the standalone version of Mechanical Cuke add:

bc. require 'mechanical-cuke'

to features/support/env.rb

To use Mechanical Cuke with Capybara add:

bc. require 'mechanical-cuke/capybara'
Capybara.default_driver = :mechanical_cuke

In features/support/paths.rb you will need to make sure you are returning the full URL.  The simplest way to do this is to add 'URL' + before the case statement in the path_to function e.g.:

bc. def path_to(page_name)
    case page_name

becomes

bc. def path_to(page_name)
   'http://localhost:3000' +
    case page_name

h2. Steps Provided by the Standalone Version

bc. Given am on path
When I go to path

GET the page at _path_ and sets it to the current page for follow steps.

bc. When I press "button"

Press button with label "_button_".  If the button is in a form the form is submitted.

bc. When I follow "link"

Click the link with text "_link_".

bc. When I fill in "field" with "value"
When I fill in "value" for "field"

Fill in the text field, password field, or text area _field_ with _value_.  _field_ can be the id or name of the field, or the text within the label for the field.

bc. When I fill in the following:

Takes a table of fields and values of the form:

bc. When I fill in the following:
     | Account Number | 5002       |
     | Expiry date    | 2009-11-01 |
     | Note           | Nice guy   |
 

bc. When I select "value" from "field"

Selects the option with _value_ from select list _field_.  _field_ can be the id or name of the field, or the text within the label for the field.

bc. When I check "field"
When I uncheck "field"

Check or uncheck the checkbox "_field_".

bc. When I choose "field"

Checks radio button _field_.  _field_ can be the id or the text within the label for the field; the field name would be ambiguous.

When I attach the file "path" to "field"

Attach the file in _path_ to the file field _field_.

bc. Then I should see "text"
Then I should see /regexp/

The body of the page should contain _text_ or _regexp_.

bc. Then I should not see "text"
Then I should not see /regexp/

The body of the page should *not* contain _text_ or _regexp_.

bc. Then the "field" field should contain "value"
Then the "field" field should not contain "value"

The value _field_ should be (or not be) _value_.

bc. Then the "_field_" checkbox should be checked
Then the "_field_" checkbox not should be checked

The checkbox _field_ should be (or not be) checked.

bc. Then I should be on _path_

The path/uri of the current page should be _path_.

bc. Then show me the page

Save the current page and open in the default browser.

h2. Basic Auth

You can provide basic auth credentials by calling:

bc. basic_auth(username,password)

in your step definitions before visiting a protected page.

h2. Todo

Add scopes to allow steps to function within an element e.g:

bc. When I press "Submit" within "#login_form"

Make Rspec support actually work.

Make Capybara driver complete.

h2. Author

Spike Ilacqua