Permit matcher now supports subparameters

NEWS.md

@@ -52,13 +52,25 @@
   vein, passing a pluralized version of the attribute name to `define_enum_for`
   would erroneously pass, and now it fails. ([#641])
 
+* Fix `permit` so that it does not break the functionality of
+  ActionController::Parameters#require. ([#648], [#675])
+
+### Features
+
+* Add `on` qualifier to `permit`. This allows you to make an assertion that
+  a restriction was placed on a slice of the `params` hash and not the entire
+  `params` hash. Although we don't require you to use this qualifier, we do
+  recommend it, as it's a more precise check. ([#675])
+
 [#402]: https://github.com/thoughtbot/shoulda-matchers/pull/402
 [#587]: https://github.com/thoughtbot/shoulda-matchers/pull/587
 [#662]: https://github.com/thoughtbot/shoulda-matchers/pull/662
 [#554]: https://github.com/thoughtbot/shoulda-matchers/pull/554
 [#641]: https://github.com/thoughtbot/shoulda-matchers/pull/641
 [#521]: https://github.com/thoughtbot/shoulda-matchers/pull/521
 [#607]: https://github.com/thoughtbot/shoulda-matchers/pull/607
+[#648]: https://github.com/thoughtbot/shoulda-matchers/pull/648
+[#675]: https://github.com/thoughtbot/shoulda-matchers/pull/675
 
 # 2.8.0
 

lib/shoulda/matchers/action_controller/permit_matcher.rb

@@ -38,14 +38,16 @@ module ActionController
       #     describe UsersController do
       #       it do
       #         should permit(:first_name, :last_name, :email, :password).
-      #           for(:create)
+      #           for(:create).
+      #           on(:user)
       #       end
       #     end
       #
       #     # Test::Unit
       #     class UsersControllerTest < ActionController::TestCase
       #       should permit(:first_name, :last_name, :email, :password).
-      #         for(:create)
+      #         for(:create).
+      #         on(:user)
       #     end
       #
       # If your action requires query parameters in order to work, then you'll
@@ -82,7 +84,8 @@ module ActionController
       #
       #       it do
       #         should permit(:first_name, :last_name, :email, :password).
-      #           for(:update, params: { id: 1 })
+      #           for(:update, params: { id: 1 }).
+      #           on(:user)
       #       end
       #     end
       #
@@ -93,7 +96,8 @@ module ActionController
       #       end
       #
       #       should permit(:first_name, :last_name, :email, :password).
-      #         for(:update, params: { id: 1 })
+      #         for(:update, params: { id: 1 }).
+      #         on(:user)
       #     end
       #
       # Finally, if you have an action that isn't one of the seven resourceful
@@ -132,10 +136,9 @@ module ActionController
       #       end
       #
       #       it do
-      #         should permit(:activated).for(:toggle,
-      #           params: { id: 1 },
-      #           verb: :put
-      #         )
+      #         should permit(:activated).
+      #           for(:toggle, params: { id: 1 }, verb: :put).
+      #           on(:user)
       #       end
       #     end
       #
@@ -145,10 +148,9 @@ module ActionController
       #         create(:user, id: 1)
       #       end
       #
-      #       should permit(:activated).for(:toggle,
-      #         params: { id: 1 },
-      #         verb: :put
-      #       )
+      #       should permit(:activated).
+      #         for(:toggle, params: { id: 1 }, verb: :put).
+      #         on(:user)
       #     end
       #
       # @return [PermitMatcher]
@@ -162,11 +164,12 @@ class PermitMatcher
         attr_writer :stubbed_params
 
         def initialize(expected_permitted_params)
+          @expected_permitted_params = expected_permitted_params
           @action = nil
           @verb = nil
           @request_params = {}
-          @expected_permitted_params = expected_permitted_params
-          set_double_collection
+          @subparameter = nil
+          @parameters_doubles = ParametersDoubles.new
         end
 
         def for(action, options = {})
@@ -176,19 +179,32 @@ def for(action, options = {})
           self
         end
 
+        def add_params(params)
+          request_params.merge!(params)
+          self
+        end
+
+        def on(subparameter)
+          @subparameter = subparameter
+          @parameters_doubles = SliceOfParametersDoubles.new(subparameter)
+          self
+        end
+
         def in_context(context)
           @context = context
           self
         end
 
         def description
-          "permit #{verb.upcase} ##{action} to receive parameters #{param_names_as_sentence}"
+          "(on #{verb.upcase} ##{action}) " + expectation
         end
 
         def matches?(controller)
           @controller = controller
           ensure_action_and_verb_present!
 
+          parameters_doubles.register
+
           Doublespeak.with_doubles_activated do
             context.__send__(verb, action, request_params)
           end
@@ -197,32 +213,49 @@ def matches?(controller)
         end
 
         def failure_message
-          "Expected controller to permit #{unpermitted_params.to_sentence}, but it did not."
+          "Expected #{verb.upcase} ##{action} to #{expectation},\nbut #{reality}."
         end
         alias failure_message_for_should failure_message
 
         def failure_message_when_negated
-          "Expected controller not to permit #{verified_permitted_params.to_sentence}, but it did."
+          "Expected #{verb.upcase} ##{action} not to #{expectation},\nbut it did."
         end
         alias failure_message_for_should_not failure_message_when_negated
 
         protected
 
-        attr_reader :controller, :double_collection, :action, :verb,
-          :request_params, :expected_permitted_params, :context
+        attr_reader :controller, :double_collections_by_param, :action, :verb,
+          :request_params, :expected_permitted_params, :context, :subparameter,
+          :parameters_doubles
+
+        def expectation
+          message = 'restrict parameters '
+
+          if subparameter
+            message << " for #{subparameter.inspect}"
+          end
+
+          message << 'to ' + format_param_names(expected_permitted_params)
 
-        def set_double_collection
-          @double_collection =
-            Doublespeak.double_collection_for(::ActionController::Parameters)
+          message
+        end
 
-          @double_collection.register_stub(:require).to_return(&:object)
-          @double_collection.register_proxy(:permit)
+        def reality
+          if actual_permitted_params.empty?
+            'it did not restrict any parameters'
+          else
+            'the restricted parameters were ' +
+              format_param_names(actual_permitted_params) +
+              ' instead'
+          end
+        end
+
+        def format_param_names(param_names)
+          param_names.map(&:inspect).to_sentence
         end
 
         def actual_permitted_params
-          double_collection.calls_to(:permit).inject([]) do |all_param_names, call|
-            all_param_names + call.args
-          end.flatten
+          parameters_doubles.permitted_params
         end
 
         def permit_called?
@@ -258,6 +291,90 @@ def param_names_as_sentence
           expected_permitted_params.map(&:inspect).to_sentence
         end
 
+        # @private
+        class ParametersDoubles
+          def self.permitted_params_within(double_collection)
+            double_collection.calls_to(:permit).map(&:args).flatten
+          end
+
+          def initialize
+            klass = ::ActionController::Parameters
+            @double_collection = Doublespeak.double_collection_for(klass)
+          end
+
+          def register
+            double_collection.register_proxy(:permit)
+          end
+
+          def permitted_params
+            ParametersDoubles.permitted_params_within(double_collection)
+          end
+
+          protected
+
+          attr_reader :double_collection
+        end
+
+        # @private
+        class SliceOfParametersDoubles
+          TOP_LEVEL = Object.new
+
+          def initialize(subparameter)
+            klass = ::ActionController::Parameters
+
+            @subparameter = subparameter
+            @double_collections_by_param = {
+              TOP_LEVEL => Doublespeak.double_collection_for(klass)
+            }
+          end
+
+          def register
+            top_level_collection = double_collections_by_param[TOP_LEVEL]
+            double_permit_on(top_level_collection)
+            double_require_on(top_level_collection)
+          end
+
+          def permitted_params
+            if double_collections_by_param.key?(subparameter)
+              ParametersDoubles.permitted_params_within(
+                double_collections_by_param[subparameter]
+              )
+            else
+              []
+            end
+          end
+
+          protected
+
+          attr_reader :subparameter, :double_collections_by_param
+
+          private
+
+          def double_permit_on(double_collection)
+            double_collection.register_proxy(:permit)
+          end
+
+          def double_require_on(double_collection)
+            double_collections_by_param = @double_collections_by_param
+            require_double = double_collection.register_proxy(:require)
+
+            require_double.to_return do |call|
+              param_name = call.args.first
+              params = call.return_value
+              double_collections_by_param[param_name] ||=
+                double_permit_against(params)
+            end
+          end
+
+          def double_permit_against(params)
+            klass = params.singleton_class
+
+            Doublespeak.double_collection_for(klass).tap do |double_collection|
+              double_permit_on(double_collection)
+            end
+          end
+        end
+
         # @private
         class ActionNotDefinedError < StandardError
           def message

lib/shoulda/matchers/doublespeak.rb

@@ -13,6 +13,16 @@ class << self
         def world
           @_world ||= World.new
         end
+
+        def debugging_enabled?
+          ENV['DEBUG_DOUBLESPEAK'] == '1'
+        end
+
+        def debug(&block)
+          if debugging_enabled?
+            puts block.call
+          end
+        end
       end
     end
   end