Merge pull request #822 from varvet/kbs/adjust-readme

Update README around rspec helper description change

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Improve the `NotAuthorizedError` message to include the policy class.
 Furthermore, in the case where the record passed is a class instead of an instance, the class name is given. (#812)
+- Add customizable permit matcher description (#806)
 
 ## 2.3.2 (2024-05-08)
 

CODE_OF_CONDUCT.md

@@ -25,4 +25,4 @@ maintainers.
 
 This Code of Conduct is adapted from the [Contributor
 Covenant](http:contributor-covenant.org), version 1.0.0, available at
-[http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)
+[https://contributor-covenant.org/version/1/0/0/](https://contributor-covenant.org/version/1/0/0/)

README.md

@@ -2,16 +2,16 @@
 
 [![Main](https://github.com/varvet/pundit/actions/workflows/main.yml/badge.svg)](https://github.com/varvet/pundit/actions/workflows/main.yml)
 [![Code Climate](https://api.codeclimate.com/v1/badges/a940030f96c9fb43046a/maintainability)](https://codeclimate.com/github/varvet/pundit/maintainability)
-[![Inline docs](http://inch-ci.org/github/varvet/pundit.svg?branch=main)](http://inch-ci.org/github/varvet/pundit)
-[![Gem Version](https://badge.fury.io/rb/pundit.svg)](http://badge.fury.io/rb/pundit)
+[![Inline docs](https://inch-ci.org/github/varvet/pundit.svg?branch=main)](https://inch-ci.org/github/varvet/pundit)
+[![Gem Version](https://badge.fury.io/rb/pundit.svg)](https://badge.fury.io/rb/pundit)
 
 Pundit provides a set of helpers which guide you in leveraging regular Ruby
 classes and object oriented design patterns to build a straightforward, robust, and
 scalable authorization system.
 
 ## Links:
 
-- [API documentation for the most recent version](http://www.rubydoc.info/gems/pundit)
+- [API documentation for the most recent version](https://www.rubydoc.info/gems/pundit)
 - [Source Code](https://github.com/varvet/pundit)
 - [Contributing](https://github.com/varvet/pundit/blob/main/CONTRIBUTING.md)
 - [Code of Conduct](https://github.com/varvet/pundit/blob/main/CODE_OF_CONDUCT.md)
@@ -496,7 +496,7 @@ end
 ## Rescuing a denied Authorization in Rails
 
 Pundit raises a `Pundit::NotAuthorizedError` you can
-[rescue_from](http://guides.rubyonrails.org/action_controller_overview.html#rescue-from)
+[rescue_from](https://guides.rubyonrails.org/action_controller_overview.html#rescue-from)
 in your `ApplicationController`. You can customize the `user_not_authorized`
 method in every controller.
 
@@ -761,6 +761,10 @@ end
 
 ### Policy Specs
 
+> [!TIP]
+> An alternative approach to Pundit policy specs is scoping them to a user context as outlined in this
+[excellent post](https://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.
+
 Pundit includes a mini-DSL for writing expressive tests for your policies in RSpec.
 Require `pundit/rspec` in your `spec_helper.rb`:
 
@@ -790,40 +794,33 @@ describe PostPolicy do
 end
 ```
 
-You can customize the description used for the `permit` matcher:
+### Custom matcher description
+
+By default rspec includes an inspected `user` and `record` in the matcher description, which might become overly verbose:
 
-``` ruby
-Pundit::RSpec::Matchers.description =
-  "permit the user"
+```
+PostPolicy
+  update? and show?
+    is expected to permit #<User:0x0000000104aefd80> and #<Post:0x0000000104aef8d0 @user=#<User:0x0000000104aefd80>>
 ```
 
-given the spec
+You can override the default description with a static string, or a block:
 
 ```ruby
-permissions :update?, :show? do
-  it { expect(policy).to permit(user, record) }
+# static alternative: Pundit::RSpec::Matchers.description = "permit the user"
+Pundit::RSpec::Matchers.description = ->(user, record) do
+  "permit user with role #{user.role} to access record with ID #{record.id}"
 end
 ```
 
-will change the output from
-
-```
-update? and show?
-  is expected to permit #<User id: 105> and #<User id: 106>
-```
-
-to
+Which would make for a less chatty output:
 
 ```
-update? and show?
-  is expected to permit the user
+PostPolicy
+  update? and show?
+    is expected to permit user with role admin to access record with ID 130
 ```
 
-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.
-
 ### Scope Specs
 
 Pundit does not provide a DSL for testing scopes. Test them like you would a regular Ruby class!
@@ -841,15 +838,15 @@ inherit_gem:
 # External Resources
 
 - [RailsApps Example Application: Pundit and Devise](https://github.com/RailsApps/rails-devise-pundit)
-- [Migrating to Pundit from CanCan](http://blog.carbonfive.com/2013/10/21/migrating-to-pundit-from-cancan/)
-- [Testing Pundit Policies with RSpec](http://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/)
+- [Migrating to Pundit from CanCan](https://blog.carbonfive.com/2013/10/21/migrating-to-pundit-from-cancan/)
+- [Testing Pundit Policies with RSpec](https://thunderboltlabs.com/blog/2013/03/27/testing-pundit-policies-with-rspec/)
 - [Testing Pundit with Minitest](https://github.com/varvet/pundit/issues/204#issuecomment-60166450)
 - [Using Pundit outside of a Rails controller](https://github.com/varvet/pundit/pull/136)
-- [Straightforward Rails Authorization with Pundit](http://www.sitepoint.com/straightforward-rails-authorization-with-pundit/)
+- [Straightforward Rails Authorization with Pundit](https://www.sitepoint.com/straightforward-rails-authorization-with-pundit/)
 
 ## Other implementations
 
-- [Flask-Pundit](https://github.com/anurag90x/flask-pundit) (Python) is a [Flask](http://flask.pocoo.org/) extension "heavily inspired by" Pundit
+- [Flask-Pundit](https://github.com/anurag90x/flask-pundit) (Python) is a [Flask](https://flask.pocoo.org/) extension "heavily inspired by" Pundit
 
 # License