h1. Unencumbered

_You got Cucumber in my RSpec!_

Write Cucumber-flavored integration tests as easily as you write your RSpec.

h2. To Get Output Like This

Output from a @rake spec:integration@ run:

<pre>
<code>
User creates a vurl
  Scenario:  creating
    Given I am on the home page
      When I submit a valid vurl
        Then I should be on vurl stats page
        And I should see a success message
        And my vurl was successfully created
</code>
</pre>

h2. Make a Feature Like This

Put it in a spec file in the _spec/integration_ folder. Here's
_user_creates_vurl_spec.rb_ for example:

<pre>
<code>
require File.expand_path('../../spec_helper', __FILE__)

Feature "User creates a vurl" do
  Scenario "creating" do
    Given "I am on the home page" do
      executes { visit root_path }
      
      When "I submit a valid vurl" do
        executes do
          fill_in "vurl_url", :with => 'http://example.com'
          click_button 'Vurlify!'
        end
        
        Then "I should be on the vurl stats page" do
          current_url.should == stats_url(Vurl.last.slug)
        end
        
        And "I should see a success message" do
          response.body.should include('Vurl was successfully created')
        end
        
        And "my vurl was created" do
          Vurl.last.url.should == 'http://example.com'
        end
      end
    end
  end
end
</code>
</pre>

h2. Set Up

h3. Environment

Add this line to your _config/environments/test.rb_ file. Make sure to use the
@:lib => false@ item.  We need to require the library manually in the
_spec_helper.rb_, since it patches RSpec.

<pre>
<code>
config.gem "unencumbered", :lib => false, :version => 'x.x.x'
</code>
</pre>


h3. spec_helper.rb

Meld these lines into your existing _spec/spec_helper.rb_. Note the
_unencumbered_ require needs to be after your RSpec requires, since it patches
RSpec.

<pre>
<code>
require 'unencumbered'
require 'webrat'

Webrat.configure do |config|
  config.mode = :rails
end

Spec::Runner.configure do |config|

  [...your other config code...]

  config.include(Webrat::Matchers, :type => [:integration])
end

class ActionController::Integration::Session; include Spec::Matchers; end
</code>
</pre>


h3. spec.opts

RSpec's nested format reads nicely. Put this line in your _spec/spec.opts_
file.

<pre>
<code>
--format nested
</code>
</pre>


Copyright (c) 2009 Hashrocket.  See LICENSE for details.