rspec-rails 2.8.0.rc1 → 2.8.0.rc2

data/features/README.md

@@ -45,8 +45,6 @@ your preference to the Gemfile:
     gem "webrat"
     gem "capybara"
 
-Note that Capybara matchers are not available in view or helper specs.
-
 ## Issues
 
 The documentation for rspec-rails is a work in progress. We'll be adding

data/features/Upgrade.md

@@ -36,7 +36,7 @@ is what you need to change:
 
 ## Controller specs
 
-### islation from view templates
+### 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.

data/lib/generators/rspec/install/templates/spec/spec_helper.rb

@@ -9,7 +9,7 @@ require 'rspec/autorun'
 Dir[Rails.root.join("spec/support/**/*.rb")].each {|f| require f}
 
 RSpec.configure do |config|
-  # == Mock Framework
+  # ## Mock Framework
   #
   # If you prefer to use mocha, flexmock or RR, uncomment the appropriate line:
   #

data/lib/generators/rspec/integration/integration_generator.rb

@@ -16,6 +16,7 @@ module Rspec
 
     protected
 
+      # @deprecated Use `--webrat` instead.
       def webrat?
         RSpec.deprecate("the --webrat-matchers option", "--webrat") if options[:webrat_matchers]
         options[:webrat] || options[:webrat_matchers]

data/lib/generators/rspec/scaffold/scaffold_generator.rb

@@ -51,6 +51,7 @@ module Rspec
 
       protected
 
+        # @deprecated Use `--webrat` instead.
         def webrat?
           RSpec.deprecate("--webrat-matchers", "--webrat") if options[:webrat_matchers]
           options[:webrat] || options[:webrat_matchers]

data/lib/generators/rspec/scaffold/templates/controller_spec.rb

@@ -26,12 +26,19 @@ describe <%= controller_class_name %>Controller do
   def valid_attributes
     {}
   end
+  
+  # This should return the minimal set of values that should be in the session
+  # in order to pass any filters (e.g. authentication) defined in
+  # <%= controller_class_name %>Controller. Be sure to keep this updated too.
+  def valid_session
+    {}
+  end
 
 <% unless options[:singleton] -%>
   describe "GET index" do
     it "assigns all <%= table_name.pluralize %> as @<%= table_name.pluralize %>" do
       <%= file_name %> = <%= class_name %>.create! valid_attributes
-      get :index
+      get :index, {}, valid_session
       assigns(:<%= table_name %>).should eq([<%= file_name %>])
     end
   end
@@ -40,14 +47,14 @@ describe <%= controller_class_name %>Controller do
   describe "GET show" do
     it "assigns the requested <%= ns_file_name %> as @<%= ns_file_name %>" do
       <%= file_name %> = <%= class_name %>.create! valid_attributes
-      get :show, :id => <%= file_name %>.id
+      get :show, {:id => <%= file_name %>.to_param}, valid_session
       assigns(:<%= ns_file_name %>).should eq(<%= file_name %>)
     end
   end
 
   describe "GET new" do
     it "assigns a new <%= ns_file_name %> as @<%= ns_file_name %>" do
-      get :new
+      get :new, {}, valid_session
       assigns(:<%= ns_file_name %>).should be_a_new(<%= class_name %>)
     end
   end
@@ -55,7 +62,7 @@ describe <%= controller_class_name %>Controller do
   describe "GET edit" do
     it "assigns the requested <%= ns_file_name %> as @<%= ns_file_name %>" do
       <%= file_name %> = <%= class_name %>.create! valid_attributes
-      get :edit, :id => <%= file_name %>.id
+      get :edit, {:id => <%= file_name %>.to_param}, valid_session
       assigns(:<%= ns_file_name %>).should eq(<%= file_name %>)
     end
   end
@@ -64,18 +71,18 @@ describe <%= controller_class_name %>Controller do
     describe "with valid params" do
       it "creates a new <%= class_name %>" do
         expect {
-          post :create, :<%= ns_file_name %> => valid_attributes
+          post :create, {:<%= ns_file_name %> => valid_attributes}, valid_session
         }.to change(<%= class_name %>, :count).by(1)
       end
 
       it "assigns a newly created <%= ns_file_name %> as @<%= ns_file_name %>" do
-        post :create, :<%= ns_file_name %> => valid_attributes
+        post :create, {:<%= ns_file_name %> => valid_attributes}, valid_session
         assigns(:<%= ns_file_name %>).should be_a(<%= class_name %>)
         assigns(:<%= ns_file_name %>).should be_persisted
       end
 
       it "redirects to the created <%= ns_file_name %>" do
-        post :create, :<%= ns_file_name %> => valid_attributes
+        post :create, {:<%= ns_file_name %> => valid_attributes}, valid_session
         response.should redirect_to(<%= class_name %>.last)
       end
     end
@@ -84,14 +91,14 @@ describe <%= controller_class_name %>Controller do
       it "assigns a newly created but unsaved <%= ns_file_name %> as @<%= ns_file_name %>" do
         # Trigger the behavior that occurs when invalid params are submitted
         <%= class_name %>.any_instance.stub(:save).and_return(false)
-        post :create, :<%= ns_file_name %> => {}
+        post :create, {:<%= ns_file_name %> => {}}, valid_session
         assigns(:<%= ns_file_name %>).should be_a_new(<%= class_name %>)
       end
 
       it "re-renders the 'new' template" do
         # Trigger the behavior that occurs when invalid params are submitted
         <%= class_name %>.any_instance.stub(:save).and_return(false)
-        post :create, :<%= ns_file_name %> => {}
+        post :create, {:<%= ns_file_name %> => {}}, valid_session
         response.should render_template("new")
       end
     end
@@ -106,18 +113,18 @@ describe <%= controller_class_name %>Controller do
         # receives the :update_attributes message with whatever params are
         # submitted in the request.
         <%= class_name %>.any_instance.should_receive(:update_attributes).with(<%= params %>)
-        put :update, :id => <%= file_name %>.id, :<%= ns_file_name %> => <%= params %>
+        put :update, {:id => <%= file_name %>.to_param, :<%= ns_file_name %> => <%= params %>}, valid_session
       end
 
       it "assigns the requested <%= ns_file_name %> as @<%= ns_file_name %>" do
         <%= file_name %> = <%= class_name %>.create! valid_attributes
-        put :update, :id => <%= file_name %>.id, :<%= ns_file_name %> => valid_attributes
+        put :update, {:id => <%= file_name %>.to_param, :<%= ns_file_name %> => valid_attributes}, valid_session
         assigns(:<%= ns_file_name %>).should eq(<%= file_name %>)
       end
 
       it "redirects to the <%= ns_file_name %>" do
         <%= file_name %> = <%= class_name %>.create! valid_attributes
-        put :update, :id => <%= file_name %>.id, :<%= ns_file_name %> => valid_attributes
+        put :update, {:id => <%= file_name %>.to_param, :<%= ns_file_name %> => valid_attributes}, valid_session
         response.should redirect_to(<%= file_name %>)
       end
     end
@@ -127,7 +134,7 @@ describe <%= controller_class_name %>Controller do
         <%= file_name %> = <%= class_name %>.create! valid_attributes
         # Trigger the behavior that occurs when invalid params are submitted
         <%= class_name %>.any_instance.stub(:save).and_return(false)
-        put :update, :id => <%= file_name %>.id, :<%= ns_file_name %> => {}
+        put :update, {:id => <%= file_name %>.to_param, :<%= ns_file_name %> => {}}, valid_session
         assigns(:<%= ns_file_name %>).should eq(<%= file_name %>)
       end
 
@@ -135,7 +142,7 @@ describe <%= controller_class_name %>Controller do
         <%= file_name %> = <%= class_name %>.create! valid_attributes
         # Trigger the behavior that occurs when invalid params are submitted
         <%= class_name %>.any_instance.stub(:save).and_return(false)
-        put :update, :id => <%= file_name %>.id, :<%= ns_file_name %> => {}
+        put :update, {:id => <%= file_name %>.to_param, :<%= ns_file_name %> => {}}, valid_session
         response.should render_template("edit")
       end
     end
@@ -145,13 +152,13 @@ describe <%= controller_class_name %>Controller do
     it "destroys the requested <%= ns_file_name %>" do
       <%= file_name %> = <%= class_name %>.create! valid_attributes
       expect {
-        delete :destroy, :id => <%= file_name %>.id
+        delete :destroy, {:id => <%= file_name %>.to_param}, valid_session
       }.to change(<%= class_name %>, :count).by(-1)
     end
 
     it "redirects to the <%= table_name %> list" do
       <%= file_name %> = <%= class_name %>.create! valid_attributes
-      delete :destroy, :id => <%= file_name %>.id
+      delete :destroy, {:id => <%= file_name %>.to_param}, valid_session
       response.should redirect_to(<%= index_helper %>_url)
     end
   end

data/lib/rspec/rails/adapters.rb

@@ -7,50 +7,62 @@ module RSpec
       extend ActiveSupport::Concern
 
       module ClassMethods
+        # @api private
+        #
+        # Wraps `setup` calls from within Rails' testing framework in `before`
+        # hooks.
         def setup(*methods)
           methods.each {|method| before { send method } }
         end
 
+        # @api private
+        #
+        # Wraps `teardown` calls from within Rails' testing framework in
+        # `after` hooks.
         def teardown(*methods)
           methods.each {|method| after { send method } }
         end
       end
 
-      module InstanceMethods
-        def method_name
-          @example
-        end
+      # @api private
+      def method_name
+        @example
       end
     end
 
     module TestUnitAssertionAdapter
       extend ActiveSupport::Concern
 
-      class AssertionDelegate
-        include Test::Unit::Assertions
-      end
-
       module ClassMethods
+        # @api private
+        #
+        # Returns the names of assertion methods that we want to expose to
+        # examples without exposing non-assertion methods in Test::Unit or
+        # Minitest.
         def assertion_method_names
           Test::Unit::Assertions.public_instance_methods.select{|m| m.to_s =~ /^(assert|flunk)/} +
             [:build_message]
         end
 
+        # @api private
         def define_assertion_delegators
           assertion_method_names.each do |m|
             class_eval <<-CODE
               def #{m}(*args, &block)
-                assertion_delegate.send :#{m}, *args, &block
+                assertion_delegator.send :#{m}, *args, &block
               end
             CODE
           end
         end
       end
 
-      module InstanceMethods
-        def assertion_delegate
-          @assertion_delegate ||= AssertionDelegate.new
-        end
+      class AssertionDelegator
+        include Test::Unit::Assertions
+      end
+
+      # @api private
+      def assertion_delegator
+        @assertion_delegator ||= AssertionDelegator.new
       end
 
       included do

data/lib/rspec/rails/example/controller_example_group.rb

@@ -3,81 +3,6 @@ RSpec.configure do |config|
 end
 
 module RSpec::Rails
-  # Extends ActionController::TestCase::Behavior to work with RSpec.
-  #
-  # == Examples
-  #
-  # == with stubs
-  #
-  #   describe WidgetsController do
-  #     describe "GET index" do
-  #       it "assigns all widgets to @widgets" do
-  #         widget = stub_model(Widget)
-  #         Widget.stub(:all) { widget }
-  #         get :index
-  #         assigns(:widgets).should eq([widget])
-  #       end
-  #     end
-  #   end
-  #
-  # === with a factory
-  #
-  #   describe WidgetsController do
-  #     describe "GET index" do
-  #       it "assigns all widgets to @widgets" do
-  #         widget = Factory(:widget)
-  #         get :index
-  #         assigns(:widgets).should eq([widget])
-  #       end
-  #     end
-  #   end
-  #
-  # === with fixtures
-  #
-  #   describe WidgetsController do
-  #     describe "GET index" do
-  #       fixtures :widgets
-  #
-  #       it "assigns all widgets to @widgets" do
-  #         get :index
-  #         assigns(:widgets).should eq(Widget.all)
-  #       end
-  #     end
-  #   end
-  #
-  # == Matchers
-  #
-  # In addition to the stock matchers from rspec-expectations, controller
-  # specs add these matchers, which delegate to rails' assertions:
-  #
-  #   response.should render_template(*args)
-  #   => delegates to assert_template(*args)
-  #
-  #   response.should redirect_to(destination)
-  #   => delegates to assert_redirected_to(destination)
-  #
-  # == Isolation from views
-  #
-  # RSpec's preferred approach to spec'ing controller behaviour is to isolate
-  # the controller from its collaborators.  By default, therefore, controller
-  # example groups do not render the views in your app. Due to the way Rails
-  # searches for view templates, the template still needs to exist, but it
-  # won't actually be loaded.
-  #
-  # NOTE that this is different from rspec-rails-1 with rails-2, which did not
-  # require the presence of the file at all. Due to changes in rails-3, this
-  # was no longer feasible in rspec-rails-2.
-  #
-  # == View rendering
-  #
-  # If you prefer a more integrated approach, similar to that of Rails'
-  # functional tests, you can tell controller groups to render the views in the
-  # app with the +render_views+ declaration:
-  #
-  #   describe WidgetsController do
-  #     render_views
-  #     ...
-  #
   module ControllerExampleGroup
     extend ActiveSupport::Concern
     include RSpec::Rails::RailsExampleGroup
@@ -88,53 +13,53 @@ module RSpec::Rails
     include RSpec::Rails::Matchers::RoutingMatchers
 
     module ClassMethods
+      # @private
       def controller_class
-        describes
+        described_class
       end
 
-      # Supports a simple DSL for specifying behaviour of
-      # ApplicationController.  Creates an anonymous subclass of
-      # ApplicationController and evals the +body+ in that context. Also sets
-      # up implicit routes for this controller, that are separate from those
-      # defined in <tt>config/routes.rb</tt>.
+      # Supports a simple DSL for specifying behavior of ApplicationController.
+      # Creates an anonymous subclass of ApplicationController and evals the
+      # `body` in that context. Also sets up implicit routes for this
+      # controller, that are separate from those defined in "config/routes.rb".
       #
-      # == Examples
+      # @note Due to Ruby 1.8 scoping rules in anoymous subclasses, constants
+      #   defined in `ApplicationController` must be fully qualified (e.g.
+      #   `ApplicationController::AccessDenied`) in the block passed to the
+      #   `controller` method. Any instance methods, filters, etc, that are
+      #   defined in `ApplicationController`, however, are accessible from
+      #   within the block.
       #
-      #    describe ApplicationController do
-      #      controller do
-      #        def index
-      #          raise ApplicationController::AccessDenied
-      #        end
-      #      end
+      # @example
       #
-      #      describe "handling AccessDenied exceptions" do
-      #        it "redirects to the /401.html page" do
-      #          get :index
-      #          response.should redirect_to("/401.html")
-      #        end
-      #      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
+      #           response.should redirect_to("/401.html")
+      #         end
+      #       end
+      #     end
       #
       # If you would like to spec a subclass of ApplicationController, call
       # controller like so:
       #
-      #    controller(ApplicationControllerSubclass) do
-      #      # ....
-      #    end
-      #
-      # NOTICE: Due to Ruby 1.8 scoping rules in anoymous subclasses, constants
-      # defined in +ApplicationController+ must be fully qualified (e.g.
-      # ApplicationController::AccessDenied) in the block passed to the
-      # +controller+ method. Any instance methods, filters, etc, that are
-      # defined in +ApplicationController+, however, are accessible from within
-      # the block.
+      #     controller(ApplicationControllerSubclass) do
+      #       # ....
+      #     end
       def controller(base_class = nil, &body)
         base_class ||= RSpec.configuration.infer_base_class_for_anonymous_controllers? ?
                          controller_class :
                          ApplicationController
 
-        metadata[:example_group][:describes] = Class.new(base_class, &body)
-        metadata[:example_group][:describes].singleton_class.class_eval do
+        metadata[:example_group][:described_class] = Class.new(base_class, &body)
+        metadata[:example_group][:described_class].singleton_class.class_eval do
           def name; "AnonymousController" end
         end
 
@@ -149,25 +74,43 @@ module RSpec::Rails
       end
     end
 
-    module InstanceMethods
-      attr_reader :controller, :routes
+    attr_reader :controller, :routes
 
-      module BypassRescue
-        def rescue_with_handler(exception)
-          raise exception
-        end
+    module BypassRescue
+      def rescue_with_handler(exception)
+        raise exception
       end
+    end
 
-      def bypass_rescue
-        controller.extend(BypassRescue)
-      end
+    # Extends the controller with a module that overrides
+    # `rescue_with_handler` to raise the exception passed to it.  Use this to
+    # specify that an action _should_ raise an exception given appropriate
+    # conditions.
+    #
+    # @example
+    #
+    #     describe ProfilesController do
+    #       it "raises a 403 when a non-admin user tries to view another user's profile" do
+    #         profile = create_profile
+    #         login_as profile.user
+    #
+    #         expect do
+    #           bypass_rescue
+    #           get :show, :id => profile.id + 1
+    #         end.to raise_error(/403 Forbidden/)
+    #       end
+    #     end
+    def bypass_rescue
+      controller.extend(BypassRescue)
+    end
 
-      def method_missing(method, *args, &block)
-        if @orig_routes && @orig_routes.named_routes.helpers.include?(method)
-          controller.send(method, *args, &block)
-        else
-          super
-        end
+    # If method is a named_route, delegates to the RouteSet associated with
+    # this controller.
+    def method_missing(method, *args, &block)
+      if @orig_routes && @orig_routes.named_routes.helpers.include?(method)
+        controller.send(method, *args, &block)
+      else
+        super
       end
     end