Merge pull request #806 from gregfletch/refactor/gregfletch/allow-cus…

…tom-rspec-matcher-description

Add customizable permit matcher description

README.md

@@ -783,6 +783,37 @@ describe PostPolicy do
 end
 ```
 
+You can customize the description used for the `permit` matcher:
+
+``` ruby
+Pundit::RSpec::Matchers.description =
+  "permit the user"
+```
+
+given the spec
+
+```ruby
+permissions :update?, :show? do
+  it { expect(policy).to permit(user, record) }
+end
+```
+
+will change the output from
+
+```
+update? and show?
+  is expected to permit #<User id: 105> and #<User id: 106>
+```
+
+to
+
+```
+update? and show?
+  is expected to permit the user
+```
+
+which may be desirable when distributing policy specs as documentation.
+
 An alternative approach to Pundit policy specs is scoping them to a user context as outlined in this
 [excellent post](http://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/) and implemented in the third party [pundit-matchers](https://github.com/punditcommunity/pundit-matchers) gem.
 

lib/pundit/rspec.rb

@@ -5,6 +5,16 @@ module RSpec
     module Matchers
       extend ::RSpec::Matchers::DSL
 
+      class << self
+        attr_writer :description
+
+        def description(user, record)
+          return @description.call(user, record) if defined?(@description) && @description.respond_to?(:call)
+
+          @description
+        end
+      end
+
       # rubocop:disable Metrics/BlockLength
       matcher :permit do |user, record|
         match_proc = lambda do |policy|
@@ -33,6 +43,10 @@ module Matchers
           "#{record} but #{@violating_permissions.to_sentence} #{was_were} granted"
         end
 
+        description do
+          Pundit::RSpec::Matchers.description(user, record) || super()
+        end
+
         if respond_to?(:match_when_negated)
           match(&match_proc)
           match_when_negated(&match_when_negated_proc)

spec/policies/post_policy_spec.rb

@@ -18,5 +18,32 @@
         should permit(user, other_post)
       end.to raise_error(RSpec::Expectations::ExpectationNotMetError)
     end
+
+    it "uses the default description if not overridden" do
+      expect(permit(user, own_post).description).to eq("permit #{user.inspect} and #{own_post.inspect}")
+    end
+
+    context "when the matcher description is overridden" do
+      after do
+        Pundit::RSpec::Matchers.description = nil
+      end
+
+      it "sets a custom matcher description with a Proc" do
+        allow(user).to receive(:role).and_return("default_role")
+        allow(own_post).to receive(:id).and_return(1)
+
+        Pundit::RSpec::Matchers.description = lambda { |user, record|
+          "permit user with role #{user.role} to access record with ID #{record.id}"
+        }
+
+        description = permit(user, own_post).description
+        expect(description).to eq("permit user with role default_role to access record with ID 1")
+      end
+
+      it "sets a custom matcher description with a string" do
+        Pundit::RSpec::Matchers.description = "permit user"
+        expect(permit(user, own_post).description).to eq("permit user")
+      end
+    end
   end
 end