rspec-rails 2.6.1 → 2.7.0.rc1

data/README.md

@@ -2,7 +2,7 @@
 
 rspec-2 for rails-3 with lightweight extensions to each
 
-[![build status](http://travis-ci.org/rspec/rspec-rails.png)](http://travis-ci.org/rspec/rspec-rails)
+[![build status](https://secure.travis-ci.org/rspec/rspec-rails.png)](http://travis-ci.org/rspec/rspec-rails)
 
 NOTE: rspec-2 does _not_ support rails-2. Use rspec-rails-1.3.x for rails-2.
 
@@ -36,18 +36,18 @@ This installs the following gems:
 Add `rspec-rails` to the `:test` and `:development` groups in the Gemfile:
 
     group :test, :development do
-      gem "rspec-rails", "~> 2.4"
+      gem "rspec-rails", "~> 2.6"
     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: 
+Now you can run:
 
-    script/rails generate rspec:install
+    rails g rspec:install
 
 This adds the spec directory and some skeleton files, including
-the "rake spec" task. 
+the "rake spec" task.
 
 ### Generators
 

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
+        @widget.should do_something
+      end
+        
+      it "does something else" do
+        @widget.should 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/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
+response.cookies['foo'].should 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/anonymous_controller.feature

@@ -1,109 +1,152 @@
 Feature: anonymous controller
 
   Use the `controller` method to define an anonymous controller derived from
-  ApplicationController, or any other base controller. This is useful for
-  specifying behavior like global error handling.
+  `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:
-    """
-    require "spec_helper"
+      """
+      require "spec_helper"
 
-    class ApplicationController < ActionController::Base
-      class AccessDenied < StandardError; end
+      class ApplicationController < ActionController::Base
+        class AccessDenied < StandardError; end
 
-      rescue_from AccessDenied, :with => :access_denied
+        rescue_from AccessDenied, :with => :access_denied
 
-    private
+      private
 
-      def access_denied
-        redirect_to "/401.html"
+        def access_denied
+          redirect_to "/401.html"
+        end
       end
-    end
 
-    describe ApplicationController do
-      controller do
-        def index
-          raise ApplicationController::AccessDenied
+      describe ApplicationController do
+        controller do
+          def index
+            raise ApplicationController::AccessDenied
+          end
         end
-      end
 
-      describe "handling AccessDenied exceptions" do
-        it "redirects to the /401.html page" do
-          get :index
-          response.should redirect_to("/401.html")
+        describe "handling AccessDenied exceptions" do
+          it "redirects to the /401.html page" do
+            get :index
+            response.should redirect_to("/401.html")
+          end
         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:
-    """
-    require "spec_helper"
+      """
+      require "spec_helper"
 
-    class ApplicationController < ActionController::Base
-      class AccessDenied < StandardError; end
-    end
+      class ApplicationController < ActionController::Base
+        class AccessDenied < StandardError; end
+      end
 
-    class ApplicationControllerSubclass < ApplicationController
+      class ApplicationControllerSubclass < ApplicationController
 
-      rescue_from ApplicationController::AccessDenied, :with => :access_denied
+        rescue_from ApplicationController::AccessDenied, :with => :access_denied
 
       private
 
-      def access_denied
-        redirect_to "/401.html"
+        def access_denied
+          redirect_to "/401.html"
+        end
       end
-    end
 
-    describe ApplicationControllerSubclass do
-      controller(ApplicationControllerSubclass) do
-        def index
-          raise ApplicationController::AccessDenied
+      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
+            response.should redirect_to("/401.html")
+          end
         end
       end
+      """
+    When I run `rspec spec`
+    Then the examples should all pass
 
-      describe "handling AccessDenied exceptions" do
-        it "redirects to the /401.html page" do
-          get :index
-          response.should redirect_to("/401.html")
+  Scenario: infer base class from the described class
+    Given a file named "spec/controllers/base_class_can_be_inferred_spec.rb" with:
+      """
+      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
+          controller.should be_a_kind_of(ApplicationControllerSubclass)
         end
       end
-    end
-    """
+      """
     When I run `rspec spec`
     Then the examples should all pass
 
-  Scenario: regression with ApplicationController around_filters
+  Scenario: invoke around filter in base class
     Given a file named "spec/controllers/application_controller_around_filter_spec.rb" with:
-    """
-    require "spec_helper"
+      """
+      require "spec_helper"
 
-    class ApplicationController < ActionController::Base
-      around_filter :some_around_filter
+      class ApplicationController < ActionController::Base
+        around_filter :an_around_filter
 
-      def some_around_filter
-        @callback_invoked = true
-        yield
+        def an_around_filter
+          @callback_invoked = true
+          yield
+        end
       end
-    end
 
-    describe ApplicationController do
-      controller do
-        def index
-          render :nothing => true
+      describe ApplicationController do
+        controller do
+          def index
+            render :nothing => true
+          end
         end
-      end
 
-      it "invokes the callback" do
-        get :index
+        it "invokes the callback" do
+          get :index
 
-        assigns[:callback_invoked].should be_true
+          assigns[:callback_invoked].should be_true
+        end
       end
-    end
-    """
+      """
     When I run `rspec spec`
     Then the examples should all pass

data/features/controller_specs/bypass_rescue.feature

@@ -0,0 +1,75 @@
+Feature: bypass rescue
+
+  Use `bypass_rescue` to bypass both Rails' default handling of errors in
+  controller actions, and any custom handling declared with a `rescue_from`
+  statement.
+
+  This lets you specify details of the exception being raised, regardless of
+  how it might be handled upstream.
+
+  Background:
+    Given a file named "spec/controllers/gadgets_controller_spec_context.rb" with:
+      """
+      class AccessDenied < StandardError; end
+
+      class ApplicationController < ActionController::Base
+        rescue_from AccessDenied, :with => :access_denied
+
+        private
+
+        def access_denied
+          redirect_to "/401.html"
+        end
+      end
+      """
+
+  Scenario: standard exception handling using `rescue_from`
+    Given a file named "spec/controllers/gadgets_controller_spec.rb" with:
+      """
+      require "spec_helper"
+
+      require 'controllers/gadgets_controller_spec_context'
+
+      describe GadgetsController do
+        before do
+          def controller.index
+            raise AccessDenied
+          end
+        end
+
+        describe "index" do
+          it "redirects to the /401.html page" do
+            get :index
+            response.should redirect_to("/401.html")
+          end
+        end
+      end
+      """
+    When I run `rspec spec/controllers/gadgets_controller_spec.rb`
+    Then the examples should all pass
+
+  Scenario: bypass `rescue_from` handling with `bypass_rescue`
+    Given a file named "spec/controllers/gadgets_controller_spec.rb" with:
+      """
+      require "spec_helper"
+
+      require 'controllers/gadgets_controller_spec_context'
+
+      describe GadgetsController do
+        before do
+          def controller.index
+            raise AccessDenied
+          end
+        end
+
+        describe "index" do
+          it "raises AccessDenied" do
+            bypass_rescue
+            expect { get :index }.to raise_error(AccessDenied)
+          end
+        end
+      end
+      """
+    When I run `rspec spec/controllers/gadgets_controller_spec.rb`
+    Then the examples should all pass
+