pundit-matchers 2.3.0 → 3.0.0.beta1

data/lib/pundit/matchers.rb

@@ -2,412 +2,168 @@
 
 require 'rspec/core'
 
+require_relative 'matchers/permit_actions_matcher'
+
+require_relative 'matchers/permit_attributes_matcher'
+
+require_relative 'matchers/forbid_all_actions_matcher'
+require_relative 'matchers/forbid_only_actions_matcher'
+
+require_relative 'matchers/permit_all_actions_matcher'
+require_relative 'matchers/permit_only_actions_matcher'
+
 module Pundit
+  # Matchers module provides a set of RSpec matchers for testing Pundit policies.
   module Matchers
-    require_relative 'matchers/utils/policy_info'
-    require_relative 'matchers/utils/all_actions/forbidden_actions_error_formatter'
-    require_relative 'matchers/utils/all_actions/forbidden_actions_matcher'
-    require_relative 'matchers/utils/all_actions/permitted_actions_error_formatter'
-    require_relative 'matchers/utils/all_actions/permitted_actions_matcher'
-
-    require_relative 'matchers/utils/only_actions/forbidden_actions_error_formatter'
-    require_relative 'matchers/utils/only_actions/forbidden_actions_matcher'
-    require_relative 'matchers/utils/only_actions/permitted_actions_error_formatter'
-    require_relative 'matchers/utils/only_actions/permitted_actions_matcher'
+    # A Proc that negates the description of a matcher.
+    NEGATED_DESCRIPTION = ->(description) { description.gsub(/^permit/, 'forbid') }
 
+    # Configuration class for Pundit Matchers.
     class Configuration
-      attr_accessor :user_alias
+      # The default user object value
+      DEFAULT_USER_ALIAS = :user
+
+      # The default user object in policies.
+      # @return [Symbol|String]
+      attr_accessor :default_user_alias
+
+      # Policy-specific user objects.
+      #
+      # @example Use +:client+ as user alias for class +Post+
+      #   config.user_aliases = { 'Post' => :client }
+      #
+      # @return [Hash]
+      attr_accessor :user_aliases
 
       def initialize
-        @user_alias = :user
+        @default_user_alias = DEFAULT_USER_ALIAS
+        @user_aliases = {}
+      end
+
+      # 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
 
     class << self
+      # Configures Pundit Matchers.
+      #
+      # @yieldparam [Configuration] configuration the configuration object to be modified.
       def configure
         yield(configuration)
       end
 
+      # Returns the configuration object for Pundit Matchers.
+      #
+      # @return [Configuration] the configuration object.
       def configuration
         @configuration ||= Pundit::Matchers::Configuration.new
       end
     end
-  end
-
-  RSpec::Matchers.define :forbid_action do |action, *args, **kwargs|
-    match do |policy|
-      if args.any?
-        !policy.public_send("#{action}?", *args, **kwargs)
-      else
-        !policy.public_send("#{action}?", **kwargs)
-      end
-    end
-
-    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
-
-  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 permitted " \
-          "#{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
-
-    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
-
-  RSpec::Matchers.define :forbid_mass_assignment_of do |attributes|
-    # Map single object argument to an array, if necessary
-    attributes = [attributes] unless attributes.is_a?(Array)
-
-    match do |policy|
-      return false if attributes.count < 1
-
-      @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
-
-      @allowed_attributes.empty?
-    end
-
-    attr_reader :allowed_attributes
-
-    chain :for_action do |action|
-      @action = action
-    end
-
-    zero_attributes_failure_message = 'At least one attribute must be ' \
-                                      'specified when using the forbid_mass_assignment_of matcher.'
-
-    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 permitted 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 permitted the mass assignment of " \
-          "the attributes #{allowed_attributes} for " \
-          "#{policy.public_send(Pundit::Matchers.configuration.user_alias).inspect}."
-      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}."
-      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, **kwargs|
-    match do |policy|
-      if args.any?
-        policy.public_send("#{action}?", *args, **kwargs)
-      else
-        policy.public_send("#{action}?", **kwargs)
-      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}."
+    # Creates a matcher that tests if the policy permits a given action.
+    #
+    # @param [Symbol] action the action to be tested.
+    # @return [PermitActionsMatcher] the matcher object.
+    def permit_action(action)
+      PermitActionsMatcher.new(action)
     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}?")
-      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.'
+    # @!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
 
-      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 set of actions.
+    #
+    # @param [Array<Symbol>] actions the actions to be tested.
+    # @return [PermitActionsMatcher] the matcher object.
+    def permit_actions(*actions)
+      PermitActionsMatcher.new(*actions)
     end
 
-    attr_reader :forbidden_actions
+    RSpec::Matchers.define_negated_matcher :forbid_actions, :permit_actions, &NEGATED_DESCRIPTION
 
-    zero_actions_failure_message = 'At least one action must be specified ' \
-                                   'when using the permit_actions matcher.'
-
-    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 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_when_negated do |policy|
-      if actions.count.zero?
-        zero_actions_failure_message
-      else
-        "#{policy.class} expected to forbid #{actions}, but permitted " \
-          "#{forbidden_actions} for " \
-          "#{policy.public_send(Pundit::Matchers.configuration.user_alias).inspect}."
-      end
+    # 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
-  end
 
-  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 the edit and update actions.
+    #
+    # @return [PermitActionsMatcher] the matcher object.
+    def permit_edit_and_update_actions
+      PermitActionsMatcher.new(:edit, :update)
     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}."
-    end
+    RSpec::Matchers.define_negated_matcher :forbid_edit_and_update_actions, :permit_edit_and_update_actions,
+                                           &NEGATED_DESCRIPTION
 
-    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 new and create actions.
+    #
+    # @return [PermitActionsMatcher] the matcher object.
+    def permit_new_and_create_actions
+      PermitActionsMatcher.new(:new, :create)
     end
-  end
 
-  RSpec::Matchers.define :permit_mass_assignment_of do |attributes|
-    # Map single object argument to an array, if necessary
-    attributes = [attributes] unless attributes.is_a?(Array)
+    RSpec::Matchers.define_negated_matcher :forbid_new_and_create_actions, :permit_new_and_create_actions,
+                                           &NEGATED_DESCRIPTION
 
-    match do |policy|
-      return false if attributes.count < 1
-
-      @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 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<Symbol>] actions the actions to be tested.
+    # @return [PermitOnlyActionsMatcher] the matcher object.
+    def permit_only_actions(*actions)
+      PermitOnlyActionsMatcher.new(*actions)
     end
 
-    attr_reader :forbidden_attributes
-
-    chain :for_action do |action|
-      @action = action
+    # 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<Symbol>] actions the actions to be tested.
+    # @return [ForbidOnlyActionsMatcher] the matcher object.
+    def forbid_only_actions(*actions)
+      ForbidOnlyActionsMatcher.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 permits mass assignment of a set of attributes.
+    #
+    # @param [Array<Symbol>] attributes the attributes to be tested.
+    # @return [PermitAttributesMatcher] the matcher object.
+    def permit_mass_assignment_of(*attributes)
+      PermitAttributesMatcher.new(*attributes)
     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
-    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
-
-    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
-  end
-
-  RSpec::Matchers.define :permit_all_actions do
-    match do |policy|
-      @matcher = Pundit::Matchers::Utils::AllActions::PermittedActionsMatcher.new(policy)
-      @matcher.match?
-    end
-
-    failure_message do
-      formatter = Pundit::Matchers::Utils::AllActions::PermittedActionsErrorFormatter.new(@matcher)
-      formatter.message
-    end
-  end
-
-  RSpec::Matchers.define :permit_only_actions do |actions|
-    match do |policy|
-      @matcher = Pundit::Matchers::Utils::OnlyActions::PermittedActionsMatcher.new(policy, actions)
-      @matcher.match?
-    end
-
-    failure_message do
-      formatter = Pundit::Matchers::Utils::OnlyActions::PermittedActionsErrorFormatter.new(@matcher)
-      formatter.message
-    end
-  end
-
-  RSpec::Matchers.define :forbid_all_actions do
-    match do |policy|
-      @matcher = Pundit::Matchers::Utils::AllActions::ForbiddenActionsMatcher.new(policy)
-      @matcher.match?
-    end
-
-    failure_message do
-      formatter = Pundit::Matchers::Utils::AllActions::ForbiddenActionsErrorFormatter.new(@matcher)
-      formatter.message
-    end
-  end
-
-  RSpec::Matchers.define :forbid_only_actions do |actions|
-    match do |policy|
-      @matcher = Pundit::Matchers::Utils::OnlyActions::ForbiddenActionsMatcher.new(policy, actions)
-      @matcher.match?
-    end
-
-    failure_message do
-      formatter = Pundit::Matchers::Utils::OnlyActions::ForbiddenActionsErrorFormatter.new(@matcher)
-      formatter.message
-    end
+    RSpec::Matchers.define_negated_matcher :forbid_mass_assignment_of, :permit_mass_assignment_of, &NEGATED_DESCRIPTION
   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,29 @@
 --- !ruby/object:Gem::Specification
 name: pundit-matchers
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 3.0.0.beta1
 platform: ruby
 authors:
 - Chris Alley
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-23 00:00:00.000000000 Z
+date: 2023-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: rspec
   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
-- !ruby/object:Gem::Dependency
-  name: pundit
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
-      - !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,18 +31,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/pundit/matchers.rb
-- lib/pundit/matchers/utils/all_actions/actions_matcher.rb
-- lib/pundit/matchers/utils/all_actions/error_message_formatter.rb
-- lib/pundit/matchers/utils/all_actions/forbidden_actions_error_formatter.rb
-- lib/pundit/matchers/utils/all_actions/forbidden_actions_matcher.rb
-- lib/pundit/matchers/utils/all_actions/permitted_actions_error_formatter.rb
-- lib/pundit/matchers/utils/all_actions/permitted_actions_matcher.rb
-- lib/pundit/matchers/utils/only_actions/actions_matcher.rb
-- lib/pundit/matchers/utils/only_actions/error_message_formatter.rb
-- lib/pundit/matchers/utils/only_actions/forbidden_actions_error_formatter.rb
-- lib/pundit/matchers/utils/only_actions/forbidden_actions_matcher.rb
-- lib/pundit/matchers/utils/only_actions/permitted_actions_error_formatter.rb
-- lib/pundit/matchers/utils/only_actions/permitted_actions_matcher.rb
+- 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:
@@ -80,9 +57,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.4.12
 signing_key:

data/lib/pundit/matchers/utils/all_actions/actions_matcher.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Pundit
-  module Matchers
-    module Utils
-      module AllActions
-        # Parent class for specific all_action matcher. Should not be used directly.
-        #
-        # Expects methods in child class:
-        # * actual_actions - list of actions which actually matches expected type.
-        class ActionsMatcher
-          attr_reader :policy_info
-
-          def initialize(policy)
-            @policy_info = PolicyInfo.new(policy)
-          end
-
-          def match?
-            missed_expected_actions.empty?
-          end
-
-          def missed_expected_actions
-            @missed_expected_actions ||= expected_actions - actual_actions
-          end
-
-          def policy
-            policy_info.policy
-          end
-
-          private
-
-          def expected_actions
-            policy_info.actions
-          end
-        end
-      end
-    end
-  end
-end