rspec-rails 2.99.0 → 3.0.0.beta1

data/features/README.md

@@ -0,0 +1,56 @@
+rspec-rails extends Rails' built-in testing framework to support rspec examples
+for requests, controllers, models, views, helpers, mailers and routing.
+
+## Rails-3
+
+rspec-rails-2 supports rails-3.0.0 and later. For earlier versions of Rails,
+you need [rspec-rails-1.3](http://rspec.info).
+
+## Install
+
+    gem install rspec-rails
+
+This installs the following gems:
+
+    rspec
+    rspec-core
+    rspec-expectations
+    rspec-mocks
+    rspec-rails
+
+## Configure
+
+Add rspec-rails to the :test and :development groups in the Gemfile:
+
+    group :test, :development do
+      gem "rspec-rails", "~> 2.4"
+    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:
+
+    script/rails generate rspec:install
+
+This adds the spec directory and some skeleton files, including a .rspec
+file.
+
+## 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"
+    gem "capybara"
+
+## Issues
+
+The documentation for rspec-rails is a work in progress. We'll be adding
+Cucumber features over time, and clarifying existing ones.  If you have
+specific features you'd like to see added, find the existing documentation
+incomplete or confusing, or, better yet, wish to write a missing Cucumber
+feature yourself, please [submit an
+issue](http://github.com/rspec/rspec-rails/issues) or a [pull
+request](http://github.com/rspec/rspec-rails).

data/features/RailsVersions.md

@@ -0,0 +1,4 @@
+    rails version | rspec-rails version
+    2.3           | 1.3.4
+    3.0           | >= 2.0
+    3.1           | >= 2.6

data/features/Transactions.md

@@ -0,0 +1,84 @@
+When you run `rails generate rspec:install`, the `spec/spec_helper.rb` file
+includes the following configuration:
+
+    RSpec.configure do |config|
+      config.use_transactional_fixtures = true
+    end
+
+The name of this setting is a bit misleading. What it really means in Rails
+is "run every test method within a transaction." In the context of rspec-rails,
+it means "run every example within a transaction."
+
+The idea is to start each example with a clean database, create whatever data
+is necessary for that example, and then remove that data by simply rolling back
+the transaction at the end of the example.
+
+### Disabling transactions
+
+If you prefer to manage the data yourself, or using another tool like
+[database_cleaner](https://github.com/bmabey/database_cleaner) to do it for you,
+simply tell RSpec to tell Rails not to manage transactions:
+
+    RSpec.configure do |config|
+      config.use_transactional_fixtures = false
+    end
+
+### Data created in `before(:each)` are rolled back
+
+Any data you create in a `before(:each)` hook will be rolled back at the end of
+the example. This is a good thing because it means that each example is
+isolated from state that would otherwise be left around by the examples that
+already ran. For example:
+
+    describe Widget do
+      before(:each) do
+        @widget = Widget.create
+      end
+
+      it "does something" do
+        expect(@widget).to do_something
+      end
+        
+      it "does something else" do
+        expect(@widget).to do_something_else
+      end
+    end
+
+The `@widget` is recreated in each of the two examples above, so each example
+has a different object, _and_ the underlying data is rolled back so the data
+backing the `@widget` in each example is new.
+        
+### Data created in `before(:all)` are _not_ rolled back
+
+`before(:all)` hooks are invoked before the transaction is opened. You can use
+this to speed things up by creating data once before any example in a group is
+run, however, this introduces a number of complications and you should only do
+this if you have a firm grasp of the implications. Here are a couple of
+guidelines:
+
+1.  Be sure to clean up any data in an `after(:all)` hook:
+
+        before(:all) do
+          @widget = Widget.create!
+        end
+
+        after(:all) do
+          @widget.destroy
+        end
+
+    If you don't do that, you'll leave data lying around that will eventually
+    interfere with other examples.
+
+2.  Reload the object in a `before(:each)` hook.
+
+        before(:all) do
+          @widget = Widget.create!
+        end
+
+        before(:each) do
+          @widget.reload
+        end
+
+      Even though database updates in each example will be rolled back, the
+      object won't _know_ about those rollbacks so the object and its backing
+      data can easily get out of sync.

data/features/Upgrade.md

@@ -0,0 +1,121 @@
+# 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](https://github.com/rspec/rspec-rails/issues).
+
+## Rake tasks
+
+Delete lib/tasks/rspec.rake, if present. Rake tasks now live in the rspec-rails
+gem.
+
+## `spec_helper.rb`
+
+There were a few changes to the generated `spec/spec_helper.rb` file. We
+recommend the following:
+
+1. set aside a copy of your existing `spec/spec_helper.rb` file.
+2. run `rails generate rspec:install`
+3. 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
+
+## Controller specs
+
+### 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.
+
+### `response.should render_template`
+
+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-rails-2 with expect syntax
+    get :edit, :id => "37"
+    expect(response).to 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, `render_template`
+delegates directly to Rails' `assert_template`, which only works after the
+action.
+
+## View specs
+
+### `view.should render_template`
+
+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")
+
+### stub_template
+
+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"
+
+### No more `have_tag` or `have_text`
+
+Before Webrat came along, rspec-rails had its own `have_tag` and `have_text`
+matchers that wrapped Rails' `assert_select`. Webrat included replacements for
+these methods, as well as new matchers (`have_selector` and `have_xpath`), all
+of which rely on Nokogiri to do its work, and are far less brittle than RSpec's
+`have_tag`.
+
+Capybara has similar matchers, which will soon be available view specs (they
+are already available in controller specs with `render_views`).
+
+Given the brittleness of RSpec's `have_tag` and `have_text` matchers and the
+presence of new Webrat and Capybara matchers that do a better job, `have_tag`
+and `have_text` were not included in rspec-rails-2.
+
+## Mocks, stubs, doubles
+
+### as_new_record
+
+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
+this:
+
+    stub_model(Widget, :new_record? => true)
+
+to this:
+
+    stub_model(Widget).as_new_record
+
+Generators in 2.0.0 final release will do the latter.

data/features/controller_specs/Cookies.md

@@ -0,0 +1,57 @@
+Controller specs wrap Rails controller tests, which expose a few different ways
+to access cookies:
+
+    @request.cookies['key']
+    @response.cookies['key']
+    cookies['key']
+
+rails-3.0.x and 3.1 handle these slightly differently, so to avoid confusion, we recommend
+the following guidelines:
+
+### Recommended guidelines for rails-3.0.0 to 3.1.0
+
+  * Access cookies through the `request` and `response` objects in the spec.
+    * Use `request.cookies` before the action to set up state.
+    * Use `response.cookies` after the action to specify outcomes.
+  * Use the `cookies` object in the controller action. 
+  * Use String keys.
+
+<pre>
+# spec
+request.cookies['foo'] = 'bar'
+get :some_action
+expect(response.cookies['foo']).to eq('modified bar')
+
+# controller
+def some_action
+  cookies['foo'] = "modified #{cookies['foo']}"
+end
+</pre>
+
+#### Why use Strings instead of Symbols?
+
+The `cookies` objects in the spec come from Rack, and do not support
+indifferent access (i.e. `:foo` and `"foo"` are different keys). The `cookies`
+object in the controller _does_ support indifferent access, which is a bit
+confusing.
+
+This changed in rails-3.1, so you _can_ use symbol keys, but we recommend
+sticking with string keys for consistency.
+
+#### Why not use the `cookies` method?
+
+The `cookies` method combines the `request` and `response` cookies. This can
+lead to confusion when setting cookies in the example in order to set up state
+for the controller action. 
+
+    # does not work in rails 3.0.0 > 3.1.0
+    cookies['foo'] = 'bar' # this is not visible in the controller
+    get :some_action
+
+### Future versions of Rails
+
+There is code in the master branch in rails that makes cookie access more
+consistent so you can use the same `cookies` object before and after the action, 
+and you can use String or Symbol keys. We'll update these docs accordingly when
+that is released.
+

data/features/controller_specs/README.md

@@ -0,0 +1,45 @@
+Controller specs live in `spec/controllers` or any example group with
+`:type => :controller`.
+
+A controller spec is an RSpec wrapper for a Rails functional test
+([ActionController::TestCase::Behavior](https://github.com/rails/rails/blob/master/actionpack/lib/action_controller/test_case.rb)).
+It allows you to simulate a single http request in each example, and then
+specify expected outcomes such as:
+
+* rendered templates
+* redirects
+* instance variables assigned in the controller to be shared with the view
+* cookies sent back with the response
+
+To specify outcomes, you can use:
+
+* standard rspec matchers (`expect(response.status).to eq(200)`)
+* standard test/unit assertions (`assert_equal 200, response.status`)
+* rails assertions (`assert_response 200`)
+* rails-specific matchers:
+  * `expect(response).to render_template(wraps assert_template)`
+  * `expect(response).to redirect_to(wraps assert_redirected_to)`
+  * `expect(assigns(:widget)).to be_a_new(Widget)`
+
+## Examples
+
+    describe TeamsController do
+      describe "GET index" do
+        it "assigns @teams" do
+          team = Team.create
+          get :index
+          expect(assigns(:teams)).to eq([team])
+        end
+
+        it "renders the index template" do
+          get :index
+          expect(response).to render_template("index")
+        end
+      end
+    end
+
+## Views
+
+* by default, views are not rendered. See
+  [views are stubbed by default](controller-specs/views-are-stubbed-by-default) and
+  [render_views](controller-specs/render-views) for details.

data/features/controller_specs/anonymous_controller.feature

@@ -0,0 +1,378 @@
+Feature: anonymous controller
+
+  Use the `controller` method to define an anonymous controller derived from
+  `ApplicationController`. This is useful for specifying behavior like global
+  error handling.
+
+  To specify a different base class, you can pass the class explicitly to the
+  controller method:
+
+      controller(BaseController)
+
+  You can also configure RSpec to use the described class:
+
+      RSpec.configure do |c|
+        c.infer_base_class_for_anonymous_controllers = true
+      end
+
+      describe BaseController do
+        controller { ... }
+        # ^^ creates an anonymous subclass of `BaseController`
+
+  Scenario: specify error handling in ApplicationController
+    Given a file named "spec/controllers/application_controller_spec.rb" with:
+      """ruby
+      require "spec_helper"
+
+      class ApplicationController < ActionController::Base
+        class AccessDenied < StandardError; end
+
+        rescue_from AccessDenied, :with => :access_denied
+
+      private
+
+        def access_denied
+          redirect_to "/401.html"
+        end
+      end
+
+      describe ApplicationController do
+        controller do
+          def index
+            raise ApplicationController::AccessDenied
+          end
+        end
+
+        describe "handling AccessDenied exceptions" do
+          it "redirects to the /401.html page" do
+            get :index
+            expect(response).to redirect_to("/401.html")
+          end
+        end
+      end
+      """
+    When I run `rspec spec`
+    Then the examples should all pass
+
+  Scenario: specify error handling in subclass of ApplicationController
+    Given a file named "spec/controllers/application_controller_subclass_spec.rb" with:
+      """ruby
+      require "spec_helper"
+
+      class ApplicationController < ActionController::Base
+        class AccessDenied < StandardError; end
+      end
+
+      class ApplicationControllerSubclass < ApplicationController
+
+        rescue_from ApplicationController::AccessDenied, :with => :access_denied
+
+      private
+
+        def access_denied
+          redirect_to "/401.html"
+        end
+      end
+
+      describe ApplicationControllerSubclass do
+        controller(ApplicationControllerSubclass) do
+          def index
+            raise ApplicationController::AccessDenied
+          end
+        end
+
+        describe "handling AccessDenied exceptions" do
+          it "redirects to the /401.html page" do
+            get :index
+            expect(response).to redirect_to("/401.html")
+          end
+        end
+      end
+      """
+    When I run `rspec spec`
+    Then the examples should all pass
+
+  Scenario: infer base class from the described class
+    Given a file named "spec/controllers/base_class_can_be_inferred_spec.rb" with:
+      """ruby
+      require "spec_helper"
+
+      RSpec.configure do |c|
+        c.infer_base_class_for_anonymous_controllers = true
+      end
+
+      class ApplicationController < ActionController::Base; end
+
+      class ApplicationControllerSubclass < ApplicationController; end
+
+      describe ApplicationControllerSubclass do
+        controller do
+          def index
+            render :text => "Hello World"
+          end
+        end
+
+        it "creates an anonymous controller derived from ApplicationControllerSubclass" do
+          expect(controller).to be_a_kind_of(ApplicationControllerSubclass)
+        end
+      end
+      """
+    When I run `rspec spec`
+    Then the examples should all pass
+
+  Scenario: invoke around filter in base class
+    Given a file named "spec/controllers/application_controller_around_filter_spec.rb" with:
+      """ruby
+      require "spec_helper"
+
+      class ApplicationController < ActionController::Base
+        around_filter :an_around_filter
+
+        def an_around_filter
+          @callback_invoked = true
+          yield
+        end
+      end
+
+      describe ApplicationController do
+        controller do
+          def index
+            render :nothing => true
+          end
+        end
+
+        it "invokes the callback" do
+          get :index
+
+          expect(assigns[:callback_invoked]).to be_truthy
+        end
+      end
+      """
+    When I run `rspec spec`
+    Then the examples should all pass
+
+  Scenario: anonymous controllers only create resource routes
+    Given a file named "spec/controllers/application_controller_spec.rb" with:
+    """ruby
+    require "spec_helper"
+
+    describe ApplicationController do
+      controller do
+        def index
+          render :text => "index called"
+        end
+
+        def create
+          render :text => "create called"
+        end
+
+        def new
+          render :text => "new called"
+        end
+
+        def show
+          render :text => "show called"
+        end
+
+        def edit
+          render :text => "edit called"
+        end
+
+        def update
+          render :text => "update called"
+        end
+
+        def destroy
+          render :text => "destroy called"
+        end
+
+        def willerror
+          render :text => "will not render"
+        end
+      end
+
+      describe "#index" do
+        it "responds to GET" do
+          get :index
+          expect(response.body).to eq "index called"
+        end
+
+        it "also responds to POST" do
+          post :index
+          expect(response.body).to eq "index called"
+        end
+
+        it "also responds to PUT" do
+          put :index
+          expect(response.body).to eq "index called"
+        end
+
+        it "also responds to DELETE" do
+          delete :index
+          expect(response.body).to eq "index called"
+        end
+      end
+
+      describe "#create" do
+        it "responds to POST" do
+          post :create
+          expect(response.body).to eq "create called"
+        end
+
+        # And the rest...
+        %w{get post put delete}.each do |calltype|
+          it "responds to #{calltype}" do
+            send(calltype, :create)
+            expect(response.body).to eq "create called"
+          end
+        end
+      end
+
+      describe "#new" do
+        it "responds to GET" do
+          get :new
+          expect(response.body).to eq "new called"
+        end
+
+        # And the rest...
+        %w{get post put delete}.each do |calltype|
+          it "responds to #{calltype}" do
+            send(calltype, :new)
+            expect(response.body).to eq "new called"
+          end
+        end
+      end
+
+      describe "#edit" do
+        it "responds to GET" do
+          get :edit, :id => "anyid"
+          expect(response.body).to eq "edit called"
+        end
+
+        it "requires the :id parameter" do
+          expect { get :edit }.to raise_error(ActionController::RoutingError)
+        end
+
+        # And the rest...
+        %w{get post put delete}.each do |calltype|
+          it "responds to #{calltype}" do
+            send(calltype, :edit, {:id => "anyid"})
+            expect(response.body).to eq "edit called"
+          end
+        end
+      end
+
+      describe "#show" do
+        it "responds to GET" do
+          get :show, :id => "anyid"
+          expect(response.body).to eq "show called"
+        end
+
+        it "requires the :id parameter" do
+          expect { get :show }.to raise_error(ActionController::RoutingError)
+        end
+
+        # And the rest...
+        %w{get post put delete}.each do |calltype|
+          it "responds to #{calltype}" do
+            send(calltype, :show, {:id => "anyid"})
+            expect(response.body).to eq "show called"
+          end
+        end
+      end
+
+      describe "#update" do
+        it "responds to PUT" do
+          put :update, :id => "anyid"
+          expect(response.body).to eq "update called"
+        end
+
+        it "requires the :id parameter" do
+          expect { put :update }.to raise_error(ActionController::RoutingError)
+        end
+
+        # And the rest...
+        %w{get post put delete}.each do |calltype|
+          it "responds to #{calltype}" do
+            send(calltype, :update, {:id => "anyid"})
+            expect(response.body).to eq "update called"
+          end
+        end
+      end
+
+      describe "#destroy" do
+        it "responds to DELETE" do
+          delete :destroy, :id => "anyid"
+          expect(response.body).to eq "destroy called"
+        end
+
+        it "requires the :id parameter" do
+          expect { delete :destroy }.to raise_error(ActionController::RoutingError)
+        end
+
+        # And the rest...
+        %w{get post put delete}.each do |calltype|
+          it "responds to #{calltype}" do
+            send(calltype, :destroy, {:id => "anyid"})
+            expect(response.body).to eq "destroy called"
+          end
+        end
+      end
+
+      describe "#willerror" do
+        it "cannot be called" do
+          expect { get :willerror }.to raise_error(ActionController::RoutingError)
+        end
+      end
+    end
+    """
+    When I run `rspec spec`
+    Then the examples should all pass
+
+  Scenario: draw custom routes for anonymous controllers
+    Given a file named "spec/controllers/application_controller_spec.rb" with:
+    """ruby
+    require "spec_helper"
+
+    describe ApplicationController do
+      controller do
+        def custom
+          render :text => "custom called"
+        end
+      end
+
+      specify "a custom action can be requested if routes are drawn manually" do
+        routes.draw { get "custom" => "anonymous#custom" }
+
+        get :custom
+        expect(response.body).to eq "custom called"
+      end
+    end
+    """
+    When I run `rspec spec`
+    Then the examples should all pass
+
+  Scenario: refer to application routes in the controller under test
+    Given a file named "spec/controllers/application_controller_spec.rb" with:
+    """ruby
+    require "spec_helper"
+
+    Rails.application.routes.draw do
+      match "/login" => "sessions#new", :as => "login", :via => "get"
+    end
+
+    describe ApplicationController do
+      controller do
+        def index
+          redirect_to login_url
+        end
+      end
+
+      it "redirects to the login page" do
+        get :index
+        expect(response).to redirect_to("/login")
+      end
+    end
+    """
+    When I run `rspec spec`
+    Then the examples should all pass