---
title: RSpec on Rails
inMenu: true
---
h2. RSpec on Rails

RSpec's rspec_generator Rubygem brings RSpec to Rails.

h3. Features

* Integrated fixture loading
* Uses many of the controller-test integration features
* Special generators for models and controllers that generate specs instead of tests.

h3. Installation

RSpec support for rails lives in a separate gem. Install that gem:

<pre>
gem install rspec_generator
</pre>

Once the gem is installed, you must configure you Rails app. Stand in the root of your Rails app and run:

<pre>
ruby script/generate rspec
</pre>

Now, you can generate models and controllers in a similar fashion to Rails' builtin generators. Example:

<pre>
ruby script/generate rspec_model person
</pre>

or

<pre>
ruby script/generate rspec_controller person
</pre>

For more information on each generator, just run them without any arguments.

h3. Running specs

All specs can be run with

<pre>
rake spec
</pre>

Model specs can be run with

<pre>
rake spec:models
</pre>

Controller specs can be run with

<pre>
rake spec:controllers
</pre>

To see all the RSpec related tasks, run

<pre>
rake --tasks spec
</pre>

h3. Naming conventions

When you use Rails without RSpec (with Test::Unit), tests for models end up in tests/unit and tests for controllers
end up in tests/functional.

In order to make things more consistent, RSpec chooses a slightly different naming convention for direcotries and
Rake tasks. So you will find model specs under specs/models, and controller specs under specs/controllers. The
Rake tasks are named accordingly.

h3. Examples

RSpec on Rails adds several methods to your specs with a look and feel similar to Test::Unit. Example:

Model:
<ruby file="../vendor/rspec_on_rails/spec/models/person_spec.rb"/>

Controller:
<ruby file="../vendor/rspec_on_rails/spec/controllers/person_controller_spec.rb"/>

h3. Translating existing Test::Unit tests

The test2spec tool that ships with RSpec translates existing tests into RSpec specs. 
Translating tests to specs in a Rails environment requires some manual steps...

h4. Install the rspec_generator
How to do this is described above

h4. Modify your test/test_helper.rb
In order to be able to translate any Rails tests, you must modify your test/test_helper.rb file:
<pre>
# This line must be commented out in order for test2spec to work.
# require 'test_help'
require 'test2spec_help'
</pre>

The reason for this is that the <tt>test_help</tt> mixin confuses test2spec to the point
where it's unable to perform the translation. The <tt>test2spec_help</tt> addresses this
shortcoming.

h4. Perform the translations
Now you can translate your unit tests (model tests) with:
<pre>
test2spec --template spec/test2spec.erb --specdir spec/models test/unit
</pre>
and your functional tests (controller tests) with:
<pre>
test2spec --template spec/test2spec.erb --specdir spec/controllers test/functional
</pre>

h4. Edit your translated specs
test2spec currently doesn't translate class-level statements such as <tt>fixtures</tt>, so you have to do this yourself.
Copy all the <tt>fixtures</tt> statements in your tests to the corresponding contexts. Example:

<ruby>
context "The Foo Model" do
  fixtures :foo
end
</ruby>

h4. Make sure fixtures are found.
By default, RSpec on Rails expects to find fixtures under <tt>spec/fixtures</tt>. You should either move your
existing <tt>test/fixtures/*.yml</tt> files to <tt>spec/fixtures</tt> or edit your <tt>spec/spec_helper.rb</tt>
to point to the old <tt>test/fixtures</tt> location. Beware that every time you do a <tt>script/generate rspec_model</tt>,
new fixstures will always be written to <tt>spec/fixtures</tt>.