shoulda-matchers 2.6.1 → 2.6.2

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

@@ -1,6 +1,7 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
+    module ActionController
+      # @private
       class RouteParams
         def initialize(args)
           @args = args
@@ -14,7 +15,7 @@ module Shoulda # :nodoc:
           end
         end
 
-        private
+        protected
 
         attr_reader :args
 

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

@@ -1,21 +1,79 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-
-      # Ensures that a session key was set to the expected value.
+    module ActionController
+      # The `set_session` matcher is used to make assertions about the
+      # `session` hash.
+      #
+      #     class PostsController < ApplicationController
+      #       def show
+      #         session[:foo] = 'bar'
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #show' do
+      #         before { get :show }
+      #
+      #         it { should set_session(:foo) }
+      #         it { should_not set_session(:baz) }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #show' do
+      #         setup { get :show }
+      #
+      #         should set_session(:foo)
+      #         should_not set_session(:baz)
+      #       end
+      #     end
+      #
+      # #### Qualifiers
+      #
+      # ##### to
+      #
+      # Use `to` to assert that the key in the session hash was set to a
+      # particular value.
       #
-      # Example:
+      #     class PostsController < ApplicationController
+      #       def show
+      #         session[:foo] = 'bar'
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #show' do
+      #         before { get :show }
+      #
+      #         it { should set_session(:foo).to('bar') }
+      #         it { should_not set_session(:foo).to('something else') }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #show' do
+      #         setup { get :show }
+      #
+      #         should set_session(:foo).to('bar')
+      #         should_not set_session(:foo).to('something else')
+      #       end
+      #     end
+      #
+      # @return [SetSessionMatcher]
       #
-      #   it { should set_session(:message) }
-      #   it { should set_session(:user_id).to(@user.id) }
-      #   it { should_not set_session(:user_id) }
       def set_session(key)
         SetSessionMatcher.new(key)
       end
 
-      class SetSessionMatcher # :nodoc:
+      # @private
+      class SetSessionMatcher
         def initialize(key)
           @key = key.to_s
+          @value_block = nil
         end
 
         def to(value = nil, &block)
@@ -57,6 +115,10 @@ module Shoulda # :nodoc:
 
         private
 
+        def value_or_default_value
+          defined?(@value) && @value
+        end
+
         def assigned_value?
           !assigned_value.nil?
         end
@@ -67,10 +129,10 @@ module Shoulda # :nodoc:
 
         def assigned_correct_value?
           if assigned_value?
-            if @value.nil?
+            if value_or_default_value.nil?
               true
             else
-              assigned_value == @value
+              assigned_value == value_or_default_value
             end
           end
         end
@@ -81,8 +143,9 @@ module Shoulda # :nodoc:
 
         def expectation
           expectation = "session variable #{@key} to be set"
-          if @value
-            expectation << " to #{@value.inspect}"
+
+          if value_or_default_value
+            expectation << " to #{value_or_default_value.inspect}"
           end
         end
 

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

@@ -1,25 +1,159 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActionController # :nodoc:
-
-      # Ensures that the flash contains the given value. Can be a String, a
-      # Regexp, or nil (indicating that the flash should not be set).
+    module ActionController
+      # The `set_the_flash` matcher is used to make assertions about the
+      # `flash` hash.
+      #
+      #     class PostsController < ApplicationController
+      #       def index
+      #         flash[:foo] = 'A candy bar'
+      #       end
+      #
+      #       def destroy
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #index' do
+      #         before { get :index }
+      #
+      #         it { should set_the_flash }
+      #       end
+      #
+      #       describe 'DELETE #destroy' do
+      #         before { delete :destroy }
+      #
+      #         it { should_not set_the_flash }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #index' do
+      #         setup { get :index }
+      #
+      #         should set_the_flash
+      #       end
+      #
+      #       context 'DELETE #destroy' do
+      #         setup { delete :destroy }
+      #
+      #         should_not set_the_flash
+      #       end
+      #     end
+      #
+      # #### Qualifiers
+      #
+      # ##### []
+      #
+      # Use `[]` to narrow the scope of the matcher to a particular key.
+      #
+      #     class PostsController < ApplicationController
+      #       def index
+      #         flash[:foo] = 'A candy bar'
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #index' do
+      #         before { get :index }
+      #
+      #         it { should set_the_flash[:foo] }
+      #         it { should_not set_the_flash[:bar] }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #index' do
+      #         setup { get :show }
+      #
+      #         should set_the_flash[:foo]
+      #         should_not set_the_flash[:bar]
+      #       end
+      #     end
+      #
+      # ##### to
+      #
+      # Use `to` to assert that some key was set to a particular value, or that
+      # some key matches a particular regex.
+      #
+      #     class PostsController < ApplicationController
+      #       def index
+      #         flash[:foo] = 'A candy bar'
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #index' do
+      #         before { get :index }
+      #
+      #         it { should set_the_flash.to('A candy bar') }
+      #         it { should set_the_flash.to(/bar/) }
+      #         it { should set_the_flash[:foo].to('bar') }
+      #         it { should_not set_the_flash[:foo].to('something else') }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #index' do
+      #         setup { get :show }
+      #
+      #         should set_the_flash.to('A candy bar')
+      #         should set_the_flash.to(/bar/)
+      #         should set_the_flash[:foo].to('bar')
+      #         should_not set_the_flash[:foo].to('something else')
+      #       end
+      #     end
+      #
+      # ##### now
+      #
+      # Use `now` to change the scope of the matcher to use the "now" hash
+      # instead of the usual "future" hash.
+      #
+      #     class PostsController < ApplicationController
+      #       def show
+      #         flash.now[:foo] = 'bar'
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe PostsController do
+      #       describe 'GET #show' do
+      #         before { get :show }
+      #
+      #         it { should set_the_flash.now }
+      #         it { should set_the_flash[:foo].now }
+      #         it { should set_the_flash[:foo].to('bar').now }
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostsControllerTest < ActionController::TestCase
+      #       context 'GET #index' do
+      #         setup { get :show }
+      #
+      #         should set_the_flash.now
+      #         should set_the_flash[:foo].now
+      #         should set_the_flash[:foo].to('bar').now
+      #       end
+      #     end
       #
-      # Example:
+      # @return [SetTheFlashMatcher]
       #
-      #   it { should set_the_flash }
-      #   it { should set_the_flash.to('Thank you for placing this order.') }
-      #   it { should set_the_flash.to(/created/i) }
-      #   it { should set_the_flash[:alert].to('Password does not match') }
-      #   it { should set_the_flash.to(/logged in/i).now }
-      #   it { should_not set_the_flash }
       def set_the_flash
         SetTheFlashMatcher.new
       end
 
-      class SetTheFlashMatcher # :nodoc:
+      # @private
+      class SetTheFlashMatcher
         def initialize
           @options = {}
+          @value = nil
         end
 
         def to(value)

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

@@ -10,10 +10,154 @@ require 'active_support/hash_with_indifferent_access'
 module Shoulda
   module Matchers
     module ActionController
+      # The `permit` matcher tests that an action in your controller receives a
+      # whitelist of parameters using Rails' Strong Parameters feature
+      # (specifically that `permit` was called with the correct arguments).
+      #
+      # Here's an example:
+      #
+      #     class UsersController < ApplicationController
+      #       def create
+      #         user = User.create(user_params)
+      #         # ...
+      #       end
+      #
+      #       private
+      #
+      #       def user_params
+      #         params.require(:user).permit(
+      #           :first_name,
+      #           :last_name,
+      #           :email,
+      #           :password
+      #         )
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe UsersController do
+      #       it do
+      #         should permit(:first_name, :last_name, :email, :password).
+      #           for(:create)
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UsersControllerTest < ActionController::TestCase
+      #       should permit(:first_name, :last_name, :email, :password).
+      #         for(:create)
+      #     end
+      #
+      # If your action requires query parameters in order to work, then you'll
+      # need to supply them:
+      #
+      #     class UsersController < ApplicationController
+      #       def update
+      #         user = User.find(params[:id])
+      #
+      #         if user.update_attributes(user_params)
+      #           # ...
+      #         else
+      #           # ...
+      #         end
+      #       end
+      #
+      #       private
+      #
+      #       def user_params
+      #         params.require(:user).permit(
+      #           :first_name,
+      #           :last_name,
+      #           :email,
+      #           :password
+      #         )
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe UsersController do
+      #       before do
+      #         create(:user, id: 1)
+      #       end
+      #
+      #       it do
+      #         should permit(:first_name, :last_name, :email, :password).
+      #           for(:update, params: { id: 1 })
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UsersControllerTest < ActionController::TestCase
+      #       setup do
+      #         create(:user, id: 1)
+      #       end
+      #
+      #       should permit(:first_name, :last_name, :email, :password).
+      #         for(:update, params: { id: 1 })
+      #     end
+      #
+      # Finally, if you have an action that isn't one of the seven resourceful
+      # actions, then you'll need to provide the HTTP verb that it responds to:
+      #
+      #     Rails.application.routes.draw do
+      #       resources :users do
+      #         member do
+      #           put :toggle
+      #         end
+      #       end
+      #     end
+      #
+      #     class UsersController < ApplicationController
+      #       def toggle
+      #         user = User.find(params[:id])
+      #
+      #         if user.update_attributes(user_params)
+      #           # ...
+      #         else
+      #           # ...
+      #         end
+      #       end
+      #
+      #       private
+      #
+      #       def user_params
+      #         params.require(:user).permit(:activated)
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe UsersController do
+      #       before do
+      #         create(:user, id: 1)
+      #       end
+      #
+      #       it do
+      #         should permit(:activated).for(:toggle,
+      #           params: { id: 1 },
+      #           verb: :put
+      #         )
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UsersControllerTest < ActionController::TestCase
+      #       setup do
+      #         create(:user, id: 1)
+      #       end
+      #
+      #       should permit(:activated).for(:toggle,
+      #         params: { id: 1 },
+      #         verb: :put
+      #       )
+      #     end
+      #
+      # @return [StrongParametersMatcher]
+      #
       def permit(*params)
         StrongParametersMatcher.new(params).in_context(self)
       end
 
+      # @private
       class StrongParametersMatcher
         attr_writer :stubbed_params
 
@@ -62,14 +206,14 @@ module Shoulda
         end
         alias failure_message_for_should_not failure_message_when_negated
 
-        private
+        protected
 
         attr_reader :controller, :double_collection, :action, :verb,
           :request_params, :expected_permitted_params, :context
 
         def set_double_collection
           @double_collection =
-            Doublespeak.register_double_collection(::ActionController::Parameters)
+            Doublespeak.double_collection_for(::ActionController::Parameters)
 
           @double_collection.register_stub(:require).to_return { |params| params }
           @double_collection.register_proxy(:permit)
@@ -114,12 +258,14 @@ module Shoulda
           expected_permitted_params.map(&:inspect).to_sentence
         end
 
+        # @private
         class ActionNotDefinedError < StandardError
           def message
             'You must specify the controller action using the #for method.'
           end
         end
 
+        # @private
         class VerbNotDefinedError < StandardError
           def message
             'You must specify an HTTP verb when using a non-RESTful action. For example: for(:authorize, verb: :post)'