pundit-matchers 2.2.0 → 3.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '013960778421a77229a9e50388f5cb7073cae3c60024b482f48c39431de063af'
-  data.tar.gz: 12a70d9a7ffdf1df5a2e584e555f3f934d36a971852605afa611c033a07c14dc
+  metadata.gz: 96b6768ee2dad9c91d75c12506f76d530b9b6052fc8d8b09c6fdaa56f88d1748
+  data.tar.gz: a2e24ef15671dec4fd9820ef5f61029499d16fd56a726be2dcdd5892dc02088f
 SHA512:
-  metadata.gz: 4c00b1be800433a24203f2d964a810eaa7445ed98934598726e568b727db2ad6333886d1d7dffe56196a1bb445a982c6d17ea96cda737cca5a5ca7e801445ada
-  data.tar.gz: 0fb59915496d8b6807b01b84ce6f70c2c350e5dd6db00851c1e013211fb6ab41c6a1cc2f21c11f0a10107f116dadd666ff71228bcf06eee1ed706a90b56d9550
+  metadata.gz: 0aa08b14749957cdeb61631b97712288eb9207201197e35f303892ab90730c5dd1fdd736f01f9d84e1c6665131d79d5a5bdc1028e2f6d4b34e875e5850e71871
+  data.tar.gz: 4fab87c430012868c5274767a5bc4d75da673e3c7637ea544d83eb244604548c17be7a21cea94617b940b42bfabc9b2f4c8fc6ab6682e18d55d2a527f5afba61

data/lib/pundit/matchers/actions_matcher.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base_matcher'
+
+module Pundit
+  module Matchers
+    # This is the base action matcher class. Matchers related to actions should inherit from this class.
+    class ActionsMatcher < BaseMatcher
+      # Error message when actions are not implemented in a policy.
+      ACTIONS_NOT_IMPLEMENTED_ERROR = "'%<policy>s' does not implement %<actions>s"
+      # Error message when at least one action must be specified.
+      ARGUMENTS_REQUIRED_ERROR = 'At least one action must be specified'
+
+      # Initializes a new instance of the ActionsMatcher class.
+      #
+      # @param expected_actions [Array<String, Symbol>] The expected actions to be checked.
+      #
+      # @raise [ArgumentError] If no actions are specified.
+      def initialize(*expected_actions)
+        raise ArgumentError, ARGUMENTS_REQUIRED_ERROR if expected_actions.empty?
+
+        super()
+        @expected_actions = expected_actions.flatten.map(&:to_sym).sort
+      end
+
+      private
+
+      attr_reader :expected_actions
+
+      def check_actions!
+        missing_actions = expected_actions - policy_info.actions
+        return if missing_actions.empty?
+
+        raise ArgumentError, format(
+          ACTIONS_NOT_IMPLEMENTED_ERROR,
+          policy: policy_info, actions: missing_actions
+        )
+      end
+    end
+  end
+end

data/lib/pundit/matchers/attributes_matcher.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'base_matcher'
+
+module Pundit
+  module Matchers
+    # The AttributesMatcher class is used to test whether a Pundit policy allows or denies access to certain attributes.
+    class AttributesMatcher < BaseMatcher
+      # Error message to be raised when no attributes are specified.
+      ARGUMENTS_REQUIRED_ERROR = 'At least one attribute must be specified'
+
+      # Initializes a new instance of the AttributesMatcher class.
+      #
+      # @param expected_attributes [Array<String, Symbol, Hash>] The list of attributes to be tested.
+      def initialize(*expected_attributes)
+        raise ArgumentError, ARGUMENTS_REQUIRED_ERROR if expected_attributes.empty?
+
+        super()
+        @expected_attributes = flatten_attributes(expected_attributes)
+        @options = {}
+      end
+
+      # Specifies the action to be tested.
+      #
+      # @param action [Symbol, String] The action to be tested.
+      # @return [AttributesMatcher] The current instance of the AttributesMatcher class.
+      def for_action(action)
+        @options[:action] = action
+        self
+      end
+
+      private
+
+      attr_reader :expected_attributes, :options
+
+      def permitted_attributes(policy)
+        @permitted_attributes ||=
+          if options.key?(:action)
+            flatten_attributes(policy.public_send(:"permitted_attributes_for_#{options[:action]}"))
+          else
+            flatten_attributes(policy.permitted_attributes)
+          end
+      end
+
+      def action_message
+        " when authorising the '#{options[:action]}' action"
+      end
+
+      # Flattens and sorts a hash or array of attributes into an array of symbols.
+      #
+      # This is a private method used internally by the `Matcher` class to convert
+      # attribute lists into a flattened, sorted array of symbols. The resulting
+      # array can be used to compare attribute lists.
+      #
+      # @param attributes [String, Symbol, Array, Hash] the attributes to be flattened.
+      # @return [Array<Symbol>] the flattened, sorted array of symbols.
+      def flatten_attributes(attributes)
+        case attributes
+        when String, Symbol
+          [attributes.to_sym]
+        when Array
+          attributes.flat_map { |item| flatten_attributes(item) }.sort
+        when Hash
+          attributes.flat_map do |key, value|
+            flatten_attributes(value).map { |item| :"#{key}[#{item}]" }
+          end.sort
+        end
+      end
+    end
+  end
+end

data/lib/pundit/matchers/base_matcher.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'utils/policy_info'
+
+module Pundit
+  module Matchers
+    # This is the base class for all matchers in the Pundit Matchers library.
+    class BaseMatcher
+      # Error message when an ambiguous negated matcher is used.
+      AMBIGUOUS_NEGATED_MATCHER_ERROR = <<~MSG
+        `expect().not_to %<name>s` is not supported since it creates ambiguity.
+      MSG
+
+      private
+
+      attr_reader :policy_info
+
+      def setup_policy_info!(policy)
+        @policy_info = Pundit::Matchers::Utils::PolicyInfo.new(policy)
+      end
+
+      def user_message
+        " for '#{policy_info.user}'"
+      end
+    end
+  end
+end

data/lib/pundit/matchers/forbid_all_actions_matcher.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'base_matcher'
+
+module Pundit
+  module Matchers
+    # This matcher tests whether a policy forbids all actions.
+    class ForbidAllActionsMatcher < BaseMatcher
+      # A description of the matcher.
+      #
+      # @return [String] Description of the matcher.
+      def description
+        'forbid all actions'
+      end
+
+      # Checks if the given policy forbids all actions.
+      #
+      # @param policy [Object] The policy to test.
+      # @return [Boolean] True if the policy forbids all actions, false otherwise.
+      def matches?(policy)
+        setup_policy_info! policy
+
+        policy_info.permitted_actions.empty?
+      end
+
+      # Raises a NotImplementedError
+      # @raise NotImplementedError
+      # @return [void]
+      def does_not_match?(_policy)
+        raise NotImplementedError, format(AMBIGUOUS_NEGATED_MATCHER_ERROR, name: 'forbid_all_actions')
+      end
+
+      # Returns a failure message if the matcher fails.
+      #
+      # @return [String] Failure message.
+      def failure_message
+        message = +"expected '#{policy_info}' to forbid all actions,"
+        message << " but permitted #{policy_info.permitted_actions}"
+        message << user_message
+      end
+    end
+  end
+end

data/lib/pundit/matchers/forbid_only_actions_matcher.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'actions_matcher'
+
+module Pundit
+  module Matchers
+    # This matcher tests whether a policy forbids only the expected actions.
+    class ForbidOnlyActionsMatcher < ActionsMatcher
+      # A description of the matcher.
+      #
+      # @return [String] Description of the matcher.
+      def description
+        "forbid only #{expected_actions}"
+      end
+
+      # Checks if the given policy forbids only the expected actions.
+      #
+      # @param policy [Object] The policy to test.
+      # @return [Boolean] True if the policy forbids only the expected actions, false otherwise.
+      def matches?(policy)
+        setup_policy_info! policy
+        check_actions!
+
+        @actual_actions = policy_info.forbidden_actions - expected_actions
+        @extra_actions = policy_info.permitted_actions & expected_actions
+
+        actual_actions.empty? && extra_actions.empty?
+      end
+
+      # Raises a NotImplementedError
+      # @raise NotImplementedError
+      # @return [void]
+      def does_not_match?(_policy)
+        raise NotImplementedError, format(AMBIGUOUS_NEGATED_MATCHER_ERROR, name: 'forbid_only_actions')
+      end
+
+      # The failure message when the expected actions and the forbidden actions do not match.
+      #
+      # @return [String] A failure message when the expected actions and the forbidden actions do not match.
+      def failure_message
+        message = +"expected '#{policy_info}' to forbid only #{expected_actions},"
+        message << " but forbade #{actual_actions}" unless actual_actions.empty?
+        message << extra_message unless extra_actions.empty?
+        message << user_message
+      end
+
+      private
+
+      attr_reader :actual_actions, :extra_actions
+
+      def extra_message
+        if actual_actions.empty?
+          " but permitted #{extra_actions}"
+        else
+          " and permitted #{extra_actions}"
+        end
+      end
+    end
+  end
+end

data/lib/pundit/matchers/permit_actions_matcher.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'actions_matcher'
+
+module Pundit
+  module Matchers
+    # This matcher tests whether a policy permits or forbids the expected actions.
+    class PermitActionsMatcher < ActionsMatcher
+      # A description of the matcher.
+      #
+      # @return [String] Description of the matcher.
+      def description
+        "permit #{expected_actions}"
+      end
+
+      # Checks if the given policy permits the expected actions.
+      #
+      # @param policy [Object] The policy to test.
+      # @return [Boolean] True if the policy permits the expected actions, false otherwise.
+      def matches?(policy)
+        setup_policy_info! policy
+        check_actions!
+
+        @actual_actions = expected_actions.reject do |action|
+          policy.public_send(:"#{action}?")
+        end
+
+        actual_actions.empty?
+      end
+
+      # Checks if the given policy forbids the expected actions.
+      #
+      # @param policy [Object] The policy to test.
+      # @return [Boolean] True if the policy forbids the expected actions, false otherwise.
+      def does_not_match?(policy)
+        setup_policy_info! policy
+        check_actions!
+
+        @actual_actions = expected_actions.select do |action|
+          policy.public_send(:"#{action}?")
+        end
+
+        actual_actions.empty?
+      end
+
+      # Returns a failure message when the expected actions are forbidden.
+      #
+      # @return [String] A failure message when the expected actions are not forbidden.
+      def failure_message
+        message = +"expected '#{policy_info}' to permit #{expected_actions},"
+        message << " but forbade #{actual_actions}"
+        message << user_message
+      end
+
+      # Returns a failure message when the expected actions are permitted.
+      #
+      # @return [String] A failure message when the expected actions are permitted.
+      def failure_message_when_negated
+        message = +"expected '#{policy_info}' to forbid #{expected_actions},"
+        message << " but permitted #{actual_actions}"
+        message << user_message
+      end
+
+      private
+
+      attr_reader :actual_actions
+    end
+  end
+end

data/lib/pundit/matchers/permit_all_actions_matcher.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'base_matcher'
+
+module Pundit
+  module Matchers
+    # This matcher tests whether a policy permits all actions.
+    class PermitAllActionsMatcher < BaseMatcher
+      # A description of the matcher.
+      #
+      # @return [String] A description of the matcher.
+      def description
+        'permit all actions'
+      end
+
+      # Checks if the given policy permits all actions.
+      #
+      # @param policy [Object] The policy to test.
+      # @return [Boolean] True if the policy permits all actions, false otherwise.
+      def matches?(policy)
+        setup_policy_info! policy
+
+        policy_info.forbidden_actions.empty?
+      end
+
+      # Raises a NotImplementedError
+      # @raise NotImplementedError
+      # @return [void]
+      def does_not_match?(_policy)
+        raise NotImplementedError, format(AMBIGUOUS_NEGATED_MATCHER_ERROR, name: 'permit_all_actions')
+      end
+
+      # Returns a failure message when the policy does not permit all actions.
+      #
+      # @return [String] A failure message when the policy does not permit all actions.
+      def failure_message
+        message = +"expected '#{policy_info}' to permit all actions,"
+        message << " but forbade #{policy_info.forbidden_actions}"
+        message << user_message
+      end
+    end
+  end
+end

data/lib/pundit/matchers/permit_attributes_matcher.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'attributes_matcher'
+
+module Pundit
+  module Matchers
+    # This matcher tests whether a policy permits or forbids the mass assignment of the expected attributes.
+    class PermitAttributesMatcher < AttributesMatcher
+      # A description of the matcher.
+      #
+      # @return [String] A description of the matcher.
+      def description
+        "permit the mass assignment of #{expected_attributes}"
+      end
+
+      # Checks if the given policy permits the mass assignment of the expected attributes.
+      #
+      # @param policy [Object] The policy to test.
+      # @return [Boolean] True if the policy permits the mass assignment of the expected attributes, false otherwise.
+      def matches?(policy)
+        setup_policy_info! policy
+
+        @actual_attributes = expected_attributes - permitted_attributes(policy)
+
+        actual_attributes.empty?
+      end
+
+      # Checks if the given policy forbids the mass assignment of the expected attributes.
+      #
+      # @param policy [Object] The policy to test.
+      # @return [Boolean] True if the policy forbids the mass assignment of the expected attributes, false otherwise.
+      def does_not_match?(policy)
+        setup_policy_info! policy
+
+        @actual_attributes = expected_attributes & permitted_attributes(policy)
+
+        actual_attributes.empty?
+      end
+
+      # The failure message when the expected attributes are forbidden.
+      #
+      # @return [String] A failure message when the expected attributes are not permitted.
+      def failure_message
+        message = +"expected '#{policy_info}' to permit the mass assignment of #{expected_attributes}"
+        message << action_message if options.key?(:action)
+        message << ", but forbade the mass assignment of #{actual_attributes}"
+        message << user_message
+      end
+
+      # The failure message when the expected attributes are permitted.
+      #
+      # @return [String] A failure message when the expected attributes are forbidden.
+      def failure_message_when_negated
+        message = +"expected '#{policy_info}' to forbid the mass assignment of #{expected_attributes}"
+        message << action_message if options.key?(:action)
+        message << ", but permitted the mass assignment of #{actual_attributes}"
+        message << user_message
+      end
+
+      private
+
+      attr_reader :actual_attributes
+    end
+  end
+end

data/lib/pundit/matchers/permit_only_actions_matcher.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'actions_matcher'
+
+module Pundit
+  module Matchers
+    # This matcher tests whether a policy permits only the expected actions.
+    class PermitOnlyActionsMatcher < ActionsMatcher
+      # A description of the matcher.
+      #
+      # @return [String] A description of the matcher.
+      def description
+        "permit only #{expected_actions}"
+      end
+
+      # Checks if the given policy permits only the expected actions.
+      #
+      # @param policy [Object] The policy to test.
+      # @return [Boolean] True if the policy permits only the expected actions, false otherwise.
+      def matches?(policy)
+        setup_policy_info! policy
+        check_actions!
+
+        @actual_actions = policy_info.permitted_actions - expected_actions
+        @extra_actions = policy_info.forbidden_actions & expected_actions
+
+        actual_actions.empty? && extra_actions.empty?
+      end
+
+      # Raises a NotImplementedError
+      # @raise NotImplementedError
+      # @return [void]
+      def does_not_match?(_policy)
+        raise NotImplementedError, format(AMBIGUOUS_NEGATED_MATCHER_ERROR, name: 'permit_only_actions')
+      end
+
+      # The failure message when the expected actions and the permitted actions do not match.
+      #
+      # @return [String] A failure message when the expected actions and the permitted actions do not match.
+      def failure_message
+        message = +"expected '#{policy_info}' to permit only #{expected_actions},"
+        message << " but permitted #{actual_actions}" unless actual_actions.empty?
+        message << extra_message unless extra_actions.empty?
+        message << user_message
+      end
+
+      private
+
+      attr_reader :actual_actions, :extra_actions
+
+      def extra_message
+        if actual_actions.empty?
+          " but forbade #{extra_actions}"
+        else
+          " and forbade #{extra_actions}"
+        end
+      end
+    end
+  end
+end

data/lib/pundit/matchers/utils/policy_info.rb

@@ -3,27 +3,88 @@
 module Pundit
   module Matchers
     module Utils
-      # Collects all details about given policy class.
+      # This class provides methods to retrieve information about a policy class,
+      # such as the actions it defines and which of those actions are permitted
+      # or forbidden. It also provides a string representation of the policy class name
+      # and the user object associated with the policy.
       class PolicyInfo
+        # Error message when policy does not respond to `user_alias`.
+        USER_NOT_IMPLEMENTED_ERROR = <<~MSG
+          '%<policy>s' does not implement '%<user_alias>s'. You may want to
+          configure an alias, which you can do as follows:
+
+          Pundit::Matchers.configure do |config|
+            # Alias for all policies
+            config.default_user_alias = :%<user_alias>s
+
+            # Per-policy alias
+            config.user_aliases = { '%<policy>s' => :%<user_alias>s }
+          end
+        MSG
+
         attr_reader :policy
 
+        # Initializes a new instance of PolicyInfo.
+        #
+        # @param policy [Class] The policy class to collect details about.
         def initialize(policy)
           @policy = policy
+          check_user_alias!
+        end
+
+        # Returns a string representation of the policy class name.
+        #
+        # @return [String] A string representation of the policy class name.
+        def to_s
+          policy.class.name
+        end
+
+        # Returns the user object associated with the policy.
+        #
+        # @return [Object] The user object associated with the policy.
+        def user
+          @user ||= policy.public_send(user_alias)
         end
 
+        # Returns an array of all actions defined in the policy class.
+        #
+        # It assumes that actions are defined as public instance methods that end with a question mark.
+        #
+        # @return [Array<Symbol>] An array of all actions defined in the policy class.
         def actions
-          @actions ||= begin
-            policy_methods = @policy.public_methods - Object.instance_methods
-            policy_methods.grep(/\?$/).sort.map { |policy_method| policy_method.to_s.delete_suffix('?').to_sym }
+          @actions ||= policy_public_methods.grep(/\?$/).sort.map do |policy_method|
+            policy_method.to_s.delete_suffix('?').to_sym
           end
         end
 
+        # Returns an array of all permitted actions defined in the policy class.
+        #
+        # @return [Array<Symbol>] An array of all permitted actions defined in the policy class.
         def permitted_actions
-          @permitted_actions ||= actions.select { |action| policy.public_send("#{action}?") }
+          @permitted_actions ||= actions.select { |action| policy.public_send(:"#{action}?") }
         end
 
+        # Returns an array of all forbidden actions defined in the policy class.
+        #
+        # @return [Array<Symbol>] An array of all forbidden actions defined in the policy class.
         def forbidden_actions
-          actions - permitted_actions
+          @forbidden_actions ||= actions - permitted_actions
+        end
+
+        private
+
+        def policy_public_methods
+          @policy_public_methods ||= policy.public_methods - Object.instance_methods
+        end
+
+        def user_alias
+          @user_alias ||= Pundit::Matchers.configuration.user_alias(policy)
+        end
+
+        def check_user_alias!
+          return if policy.respond_to?(user_alias)
+
+          raise ArgumentError, format(USER_NOT_IMPLEMENTED_ERROR, policy: self, user_alias: user_alias)
         end
       end
     end