rspec-rails

rspec-rails 2 is a testing framework for Rails 3.x and 4.x.

Use rspec-rails 1 for Rails 2.x.

Install

Add rspec-rails to the :test and :development groups in the Gemfile:

group :test, :development do
  gem "rspec-rails", "~> 2.0"
end

It needs to be in the :development group to expose generators and rake tasks without having to type RAILS_ENV=test.

Now you can run:

rails generate rspec:install

This adds the spec directory and some skeleton files, including the "rake spec" task.

Generators

Once installed, RSpec will generate spec file instead of Test::Unit test files when commands like rails generate model and rails generate controller are used.

Model Specs

Model specs reside in the spec/models folder. Use model specs to describe behavior of models (usually ActiveRecord-based) in the application. For example:

require "spec_helper"

describe User do
  it "orders by last name" do
    lindeman = User.create!(first_name: "Andy", last_name: "Lindeman")
    chelimsky = User.create!(first_name: "David", last_name: "Chelimsky")

    expect(User.ordered_by_last_name).to eq([chelimsky, lindeman])
  end
end

For more information, see cucumber scenarios for model specs.

Controller Specs

Controller specs reside in the spec/controllers folder. Use controller specs to describe behavior of Rails controllers. For example:

require "spec_helper"

describe PostsController do
  describe "GET #index" do
    it "responds successfully with an HTTP 200 status code" do
      get :index
      expect(response).to be_success
      expect(response.code).to eq(200)
    end

    it "renders the index template" do
      get :index
      expect(response).to render_template("index")
    end

    it "loads all of the posts into @posts" do
      post1, post2 = Post.create!, Post.create!
      get :index

      expect(assigns(:posts)).to match_array([post1, post2])
    end
  end
end

For more information, see cucumber scenarios for controller specs.

Note: To encourage more isolated testing, views are not rendered by default in controller specs. If you wish to assert against the contents of the rendered view in a controller spec, enable render_views or use a higher-level request spec or feature spec.

Request Specs

Request specs live in spec/requests, spec/api and spec/integration, and mix in behavior ActionDispatch::Integration::Runner, which is the basis for Rails' integration tests. The intent is to specify one or more request/response cycles from end to end using a black box approach.

require 'spec_helper'
describe "home page" do
  it "displays the user's username after successful login" do
    user = User.create!(:username => "jdoe", :password => "secret")
    get "/login"
    assert_select "form.login" do
      assert_select "input[name=?]", "username"
      assert_select "input[name=?]", "password"
      assert_select "input[type=?]", "submit"
    end

    post "/login", :username => "jdoe", :password => "secret"
    assert_select ".header .username", :text => "jdoe"
  end
end

This example uses only standard Rails and RSpec API's, but many RSpec/Rails users like to use extension libraries like FactoryGirl and Capybara:

require 'spec_helper'
describe "home page" do
  it "displays the user's username after successful login" do
    user = FactoryGirl.create(:user, :username => "jdoe", :password => "secret")
    visit "/login"
    fill_in "Username", :with => "jdoe"
    fill_in "Password", :with => "secret"
    click_button "Log in"

    expect(page).to have_selector(".header .username", :text => "jdoe")
  end
end

FactoryGirl decouples this example from changes to validation requirements, which can be encoded into the underlying factory definition without requiring changes to this example.

Among other benefits, Capybara binds the form post to the generated HTML, which means we don't need to specify them separately.

There are several other Ruby libs that implement the factory pattern or provide a DSL for request specs (a.k.a. acceptance or integration specs), but FactoryGirl and Capybara seem to be the most widely used. Whether you choose these or other libs, we strongly recommend using something for each of these roles.

View specs

View specs live in spec/views, and mix in ActionView::TestCase::Behavior.

require 'spec_helper'
describe "events/index" do
  it "renders _event partial for each event" do
    assign(:events, [stub_model(Event), stub_model(Event)])
    render
    expect(view).to render_template(:partial => "_event", :count => 2)
  end
end

describe "events/show" do
  it "displays the event location" do
    assign(:event, stub_model(Event,
      :location => "Chicago"
    ))
    render
    expect(rendered).to include("Chicago")
  end
end

View specs infer the controller name and path from the path to the view template. e.g. if the template is "events/index.html.erb" then:

controller.controller_path == "events"
controller.request.path_parameters[:controller] == "events"

This means that most of the time you don't need to set these values. When spec'ing a partial that is included across different controllers, you may need to override these values before rendering the view.

To provide a layout for the render, you'll need to specify both the template and the layout explicitly. For example:

render :template => "events/show", :layout => "layouts/application"

assign(key, val)

Use this to assign values to instance variables in the view:

assign(:widget, stub_model(Widget))
render

The code above assigns stub_model(Widget) to the @widget variable in the view, and then renders the view.

Note that because view specs mix in ActionView::TestCase behavior, any instance variables you set will be transparently propagated into your views (similar to how instance variables you set in controller actions are made available in views). For example:

@widget = stub_model(Widget)
render # @widget is available inside the view

RSpec doesn't officially support this pattern, which only works as a side-effect of the inclusion of ActionView::TestCase. Be aware that it may be made unavailable in the future.

Upgrade note

# rspec-rails-1.x
assigns[key] = value

# rspec-rails-2.x
assign(key, value)

rendered

This represents the rendered view.

render
expect(rendered).to match /Some text expected to appear on the page/

Upgrade note

# rspec-rails-1.x
render
response.should xxx

# rspec-rails-2.x
render
rendered.should xxx

# rspec-rails-2.x with expect syntax
render
expect(rendered).to xxx

Routing specs

Routing specs live in spec/routing.

require 'spec_helper'
describe "routing to profiles" do
  it "routes /profile/:username to profile#show for username" do
    expect(:get => "/profiles/jsmith").to route_to(
      :controller => "profiles",
      :action => "show",
      :username => "jsmith"
    )
  end

  it "does not expose a list of profiles" do
    expect(:get => "/profiles").not_to be_routable
  end
end

Upgrade note

route_for from rspec-rails-1.x is gone. Use route_to and be_routable instead.

Helper specs

Helper specs live in spec/helpers, and mix in ActionView::TestCase::Behavior.

Provides a helper object which mixes in the helper module being spec'd, along with ApplicationHelper (if present).

require 'spec_helper'
describe EventsHelper do
  describe "#link_to_event" do
    it "displays the title, and formatted date" do
      event = Event.new("Ruby Kaigi", Date.new(2010, 8, 27))
      # helper is an instance of ActionView::Base configured with the
      # EventsHelper and all of Rails' built-in helpers
      expect(helper.link_to_event).to match /Ruby Kaigi, 27 Aug, 2010/
    end
  end
end

Matchers

rspec-rails exposes domain-specific matchers to each of the example group types. Most of them simply delegate to Rails' assertions.

be_a_new

• Available in all specs.
• Primarily intended for controller specs

expect(object).to be_a_new(Widget)

Passes if the object is a Widget and returns true for new_record?

render_template

• Delegates to Rails' assert_template.
• Available in request, controller, and view specs.

In request and controller specs, apply to the response object:

expect(response).to render_template("new")

In view specs, apply to the view object:

expect(view).to render_template(:partial => "_form", :locals => { :widget => widget } )

redirect_to

• Delegates to assert_redirect
• Available in request and controller specs.

expect(response).to redirect_to(widgets_path)

route_to

• Delegates to Rails' assert_routing.
• Available in routing and controller specs.

expect(:get => "/widgets").to route_to(:controller => "widgets", :action => "index")

be_routable

Passes if the path is recognized by Rails' routing. This is primarily intended to be used with not_to to specify routes that should not be routable.

expect(:get => "/widgets/1/edit").not_to be_routable

rake tasks

rspec-rails defines rake tasks to run the entire test suite (rake spec) and subsets of tests (e.g., rake spec:models).

A full list of the available rake tasks can be seen by running rake -T | grep rspec.

Customizing rake tasks

If you want to customize the behavior of rake spec, you may define your own task in the Rakefile for your project. However, you must first clear the task that rspec-rails defined:

task("spec").clear

Webrat and Capybara

You can choose between webrat or capybara for simulating a browser, automating a browser, or setting expectations using the matchers they supply. Just add your preference to the Gemfile:

gem "webrat"
# ... or ...
gem "capybara"

See http://rubydoc.info/gems/rspec-rails/file/Capybara.md for more info on Capybara integration.

Contribute

See http://github.com/rspec/rspec-dev.

For rspec-rails-specific development information, see DEV-README.

Also see

• http://github.com/rspec/rspec
• http://github.com/rspec/rspec-core
• http://github.com/rspec/rspec-expectations
• http://github.com/rspec/rspec-mocks

Feature Requests & Bugs

See http://github.com/rspec/rspec-rails/issues