pundit-matchers 1.7.0 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0da80bb866c35b8ab6548d017a9bc022831e3da0c5493b99aac0ba5c8c79cad
-  data.tar.gz: 24bfacd140e3976e30c88204db5e33566c42dbd5e45d568c8d857a7a4205951d
+  metadata.gz: 0ce1e0e0fa90468774d5a482fd4d715af3e40b6e4a4fc6360f19c009d21d04a8
+  data.tar.gz: 463cb245dfd0a68f5c106e92248ff320fb7ef95d826cdf1a0111b3bddd0ba8bd
 SHA512:
-  metadata.gz: 5c1fbddf259fce9fa65c6f0613ec5d46e271ab0c7212380bc86cb5fef6fb85a2f74b6c20a4fb6b4c0e1dacc6b8ad11e1c963f8827c997e88bb319cce157d305b
-  data.tar.gz: a2363786904df0631c54b8d84094179b61607e300a16ba53cd6406b02272e51f1e21060832f5b64a3eeaaba1ff6dba7c8462d3308732f335dc363df666058120
+  metadata.gz: 7ebb5b5df0c13cb1bc0fa8a150c0f6a34cae3719bebd9ff11bdec03f30304678e1101e393c7e7b3a47a3efa83b0169732e96efe929c8c23d79682dd537f72c8d
+  data.tar.gz: 25026769eeb8f12294babbbecd5efcff201d7a648b843d4b71b8a49d8da19b88c18f7cc0298e10e95f9dd0e36fc1209824a650aa338904704dcd4bcb121b24a7

data/lib/pundit/matchers/actions_matcher.rb

@@ -0,0 +1,55 @@
+# 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'
+      # Error message when only one action may be specified.
+      ONE_ARGUMENT_REQUIRED_ERROR = 'Only one action may 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
+
+      # Ensures that only one action is specified.
+      #
+      # @raise [ArgumentError] If more than one action is specified.
+      #
+      # @return [ActionsMatcher] The object itself.
+      def ensure_single_action!
+        raise ArgumentError, ONE_ARGUMENT_REQUIRED_ERROR if expected_actions.size > 1
+
+        self
+      end
+
+      private
+
+      attr_reader :expected_actions
+
+      def check_actions!
+        non_explicit_actions = (expected_actions - policy_info.actions)
+        missing_actions = non_explicit_actions.reject { |action| policy_info.policy.respond_to?(:"#{action}?") }
+        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,84 @@
+# 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'
+      # Error message to be raised when only one attribute may be specified.
+      ONE_ARGUMENT_REQUIRED_ERROR = 'Only one attribute may 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
+
+      # Ensures that only one attribute is specified.
+      #
+      # @raise [ArgumentError] If more than one attribute is specified.
+      #
+      # @return [AttributesMatcher] The object itself.
+      def ensure_single_attribute!
+        raise ArgumentError, ONE_ARGUMENT_REQUIRED_ERROR if expected_attributes.size > 1
+
+        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,29 @@
+# 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
+      include ::RSpec::Matchers::Composable
+
+      # 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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Pundit
+  module Matchers
+    module Utils
+      # 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 ||= 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}?") }
+        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
+          @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
+  end
+end

data/lib/pundit/matchers.rb

@@ -1,373 +1,186 @@
-require 'rspec/core'
-
-module Pundit
-  module Matchers
-    class Configuration
-      attr_accessor :user_alias
-
-      def initialize
-        @user_alias = :user
-      end
-    end
-
-    class << self
-      def configure
-        yield(configuration)
-      end
-
-      def configuration
-        @configuration ||= Pundit::Matchers::Configuration.new
-      end
-    end
-
-    RSpec::Matchers.define :forbid_action do |action, *args|
-      match do |policy|
-        if args.any?
-          !policy.public_send("#{action}?", *args)
-        else
-          !policy.public_send("#{action}?")
-        end
-      end
+# frozen_string_literal: true
 
-      failure_message do |policy|
-        "#{policy.class} does not forbid #{action} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      end
-
-      failure_message_when_negated do |policy|
-        "#{policy.class} does not permit #{action} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      end
-    end
-  end
-
-  RSpec::Matchers.define :forbid_actions do |*actions|
-    actions.flatten!
-    match do |policy|
-      return false if actions.count < 1
-      @allowed_actions = actions.select do |action|
-        policy.public_send("#{action}?")
-      end
-      @allowed_actions.empty?
-    end
-
-    attr_reader :allowed_actions
-
-    zero_actions_failure_message = 'At least one action must be ' \
-      'specified when using the forbid_actions matcher.'
-
-    failure_message do |policy|
-      if actions.count.zero?
-        zero_actions_failure_message
-      else
-        "#{policy.class} expected to forbid #{actions}, but allowed " \
-          "#{allowed_actions} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      end
-    end
-
-    failure_message_when_negated do |policy|
-      if actions.count.zero?
-        zero_actions_failure_message
-      else
-        "#{policy.class} expected to permit #{actions}, but forbade " \
-          "#{allowed_actions} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      end
-    end
-  end
-
-  RSpec::Matchers.define :forbid_edit_and_update_actions do
-    match do |policy|
-      !policy.edit? && !policy.update?
-    end
-
-    failure_message do |policy|
-      "#{policy.class} does not forbid the edit or update action for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
-    end
+require 'rspec/core'
 
-    failure_message_when_negated do |policy|
-      "#{policy.class} does not permit the edit or update action for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
-    end
-  end
+require_relative 'matchers/permit_actions_matcher'
 
-  RSpec::Matchers.define :forbid_mass_assignment_of do |attributes|
-    # Map single object argument to an array, if necessary
-    attributes = attributes.is_a?(Array) ? attributes : [attributes]
+require_relative 'matchers/permit_attributes_matcher'
 
-    match do |policy|
-      return false if attributes.count < 1
+require_relative 'matchers/forbid_all_actions_matcher'
+require_relative 'matchers/forbid_only_actions_matcher'
 
-      @allowed_attributes = attributes.select do |attribute|
-        if defined? @action
-          policy.send("permitted_attributes_for_#{@action}").include? attribute
-        else
-          policy.permitted_attributes.include? attribute
-        end
-      end
+require_relative 'matchers/permit_all_actions_matcher'
+require_relative 'matchers/permit_only_actions_matcher'
 
-      @allowed_attributes.empty?
-    end
+module Pundit
+  # Matchers module provides a set of RSpec matchers for testing Pundit policies.
+  module Matchers
+    # A Proc that negates the description of a matcher.
+    NEGATED_DESCRIPTION = ->(description) { description.gsub(/^permit/, 'forbid') }
 
-    attr_reader :allowed_attributes
+    # Configuration class for Pundit Matchers.
+    class Configuration
+      # The default user object value
+      DEFAULT_USER_ALIAS = :user
 
-    chain :for_action do |action|
-      @action = action
-    end
+      # The default user object in policies.
+      # @return [Symbol|String]
+      attr_accessor :default_user_alias
 
-    zero_attributes_failure_message = 'At least one attribute must be ' \
-      'specified when using the forbid_mass_assignment_of matcher.'
+      # Policy-specific user objects.
+      #
+      # @example Use +:client+ as user alias for class +Post+
+      #   config.user_aliases = { 'Post' => :client }
+      #
+      # @return [Hash]
+      attr_accessor :user_aliases
 
-    failure_message do |policy|
-      if attributes.count.zero?
-        zero_attributes_failure_message
-      elsif defined? @action
-        "#{policy.class} expected to forbid the mass assignment of the " \
-          "attributes #{attributes} when authorising the #{@action} action, " \
-          'but allowed the mass assignment of the attributes ' \
-          "#{allowed_attributes} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      else
-        "#{policy.class} expected to forbid the mass assignment of the " \
-          "attributes #{attributes}, but allowed the mass assignment of " \
-          "the attributes #{allowed_attributes} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
+      def initialize
+        @default_user_alias = DEFAULT_USER_ALIAS
+        @user_aliases = {}
       end
-    end
 
-    failure_message_when_negated do |policy|
-      if attributes.count.zero?
-        zero_attributes_failure_message
-      elsif defined? @action
-        "#{policy.class} expected to permit the mass assignment of the " \
-          "attributes #{attributes} when authorising the #{@action} action, " \
-          'but permitted the mass assignment of the attributes ' \
-          "#{allowed_attributes} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      else
-        "#{policy.class} expected to permit the mass assignment of the " \
-          "attributes #{attributes}, but permitted the mass assignment of " \
-          "the attributes #{allowed_attributes} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
+      # Returns the user object for the given policy.
+      #
+      # @return [Symbol]
+      def user_alias(policy)
+        user_aliases.fetch(policy.class.name, default_user_alias)
       end
     end
-  end
-
-  RSpec::Matchers.define :forbid_new_and_create_actions do
-    match do |policy|
-      !policy.new? && !policy.create?
-    end
-
-    failure_message do |policy|
-      "#{policy.class} does not forbid the new or create action for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
-    end
-
-    failure_message_when_negated do |policy|
-      "#{policy.class} does not permit the new or create action for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
-    end
-  end
 
-  RSpec::Matchers.define :permit_action do |action, *args|
-    match do |policy|
-      if args.any?
-        policy.public_send("#{action}?", *args)
-      else
-        policy.public_send("#{action}?")
+    class << self
+      # Configures Pundit Matchers.
+      #
+      # @yieldparam [Configuration] configuration the configuration object to be modified.
+      def configure
+        yield(configuration)
       end
-    end
 
-    failure_message do |policy|
-      "#{policy.class} does not permit #{action} for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
-    end
-
-    failure_message_when_negated do |policy|
-      "#{policy.class} does not forbid #{action} for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
-    end
-  end
-
-  RSpec::Matchers.define :permit_actions do |*actions|
-    actions.flatten!
-    match do |policy|
-      return false if actions.count < 1
-      @forbidden_actions = actions.reject do |action|
-        policy.public_send("#{action}?")
+      # Returns the configuration object for Pundit Matchers.
+      #
+      # @return [Configuration] the configuration object.
+      def configuration
+        @configuration ||= Pundit::Matchers::Configuration.new
       end
-      @forbidden_actions.empty?
     end
 
-    match_when_negated do |policy|
-      ::Kernel.warn 'Using expect { }.not_to permit_actions could produce \
-        confusing results. Please use `.to forbid_actions` instead. To \
-        clarify, `.not_to permit_actions` will look at all of the actions and \
-        checks if ANY actions fail, not if all actions fail. Therefore, you \
-        could result in something like this: \
-
-        it { is_expected.to permit_actions([:new, :create, :edit]) } \
-        it { is_expected.not_to permit_actions([:edit, :destroy]) } \
-
-        In this case, edit would be true and destroy would be false, but both \
-        tests would pass.'
-
-      return true if actions.count < 1
-      @forbidden_actions = actions.reject do |action|
-        policy.public_send("#{action}?")
-      end
-      !@forbidden_actions.empty?
+    # Creates a matcher that tests if the policy permits a given action.
+    #
+    # @param [String|Symbol] action the action to be tested.
+    # @return [PermitActionsMatcher] the matcher object.
+    def permit_action(action)
+      PermitActionsMatcher.new(action).ensure_single_action!
     end
 
-    attr_reader :forbidden_actions
-
-    zero_actions_failure_message = 'At least one action must be specified ' \
-      'when using the permit_actions matcher.'
+    # @!macro [attach] RSpec::Matchers.define_negated_matcher
+    #   @!method $1
+    #
+    #   The negated matcher of {$2}.
+    #
+    #   Same as +expect(policy).not_to $2(*args)+.
+    RSpec::Matchers.define_negated_matcher :forbid_action, :permit_action, &NEGATED_DESCRIPTION
 
-    failure_message do |policy|
-      if actions.count.zero?
-        zero_actions_failure_message
-      else
-        "#{policy.class} expected to permit #{actions}, but forbade " \
-          "#{forbidden_actions} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      end
+    # Creates a matcher that tests if the policy permits a set of actions.
+    #
+    # @param [Array<String, Symbol>] actions the actions to be tested.
+    # @return [PermitActionsMatcher] the matcher object.
+    def permit_actions(*actions)
+      PermitActionsMatcher.new(*actions)
     end
 
-    failure_message_when_negated do |policy|
-      if actions.count.zero?
-        zero_actions_failure_message
-      else
-        "#{policy.class} expected to forbid #{actions}, but allowed " \
-          "#{forbidden_actions} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      end
-    end
-  end
+    RSpec::Matchers.define_negated_matcher :forbid_actions, :permit_actions, &NEGATED_DESCRIPTION
 
-  RSpec::Matchers.define :permit_edit_and_update_actions do
-    match do |policy|
-      policy.edit? && policy.update?
+    # Creates a matcher that tests if the policy permits all actions.
+    #
+    # @note The negative form +not_to permit_all_actions+ is not supported
+    #   since it creates ambiguity. Instead use +to forbid_all_actions+.
+    #
+    # @return [PermitAllActionsMatcher] the matcher object.
+    def permit_all_actions
+      PermitAllActionsMatcher.new
     end
 
-    failure_message do |policy|
-      "#{policy.class} does not permit the edit or update action for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
+    # Creates a matcher that tests if the policy forbids all actions.
+    #
+    # @note The negative form +not_to forbid_all_actions+ is not supported
+    #   since it creates ambiguity. Instead use +to permit_all_actions+.
+    #
+    # @return [ForbidAllActionsMatcher] the matcher object.
+    def forbid_all_actions
+      ForbidAllActionsMatcher.new
     end
 
-    failure_message_when_negated do |policy|
-      "#{policy.class} does not forbid the edit or update action for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
+    # Creates a matcher that tests if the policy permits the edit and update actions.
+    #
+    # @return [PermitActionsMatcher] the matcher object.
+    def permit_edit_and_update_actions
+      PermitActionsMatcher.new(:edit, :update)
     end
-  end
-
-  RSpec::Matchers.define :permit_mass_assignment_of do |attributes|
-    # Map single object argument to an array, if necessary
-    attributes = attributes.is_a?(Array) ? attributes : [attributes]
 
-    match do |policy|
-      return false if attributes.count < 1
+    RSpec::Matchers.define_negated_matcher :forbid_edit_and_update_actions, :permit_edit_and_update_actions,
+                                           &NEGATED_DESCRIPTION
 
-      @forbidden_attributes = attributes.select do |attribute|
-        if defined? @action
-          !policy.send("permitted_attributes_for_#{@action}").include? attribute
-        else
-          !policy.permitted_attributes.include? attribute
-        end
-      end
-
-      @forbidden_attributes.empty?
+    # Creates a matcher that tests if the policy permits the new and create actions.
+    #
+    # @return [PermitActionsMatcher] the matcher object.
+    def permit_new_and_create_actions
+      PermitActionsMatcher.new(:new, :create)
     end
 
-    attr_reader :forbidden_attributes
+    RSpec::Matchers.define_negated_matcher :forbid_new_and_create_actions, :permit_new_and_create_actions,
+                                           &NEGATED_DESCRIPTION
 
-    chain :for_action do |action|
-      @action = action
+    # Creates a matcher that tests if the policy permits only a set of actions.
+    #
+    # @note The negative form +not_to permit_only_actions+ is not supported
+    #   since it creates ambiguity. Instead use +to forbid_only_actions+.
+    #
+    # @param [Array<String, Symbol>] actions the actions to be tested.
+    # @return [PermitOnlyActionsMatcher] the matcher object.
+    def permit_only_actions(*actions)
+      PermitOnlyActionsMatcher.new(*actions)
     end
 
-    zero_attributes_failure_message = 'At least one attribute must be ' \
-      'specified when using the permit_mass_assignment_of matcher.'
-
-    failure_message do |policy|
-      if attributes.count.zero?
-        zero_attributes_failure_message
-      elsif defined? @action
-        "#{policy.class} expected to permit the mass assignment of the " \
-          "attributes #{attributes} when authorising the #{@action} action, " \
-          'but forbade the mass assignment of the attributes ' \
-          "#{forbidden_attributes} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      else
-        "#{policy.class} expected to permit the mass assignment of the " \
-          "attributes #{attributes}, but forbade the mass assignment of the " \
-          "attributes #{forbidden_attributes} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      end
+    # Creates a matcher that tests if the policy forbids only a set of actions.
+    #
+    # @note The negative form +not_to forbid_only_actions+ is not supported
+    #   since it creates ambiguity. Instead use +to permit_only_actions+.
+    #
+    # @param [Array<String, Symbol>] actions the actions to be tested.
+    # @return [ForbidOnlyActionsMatcher] the matcher object.
+    def forbid_only_actions(*actions)
+      ForbidOnlyActionsMatcher.new(*actions)
     end
 
-    failure_message_when_negated do |policy|
-      if attributes.count.zero?
-        zero_attributes_failure_message
-      elsif defined? @action
-        "#{policy.class} expected to forbid the mass assignment of the " \
-          "attributes #{attributes} when authorising the #{@action} action, " \
-          'but forbade the mass assignment of the attributes ' \
-          "#{forbidden_attributes} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      else
-        "#{policy.class} expected to forbid the mass assignment of the " \
-          "attributes #{attributes}, but forbade the mass assignment of the " \
-          "attributes #{forbidden_attributes} for " +
-          policy.public_send(Pundit::Matchers.configuration.user_alias)
-                .inspect + '.'
-      end
+    # Creates a matcher that tests if the policy permits mass assignment of an attribute.
+    #
+    # @param [String, Symbol, Hash] attribute the attribute to be tested.
+    # @return [PermitAttributesMatcher] the matcher object.
+    def permit_attribute(attribute)
+      PermitAttributesMatcher.new(attribute).ensure_single_attribute!
     end
-  end
 
-  RSpec::Matchers.define :permit_new_and_create_actions do
-    match do |policy|
-      policy.new? && policy.create?
-    end
-
-    failure_message do |policy|
-      "#{policy.class} does not permit the new or create action for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
-    end
+    RSpec::Matchers.define_negated_matcher :forbid_attribute, :permit_attribute, &NEGATED_DESCRIPTION
 
-    failure_message_when_negated do |policy|
-      "#{policy.class} does not forbid the new or create action for " +
-        policy.public_send(Pundit::Matchers.configuration.user_alias)
-              .inspect + '.'
-    end
+    # Creates a matcher that tests if the policy permits mass assignment of a set of attributes.
+    #
+    # @param [Array<String, Symbol, Hash>] attributes the attributes to be tested.
+    # @return [PermitAttributesMatcher] the matcher object.
+    def permit_attributes(*attributes)
+      PermitAttributesMatcher.new(*attributes)
+    end
+
+    RSpec::Matchers.define_negated_matcher :forbid_attributes, :permit_attributes, &NEGATED_DESCRIPTION
+
+    # @!macro [attach] RSpec::Matchers.alias_matcher
+    #   @!method $1
+    #
+    #   An alias matcher for {$2}.
+    RSpec::Matchers.alias_matcher :permit_mass_assignment_of, :permit_attributes
+    RSpec::Matchers.alias_matcher :forbid_mass_assignment_of, :forbid_attributes
   end
 end
 
-if defined?(Pundit)
-  RSpec.configure do |config|
-    config.include Pundit::Matchers
-  end
+RSpec.configure do |config|
+  config.include Pundit::Matchers
 end

metadata

@@ -1,49 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: pundit-matchers
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 3.1.2
 platform: ruby
 authors:
 - Chris Alley
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-04 00:00:00.000000000 Z
+date: 2023-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: rspec-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '3.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '3.12'
 - !ruby/object:Gem::Dependency
-  name: pundit
+  name: rspec-expectations
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
+        version: '3.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
-  type: :development
+        version: '3.12'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rspec-support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: '3.12'
 description: A set of RSpec matchers for testing Pundit authorisation policies
 email: chris@chrisalley.info
 executables: []
@@ -51,10 +73,21 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/pundit/matchers.rb
-homepage: http://github.com/chrisalley/pundit-matchers
+- lib/pundit/matchers/actions_matcher.rb
+- lib/pundit/matchers/attributes_matcher.rb
+- lib/pundit/matchers/base_matcher.rb
+- lib/pundit/matchers/forbid_all_actions_matcher.rb
+- lib/pundit/matchers/forbid_only_actions_matcher.rb
+- lib/pundit/matchers/permit_actions_matcher.rb
+- lib/pundit/matchers/permit_all_actions_matcher.rb
+- lib/pundit/matchers/permit_attributes_matcher.rb
+- lib/pundit/matchers/permit_only_actions_matcher.rb
+- lib/pundit/matchers/utils/policy_info.rb
+homepage: https://github.com/punditcommunity/pundit-matchers
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -63,14 +96,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.4.12
 signing_key:
 specification_version: 4
 summary: RSpec matchers for Pundit policies