shoulda-matchers 2.6.1 → 2.6.2

data/lib/shoulda/matchers/action_controller/render_template_matcher.rb

@@ -1,25 +1,49 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-      # Ensures a controller rendered the given template.
+    module ActionController
+      # The `render_template` matcher tests that an action renders a template
+      # or partial. In RSpec, it is very similar to rspec-rails's
+      # `render_template` matcher. In Test::Unit, it provides a more expressive
+      # syntax over `assert_template`.
       #
-      # Example:
+      #     class PostsController < ApplicationController
+      #       def show
+      #       end
+      #     end
       #
-      #   it { should render_template(:show)  }
+      #     # app/views/posts/show.html.erb
+      #     <%= render 'sidebar' %>
       #
-      #   assert that the "_customer" partial was rendered
-      #   it { should render_template(partial: '_customer')  }
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #show' do
+      #         before { get :show }
       #
-      #   assert that the "_customer" partial was rendered twice
-      #   it { should render_template(partial: '_customer', count: 2)  }
+      #         it { should render_template('show') }
+      #         it { should render_template(partial: 'sidebar') }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #show' do
+      #         setup { get :show }
+      #
+      #         should render_template('show')
+      #         should render_template(partial: 'sidebar')
+      #       end
+      #     end
+      #
+      # 
+      #
+      # @return [RenderTemplateMatcher]
       #
-      #   assert that no partials were rendered
-      #   it { should render_template(partial: false)  }
       def render_template(options = {}, message = nil)
         RenderTemplateMatcher.new(options, message, self)
       end
 
-      class RenderTemplateMatcher # :nodoc:
+      # @private
+      class RenderTemplateMatcher
         attr_reader :failure_message, :failure_message_when_negated
 
         alias failure_message_for_should failure_message
@@ -29,7 +53,10 @@ module Shoulda # :nodoc:
           @options = options
           @message = message
           @template = options.is_a?(Hash) ? options[:partial] : options
-          @context  = context
+          @context = context
+          @controller = nil
+          @failure_message = nil
+          @failure_message_when_negated = nil
         end
 
         def matches?(controller)

data/lib/shoulda/matchers/action_controller/render_with_layout_matcher.rb

@@ -1,24 +1,76 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-
-      # Ensures that the controller rendered with the given layout.
+    module ActionController
+      # The `render_with_layout` matcher asserts that an action is rendered with
+      # a particular layout.
+      #
+      #     class PostsController < ApplicationController
+      #       def show
+      #         render layout: 'posts'
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #show' do
+      #         before { get :show }
+      #
+      #         it { should render_with_layout('posts') }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #show' do
+      #         setup { get :show }
+      #
+      #         should render_with_layout('posts')
+      #       end
+      #     end
+      #
+      # It can also be used to assert that the action is not rendered with a
+      # layout at all:
+      #
+      #     class PostsController < ApplicationController
+      #       def sidebar
+      #         render layout: false
+      #       end
+      #     end
       #
-      # Example:
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #sidebar' do
+      #         before { get :sidebar }
+      #
+      #         it { should_not render_with_layout }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #sidebar' do
+      #         setup { get :sidebar }
+      #
+      #         should_not render_with_layout
+      #       end
+      #     end
+      #
+      # @return [RenderWithLayoutMatcher]
       #
-      #   it { should render_with_layout }
-      #   it { should render_with_layout(:special) }
-      #   it { should_not render_with_layout }
       def render_with_layout(expected_layout = nil)
         RenderWithLayoutMatcher.new(expected_layout).in_context(self)
       end
 
-      class RenderWithLayoutMatcher # :nodoc:
-
+      # @private
+      class RenderWithLayoutMatcher
         def initialize(expected_layout)
-          unless expected_layout.nil?
+          if expected_layout
             @expected_layout = expected_layout.to_s
+          else
+            @expected_layout = nil
           end
+
+          @controller = nil
         end
 
         # Used to provide access to layouts recorded by

data/lib/shoulda/matchers/action_controller/rescue_from_matcher.rb

@@ -1,13 +1,46 @@
 module Shoulda
   module Matchers
     module ActionController
+      # The `rescue_from` matcher tests usage of the `rescue_from` macro. It
+      # asserts that an exception and method are present in the list of
+      # exception handlers, and that the handler method exists.
+      #
+      #     class ApplicationController < ActionController::Base
+      #       rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
+      #
+      #       private
+      #
+      #       def handle_not_found
+      #         # ...
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe ApplicationController do
+      #       it do
+      #         should rescue_from(ActiveRecord::RecordNotFound).
+      #           with(:handle_not_found)
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class ApplicationControllerTest < ActionController::TestCase
+      #       should rescue_from(ActiveRecord::RecordNotFound).
+      #         with(:handle_not_found)
+      #     end
+      #
+      # @return [RescueFromMatcher]
+      #
       def rescue_from(exception)
         RescueFromMatcher.new exception
       end
 
+      # @private
       class RescueFromMatcher
         def initialize(exception)
           @exception = exception
+          @expected_method = nil
+          @controller = nil
         end
 
         def with(method)
@@ -36,7 +69,7 @@ module Shoulda
         end
         alias failure_message_for_should_not failure_message_when_negated
 
-        private
+        protected
 
         attr_reader :controller, :exception, :expected_method, :handlers
 

data/lib/shoulda/matchers/action_controller/respond_with_matcher.rb

@@ -1,26 +1,95 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-
-      # Ensures a controller responded with expected 'response' status code.
+    module ActionController
+      # The `respond_with` matcher tests that an action responds with a certain
+      # status code.
+      #
+      # You can specify that the status should be a number:
+      #
+      #     class PostsController < ApplicationController
+      #       def index
+      #         render status: 403
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #index' do
+      #         before { get :index }
+      #
+      #         it { should respond_with(403) }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #index' do
+      #         setup { get :index }
+      #
+      #         should respond_with(403)
+      #       end
+      #     end
+      #
+      # You can specify that the status should be within a range of numbers:
+      #
+      #     class PostsController < ApplicationController
+      #       def destroy
+      #         render status: 508
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'DELETE #destroy' do
+      #         before { delete :destroy }
       #
-      # You can pass an explicit status number like 200, 301, 404, 500
-      # or its symbolic equivalent :success, :redirect, :missing, :error.
-      # See ActionController::StatusCodes for a full list.
+      #         it { should respond_with(500..600) }
+      #       end
+      #     end
       #
-      # Example:
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'DELETE #destroy' do
+      #         setup { delete :destroy }
+      #
+      #         should respond_with(500..600)
+      #       end
+      #     end
+      #
+      # Finally, you can specify that the status should be a symbol:
+      #
+      #     class PostsController < ApplicationController
+      #       def show
+      #         render status: :locked
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #show' do
+      #         before { get :show }
+      #
+      #         it { should respond_with(:locked) }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #show' do
+      #         setup { get :show }
+      #
+      #         should respond_with(:locked)
+      #       end
+      #     end
+      #
+      # @return [RespondWithMatcher]
       #
-      #   it { should respond_with(:success)  }
-      #   it { should respond_with(:redirect) }
-      #   it { should respond_with(:missing)  }
-      #   it { should respond_with(:error)    }
-      #   it { should respond_with(501)       }
       def respond_with(status)
         RespondWithMatcher.new(status)
       end
 
-      class RespondWithMatcher # :nodoc:
-
+      # @private
+      class RespondWithMatcher
         def initialize(status)
           @status = symbol_to_status_code(status)
         end

data/lib/shoulda/matchers/action_controller/route_matcher.rb

@@ -1,36 +1,92 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-
-      # Ensures that requesting +path+ using +method+ routes to +options+.
-      #
-      # If you don't specify a controller, it will use the controller from the
-      # example group.
-      #
-      # +to_param+ is called on the +options+ given.
-      #
-      # Examples:
-      #
-      #   it { should route(:get, '/posts').
-      #                 to(controller: :posts, action: :index) }
-      #   it { should route(:get, '/posts').to('posts#index') }
-      #   it { should route(:get, '/posts/new').to(action: :new) }
-      #   it { should route(:post, '/posts').to(action: :create) }
-      #   it { should route(:get, '/posts/1').to(action: :show, id: 1) }
-      #   it { should route(:get, '/posts/1').to('posts#show', id: 1) }
-      #   it { should route(:get, '/posts/1/edit').to(action: :edit, id: 1) }
-      #   it { should route(:put, '/posts/1').to(action: :update, id: 1) }
-      #   it { should route(:delete, '/posts/1').
-      #                 to(action: :destroy, id: 1) }
-      #   it { should route(:get, '/users/1/posts/1').
-      #                 to(action: :show, id: 1, user_id: 1) }
-      #   it { should route(:get, '/users/1/posts/1').
-      #                 to('posts#show', id: 1, user_id: 1) }
+    module ActionController
+      # The `route` matcher tests that a route resolves to a controller,
+      # action, and params; and that the controller, action, and params
+      # generates the same route. For an RSpec suite, this is like using a
+      # combination of `route_to` and `be_routable`. For a Test::Unit suite, it
+      # provides a more expressive syntax over `assert_routing`.
+      #
+      # You can use this matcher either in a controller test case or in a
+      # routing test case. For instance, given these routes:
+      #
+      #     My::Application.routes.draw do
+      #       get '/posts', controller: 'posts', action: 'index'
+      #       get '/posts/:id' => 'posts#show'
+      #     end
+      #
+      # You could choose to write tests for these routes alongside other tests
+      # for PostsController:
+      #
+      #     class PostsController < ApplicationController
+      #       # ...
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       it { should route(:get, '/posts').to(action: :index) }
+      #       it { should route(:get, '/posts/1').to(action: :show, id: 1) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       should route(:get, '/posts').to(action: 'index')
+      #       should route(:get, '/posts/1').to(action: :show, id: 1)
+      #     end
+      #
+      # Or you could place the tests along with other route tests:
+      #
+      #     # RSpec
+      #     describe 'Routing' do
+      #       it do
+      #         should route(:get, '/posts').
+      #           to(controller: :posts, action: :index)
+      #       end
+      #
+      #       it do
+      #         should route(:get, '/posts/1').
+      #           to('posts#show', id: 1)
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class RoutesTest < ActionController::IntegrationTest
+      #       should route(:get, '/posts').
+      #         to(controller: :posts, action: :index)
+      #
+      #       should route(:get, '/posts/1').
+      #         to('posts#show', id: 1)
+      #     end
+      #
+      # Notice that in the former case, as we are inside of a test case for
+      # PostsController, we do not have to specify that the routes resolve to
+      # this controller. In the latter case we specify this using the
+      # `controller` key passed to the `to` qualifier.
+      #
+      # #### Qualifiers
+      #
+      # ##### to
+      #
+      # Use `to` to specify the action (along with the controller, if needed)
+      # that the route resolves to.
+      #
+      #     # Three ways of saying the same thing (using the example above)
+      #     route(:get, '/posts').to(action: index)
+      #     route(:get, '/posts').to(controller: :posts, action: index)
+      #     route(:get, '/posts').to('posts#index')
+      #
+      # If there are parameters in your route, then specify those too:
+      #
+      #     route(:get, '/posts/1').to('posts#show', id: 1)
+      #
+      # @return [RouteMatcher]
+      #
       def route(method, path)
         RouteMatcher.new(method, path, self)
       end
 
-      class RouteMatcher # :nodoc:
+      # @private
+      class RouteMatcher
         def initialize(method, path, context)
           @method  = method
           @path    = path