action_policy 0.2.4 → 0.3.0.beta1

data/docs/testing.md

@@ -3,8 +3,158 @@
 Authorization is one of the crucial parts of your application. Hence, it should be thoroughly tested (that is the place where 100% coverage makes sense).
 
 When you use policies for authorization, it is possible to split testing into two parts:
-- Test that **the required authorization is performed** within your authorization layer (controller, channel, etc.);
-- Test the policy class itself.
+- Test the policy class itself
+- Test that **the required authorization is performed** within your authorization layer (controller, channel, etc.)
+- Test that **the required scoping has been applied**.
+
+## Testing policies
+
+You can test policies as plain-old Ruby classes, no special tooling is required.
+
+Consider an RSpec example:
+
+```ruby
+describe PostPolicy do
+  let(:user) { build_stubbed(:user) }
+  let(:post) { build_stubbed(:post) }
+
+  let(:policy) { described_class.new(post, user: user) }
+
+  describe "#update?" do
+    subject { policy.apply(:update?) }
+
+    it "returns false when the user is not admin nor author" do
+      is_expected.to eq false
+    end
+
+    context "when the user is admin" do
+      let(:user) { build_stubbed(:user, :admin) }
+
+      it { is_expected.to eq true }
+    end
+
+    context "when the user is an author" do
+      let(:post) { build_stubbed(:post, user: user) }
+
+      it { is_expected.to eq true }
+    end
+  end
+end
+```
+
+### RSpec DSL
+
+We also provide a simple RSpec DSL which aims to reduce the boilerplate when writing
+policies specs.
+
+Example:
+
+```ruby
+# Add this to your spec_helper.rb / rails_helper.rb
+require "action_policy/rspec/dsl"
+
+describe PostPolicy do
+  let(:user) { build_stubbed :user }
+  # `record` must be defined – it is the authorization target
+  let(:record) { build_stubbed :post, draft: false }
+
+  # `context` is the authorization context
+  let(:context) { {user: user} }
+
+  # `describe_rule` is a combination of
+  # `describe` and `subject { ... }` (returns the result of
+  # applying the rule to the record)
+  describe_rule :show? do
+    # `succeed` is `context` + `specify`, which checks
+    # that the result of application is successful
+    succeed "when post is published"
+
+    # `succeed` is `context` + `specify`, which checks
+    # that the result of application wasn't successful
+    failed "when post is draft" do
+      before { post.draft = false }
+
+      succeed "when user is a manager" do
+        before { user.role = "manager" }
+      end
+    end
+  end
+end
+```
+
+If test failed the exception message includes the result and [failure reasons](reasons) (if any):
+
+```
+1) PostPolucy#show? when post is draft
+Failure/Error:  ...
+
+Expected to fail but succeed:
+<PostPolicy#show?: true (reasons: ...)>
+```
+
+If you have [debugging utils](debugging) installed the message also includes the _annotated_
+source code of the policy rule:
+
+```
+1) UserPolucy#manage? when post is draft
+Failure/Error:  ...
+
+Expected to fail but succeed:
+<PostPolicy#show?: true (reasons: ...)>
+↳ user.admin? #=> true
+OR
+!record.draft? #=> false
+```
+
+**NOTE:** DSL for focusing or skipping examples and groups is also available (e.g. `xdescribe_rule`, `fsucceed`, etc.).
+
+**NOTE:** the DSL is included only to example with the tag `type: :policy` or in the `spec/policies` folder. If you want to add this DSL to other examples, add `include ActionPolicy::RSpec::PolicyExampleGroup`.
+
+### Testing scopes
+
+There is no single rule on how to test scopes, 'cause it dependes on the _nature_ of the scope.
+
+Here's an example of RSpec tests for Active Record scoping rules:
+
+```ruby
+describe PostPolicy do
+  describe "relation scope" do
+    let(:user) { build_stubbed :user }
+    let(:context) { {user: user} }
+
+    # Feel free to replace with `before_all` from `test-prof`:
+    # https://test-prof.evilmartians.io/#/before_all
+    before do
+      create(:post, name: "A")
+      create(:post, name: "B", draft: true)
+    end
+
+    let(:target) do
+      # We want to make sure that only the records created
+      # for this test are affected, and they have a deterministic order
+      Post.where(name: %w[A B]).order(name: :asc)
+    end
+
+    subject { policy.apply_scope(target, type: :active_record_relation).pluck(:name) }
+
+    context "as user" do
+      it { is_expected.to eq(%w[A]) }
+    end
+
+    context "as manager" do
+      before { user.update!(role: :manager) }
+
+      it { is_expected.to eq(%w[A B]) }
+    end
+
+    context "as banned user" do
+      before { user.update!(banned: true) }
+
+      it { is_expected.to be_empty }
+    end
+  end
+end
+```
 
 ## Testing authorization
 
@@ -80,37 +230,98 @@ end
 
 If you omit `.with(PostPolicy)` then the inferred policy for the target (`post`) would be used.
 
-## Testing policies
+## Testing scoping
 
-You can test policies as plain-old Ruby classes, no special tooling is required.
+Action Policy provides a way to test that a correct scoping has been applied during the code execution.
 
-Consider an RSpec example:
+For example, you can test that in your `#index` action the correct scoping is used:
 
 ```ruby
-describe PostPolicy do
-  let(:user) { build_stubbed(:user) }
-  let(:post) { build_stubbed(:post) }
+class UsersController < ApplicationController
+  def index
+    @user = authorized(User.all)
+  end
+end
+```
 
-  let(:policy) { described_class.new(post, user: user) }
+### Minitest
 
-  describe "#update?" do
-    subject { policy.apply(:update?) }
+Include `ActionPolicy::TestHelper` to your test class and you'll be able to use
+`assert_have_authorized_scope` assertion:
 
-    it "returns false when the user is not admin nor author" do
-      is_expected.to eq false
-    end
+```ruby
+# in your test
+require "action_policy/test_helper"
 
-    context "when the user is admin" do
-      let(:user) { build_stubbed(:user, :admin) }
+class UsersControllerTest < ActionDispatch::IntegrationTest
+  include ActionPolicy::TestHelper
 
-      it { is_expected.to eq true }
+  test "index has authorized scope" do
+    sign_in users(:john)
+
+    assert_have_authorized_scope(type: :active_record_relation, with: UserPolicy) do
+      get :index
     end
+  end
+end
+```
 
-    context "when the user is an author" do
-      let(:post) { build_stubbed(:post, user: user) }
+You can also specify `as` and `scope_options` options.
 
-      it { is_expected.to eq true }
-    end
+**NOTE:** both `type` and `with` params are required.
+
+It's not possible to test that a scoped has been applied to a particular _target_ but we provide
+a way to perform additional assertions against the matching target (if the assertion didn't fail):
+
+```ruby
+test "index has authorized scope" do
+  sign_in users(:john)
+
+  assert_have_authorized_scope(type: :active_record_relation, with: UserPolicy) do
+    get :index
+  end.with_target do |target|
+    # target is a object passed to `authorized` call
+    assert_equal User.all, target
+  end
+end
+```
+
+### RSpec
+
+Add the following to your `rails_helper.rb` (or `spec_helper.rb`):
+
+```ruby
+require "action_policy/rspec"
+```
+
+Now you can use `have_authorized_scope` matcher:
+
+```ruby
+describe UsersController do
+  subject { get :index }
+
+  it "has authorized scope" do
+    expect { subject }.to have_authorized_scope(:active_record_relation)
+      .with(PostPolicy)
   end
 end
 ```
+
+You can also add `.as(:named_scope)` and `with_scope_options(options_hash)` options.
+
+RSpec composed matchers are available as scope options:
+
+```ruby
+expect { subject }.to have_authorized_scope(:scope)
+  .with_scope_options(matching(with_deleted: a_falsey_value))
+```
+
+You can use the `with_target` modifier to run additional expectations against the matching target (if the matcher didn't fail):
+
+```ruby
+expect { subject }.to have_authorized_scope(:scope)
+  .with_scope_options(matching(with_deleted: a_falsey_value))
+  .with_target { |target|
+    expect(target).to eq(User.all)
+  }
+```

data/docs/writing_policies.md

@@ -20,7 +20,7 @@ end
 
 ## Initializing policies
 
-**NOTE**: it is not recommended to manually initialize policy objects and use them directly (one exclusion–[tests](testing.md)). Use `authorize!` / `allowed_to?` methods instead.
+**NOTE**: it is not recommended to manually initialize policy objects and use them directly (one exclusion–[tests](testing.md)). Use [`authorize!` / `allowed_to?` methods](./behaviour.md#authorize) instead.
 
 To initialize policy object, you should specify target record and context:
 

data/gemfiles/jruby.gemfile

@@ -1,5 +1,8 @@
 source "https://rubygems.org"
 
+gem "activerecord-jdbcsqlite3-adapter", "~> 52.0"
+gem "jdbc-sqlite3"
+
 gem "rails", "~> 5.0"
 
 gemspec path: ".."

data/gemfiles/rails42.gemfile

@@ -1,5 +1,8 @@
 source "https://rubygems.org"
 
+gem "sqlite3", "~> 1.3.0"
 gem "rails", "~> 4.2"
+gem "method_source"
+gem "unparser"
 
 gemspec path: ".."

data/gemfiles/rails6.gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+gem "sqlite3"
+gem "rails", "6.0.0.beta3"
+gem "method_source"
+gem "unparser"
+
+gemspec path: ".."

data/gemfiles/railsmaster.gemfile

@@ -1,6 +1,6 @@
 source "https://rubygems.org"
 
-gem "arel", github: "rails/arel"
+gem "sqlite3", "~> 1.3.0"
 gem "rails", github: "rails/rails"
 
 gemspec path: ".."

data/lib/action_policy.rb

@@ -20,16 +20,16 @@ module ActionPolicy
   require "action_policy/version"
   require "action_policy/base"
   require "action_policy/lookup_chain"
-  require "action_policy/authorizer"
   require "action_policy/behaviour"
+  require "action_policy/i18n" if defined?(::I18n)
 
   class << self
     attr_accessor :cache_store
 
     # Find a policy class for a target
-    def lookup(target, **options)
+    def lookup(target, allow_nil: false, **options)
       LookupChain.call(target, options) ||
-        raise(NotFound, target)
+        (allow_nil ? nil : raise(NotFound, target))
     end
   end
 

data/lib/action_policy/authorizer.rb

@@ -14,16 +14,24 @@ module ActionPolicy
     end
   end
 
-  # Performs authorization, raises an exception when check failed.
-  #
-  # The main purpose of this module is to extact authorize action
+  # The main purpose of this module is to extact authorize actions
   # from everything else to make it easily testable.
   module Authorizer
     class << self
+      # Performs authorization, raises an exception when check failed.
       def call(policy, rule)
-        policy.apply(rule) ||
+        authorize(policy, rule) ||
           raise(::ActionPolicy::Unauthorized.new(policy, rule))
       end
+
+      def authorize(policy, rule)
+        policy.apply(rule)
+      end
+
+      # Applies scope to the target
+      def scopify(target, policy, **options)
+        policy.apply_scope(target, **options)
+      end
     end
   end
 end

data/lib/action_policy/base.rb

@@ -9,6 +9,7 @@ module ActionPolicy
     require "action_policy/policy/reasons"
     require "action_policy/policy/pre_check"
     require "action_policy/policy/aliases"
+    require "action_policy/policy/scoping"
     require "action_policy/policy/cache"
     require "action_policy/policy/cached_apply"
 
@@ -17,6 +18,7 @@ module ActionPolicy
     include ActionPolicy::Policy::PreCheck
     include ActionPolicy::Policy::Reasons
     include ActionPolicy::Policy::Aliases
+    include ActionPolicy::Policy::Scoping
     include ActionPolicy::Policy::Cache
     include ActionPolicy::Policy::CachedApply
     include ActionPolicy::Policy::Defaults

data/lib/action_policy/behaviour.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require "action_policy/behaviours/policy_for"
+require "action_policy/behaviours/scoping"
 require "action_policy/behaviours/memoized"
 require "action_policy/behaviours/thread_memoized"
 require "action_policy/behaviours/namespaced"
 
+require "action_policy/authorizer"
+
 module ActionPolicy
   # Provides `authorize!` and `allowed_to?` methods and
   # `authorize` class method to define authorization context.
@@ -12,6 +15,7 @@ module ActionPolicy
   # Could be included anywhere to perform authorization.
   module Behaviour
     include ActionPolicy::Behaviours::PolicyFor
+    include ActionPolicy::Behaviours::Scoping
 
     def self.included(base)
       # Handle ActiveSupport::Concern differently
@@ -30,7 +34,10 @@ module ActionPolicy
     # (unless explicitly specified through `with` option).
     #
     # Raises `ActionPolicy::Unauthorized` if check failed.
-    def authorize!(record, to:, **options)
+    def authorize!(record = :__undef__, to:, **options)
+      record = implicit_authorization_target if record == :__undef__
+      raise ArgumentError, "Record must be specified" if record.nil?
+
       policy = policy_for(record: record, **options)
 
       Authorizer.call(policy, authorization_rule_for(policy, to))
@@ -39,8 +46,12 @@ module ActionPolicy
     # Checks that an activity is allowed for the current context (e.g. user).
     #
     # Returns true of false.
-    def allowed_to?(rule, record, **options)
+    def allowed_to?(rule, record = :__undef__, **options)
+      record = implicit_authorization_target if record == :__undef__
+      raise ArgumentError, "Record must be specified" if record.nil?
+
       policy = policy_for(record: record, **options)
+
       policy.apply(authorization_rule_for(policy, rule))
     end
 
@@ -49,7 +60,7 @@ module ActionPolicy
         instance_variable_defined?(:@__authorization_context)
 
       @__authorization_context = self.class.authorization_targets
-                                     .each_with_object({}) do |(key, meth), obj|
+        .each_with_object({}) do |(key, meth), obj|
         obj[key] = send(meth)
       end
     end

data/lib/action_policy/behaviours/memoized.rb

@@ -36,7 +36,7 @@ module ActionPolicy
         end
       end
 
-      def __policy_memoize__(record, with: nil, namespace: nil)
+      def __policy_memoize__(record, with: nil, namespace: nil, **_opts)
         record_key = record._policy_cache_key(use_object_id: true)
         cache_key = "#{namespace}/#{with}/#{record_key}"