Upgrading from rspec-rails-1.x to rspec-rails-2.
This is a work in progress. Please submit errata, missing steps, or patches to the rspec-rails issue tracker.
Delete lib/tasks/rspec.rake, if present. Rake tasks now live in the rspec-rails gem.
There were a few changes to the generated
spec/spec_helper.rb file. We
recommend the following:
- set aside a copy of your existing
rails generate rspec:install
- copy any customizations from your old spec_helper to the new one
If you prefer to make the changes manually in the existing spec_helper, here is what you need to change:
# rspec-1 require 'spec/autorun' Spec::Runner.configure do |config| ... end # rspec-2 require 'rspec/rails' RSpec.configure do |config| ... end
isolation from view templates
By default, controller specs do not render view templates. This keeps controller specs isolated from the content of views and their requirements.
NOTE that the template must exist, but it will not be rendered. This is different from rspec-rails-1.x, in which the template didn't need to exist, but ActionController makes a number of new decisions in Rails 3 based on the existence of the template. To keep the RSpec code free of monkey patches, and to keep the rspec user experience simpler, we decided that this would be a fair trade-off.
This needs to move from before the action to after. For example:
# rspec-rails-1 controller.should render_template("edit") get :edit, :id => "37" # rspec-rails-2 get :edit, :id => "37" response.should render_template("edit")
rspec-1 had to monkey patch Rails to get render_template to work before the
action, and this broke a couple of times with Rails releases (requiring urgent
fix releases in RSpec). Part of the philosophy of rspec-rails-2 is to rely on
public APIs in Rails as much as possible. In this case,
delegates directly to Rails'
assert_template, which only works after the
Rails changed the way it renders partials, so to set an expectation that a partial gets rendered, you need
render view.should render_template(:partial => "widget/_row")
Introduced in rspec-rails-2.2, simulates the presence of view templates on the file system. This supports isolation from partials rendered by the vew template that is the subject of a view example:
stub_template "widgets/_widget.html.erb" => "This Content"
Before Webrat came along, rspec-rails had its own
matchers that wrapped Rails'
assert_select. Webrat included replacements for
these methods, as well as new matchers (
of which rely on Nokogiri to do its work, and are far less brittle than RSpec's
Capybara has similar matchers, which will soon be available view specs (they
are already available in controller specs with
Given the brittleness of RSpec's
have_text matchers and the
presence of new Webrat and Capybara matchers that do a better job,
have_text were not included in rspec-rails-2.
Mocks, stubs, doubles
Earlier versions of the view generators generated stub_model with
:new_record? => true. That is no longer recognized in rspec-rails-2, so you need to change
stub_model(Widget, :new_record? => true)
Generators in 2.0.0 final release will do the latter.