A set of RSpec matchers for testing Pundit authorisation policies. The matcher syntax was inspired by this excellent blog post from Thunderbolt Labs.
Include pundit-matchers
in your Rails application's Gemfile, inside the test group:
group :test do
gem 'pundit-matchers', '~> 1.0.0'
end
And then execute the following command:
bundle
Pundit Matchers requires that both the rspec-rails and pundit gems are also installed.
Add the following to the top of your Rails application's spec/spec_helper.rb
file:
require 'pundit/matchers'
The following RSpec matchers can now be used in your the Pundit policy spec
files (by convention, saved in the spec/policies
directory).
permit_action(:action_name)
Tests that the action, passed in as a parameter, is permitted by the policy.permit_new_and_create_actions
Tests that both the new and create actions are permitted by the policy.permit_edit_and_update_actions
Tests that both the edit and update actions are permitted by the policy.permit_mass_assignment_of(:attribute_name)
Tests that mass assignment of the attribute, passed in as a parameter, is permitted by the policy.
forbid_action(:action_name)
Tests that the action, passed in as a parameter, is not permitted by the policy.forbid_new_and_create_actions
Tests that both the new and create actions are not permitted by the policy.forbid_edit_and_update_actions
Tests that both the edit and update actions are not permitted by the policy.forbid_mass_assignment_of(:attribute_name)
Tests that mass assignment of the attribute, passed in as a parameter, is not permitted by the policy.
The following example shows how to structure a Pundit policy spec (in this
example, the spec would be located in spec/policies/article_policy_spec.rb
)
which authorises administrators to view and destroy articles, while visitors
are only authorised to access the show action and are forbidden to destroy
articles.
require 'rails_helper'
describe ArticlePolicy do
subject { ArticlePolicy.new(user, article) }
let(:article) { Article.create }
context "being a visitor" do
let(:user) { nil }
it { should permit_action(:show) }
it { should forbid_action(:destroy) }
end
context "being an administrator" do
let(:user) { User.create(administrator: true) }
it { should permit_action(:show) }
it { should permit_action(:destroy) }
end
end
Pundit Matchers makes several assumptions about how you're going to structure your policy spec file. First, you should declare a subject for the spec. The subject should be a new instance of the policy class that you're testing. For example:
subject { ArticlePolicy.new(user, article) }
The subject will be implicitly referenced inside of it
blocks throughout the
spec, whenever a permit or forbid matcher is used. The new method of the policy class should also contain the two objects that will be used to authorise each action within the policy: the user who is attempting access to the record and the record which is to be authorised.
Throughout the spec, you can use let
statements to create objects for the
user/record pair which is being authorised. For example, the following
permit_action
matcher would test that the user can destroy articles
containing a user_id
attribute which matches the user's ID:
let(:user) { User.create }
let(:article) { Article.create(user_id: user.id) }
it { should permit_action(:destroy) }
The user and record objects used by the subject policy class will be
reassigned whenever you reassign these using the let
keyword. This will
typically be done on a per context basis, as you will likely want to check the
outcome of an authorisation attempt using different configurations of
user/record pairs based on application state. These variations should be
organised into separate RSpec context blocks, as in the previous example.
It common to write separate authorisation policies on a per action basis. A notable exception to this is in the case of new/create and edit/update action pairs. Generally speaking, you do not want to allow users to access a 'new' form unless the user is also authorised to create the record associated with that form. Similarly, you generally do not want the user to access an 'edit' form unless that user can also update the associated record.
Pundit Matchers provides four shortcut matchers to account for these common scenarios:
permit_new_and_create_actions
permit_edit_and_update_actions
forbid_new_and_create_actions
forbid_edit_and_update_actions
The following example tests a policy which grants administrators permission to create articles, but does not authorise visitors to do the same.
require 'rails_helper'
describe ArticlePolicy do
subject { ArticlePolicy.new(user, article) }
let(:article) { Article.new }
context "being a visitor" do
let(:user) { nil }
it { should forbid_new_and_create_actions }
end
context "being an administrator" do
let(:user) { User.create(administrator: true) }
it { should permit_new_and_create_actions }
end
end
For policies that contain a permitted_attributes
method (to authorise only
particular attributes), Pundit Matchers provides two matchers to test for mass
assignment.
permit_mass_assignment_of(:attribute_name)
forbid_mass_assignment_of(:attribute_name)
Let's modify the earlier example which tests a policy where administrators are granted permission to create articles, but visitors are not authorised to do so. In this updated example, visitors can create articles but they cannot set the publish flag.
require 'rails_helper'
describe ArticlePolicy do
subject { ArticlePolicy.new(user, article) }
let(:article) { Article.new }
context "being a visitor" do
let(:user) { nil }
it { should permit_new_and_create_actions }
it { should forbid_mass_assignment_of(:publish) }
end
context "being an administrator" do
let(:user) { User.create(administrator: true) }
it { should permit_new_and_create_actions }
it { should permit_mass_assignment_of(:publish) }
end
end
Another common scenario is to authorise particular records to be returned
in a collection, based on particular properties of candidate records for that
collection. To test for this you don't need to use any matchers. Instead, you
can test for the inclusion or exclusion of a record in the resolved scope by using the let
keyword to create a resolved scope based on the current user
and record objects used by a Policy::Scope
class.
For example, to test that visitors can only view published articles in a resolved scope you could write your policy spec as follows:
require 'rails_helper'
describe ArticlePolicy do
subject { ArticlePolicy.new(user, article) }
let(:resolved_scope) {
ArticlePolicy::Scope.new(user, Article.all).resolve
}
context "being a visitor" do
let(:user) { nil }
context "accessing a published article" do
let(:article) { Article.create(publish: true) }
it "includes article in resolved scope" do
expect(resolved_scope).to include(article)
end
it { should permit_action(:show) }
end
context "accessing an unpublished article" do
let(:article) { Article.create(publish: false) }
it "excludes article from resolved scope" do
expect(resolved_scope).not_to include(article)
end
it { should forbid_action(:show) }
end
end
end
The advantage of this approach is that it increases the readability of your specs. It allows you to place all of your specifications for authorising a particular context (user and record configuration) inside of a single context block; attempts to access a particular record via both actions and scopes are tested in the same part of the spec.
The following example puts all of the techniques discussed so far together in one policy spec that tests multiple user and record configurations within different context blocks. Here visitors can view published articles and create unpublished articles, while administrators have full access to all articles.
require 'rails_helper'
describe ArticlePolicy do
subject { ArticlePolicy.new(user, article) }
let(:resolved_scope) {
ArticlePolicy::Scope.new(user, Article.all).resolve
}
context "being a visitor" do
let(:user) { nil }
context "creating a new article" do
let(:article) { Article.new }
it { should permit_new_and_create_actions }
it { should forbid_mass_assignment_of(:publish) }
end
context "accessing a published article" do
let(:article) { Article.create(publish: true) }
it "includes article in resolved scope" do
expect(resolved_scope).to include(article)
end
it { should permit_action(:show) }
it { should forbid_edit_and_update_actions }
it { should forbid_action(:destroy) }
it { should forbid_mass_assignment_of(:publish) }
end
context "accessing an unpublished article" do
let(:article) { Article.create(publish: false) }
it "excludes article from resolved scope" do
expect(resolved_scope).not_to include(article)
end
it { should forbid_action(:show) }
it { should forbid_edit_and_update_actions }
it { should forbid_action(:destroy) }
it { should forbid_mass_assignment_of(:publish) }
end
end
context "being an administrator" do
let(:user) { User.create(administrator: true) }
context "creating a new article" do
let(:article) { Article.new }
it { should permit_new_and_create_actions }
it { should permit_mass_assignment_of(:publish) }
end
context "accessing a published article" do
let(:article) { Article.create(publish: true) }
it "includes article in resolved scope" do
expect(resolved_scope).to include(article)
end
it { should permit_action(:show) }
it { should permit_edit_and_update_actions }
it { should permit_action(:destroy) }
it { should permit_mass_assignment_of(:publish) }
end
context "accessing an unpublished article" do
let(:article) { Article.create(publish: false) }
it "includes article in resolved scope" do
expect(resolved_scope).to include(article)
end
it { should permit_action(:show) }
it { should permit_edit_and_update_actions }
it { should permit_action(:destroy) }
it { should permit_mass_assignment_of(:publish) }
end
end
end