### Installing pundit-matchers Gem in Gemfile (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Add the `pundit-matchers` gem to the `:test` group in your application's Gemfile to include it for testing purposes. Specify the desired version constraint.

```Ruby
group :test do
  gem 'pundit-matchers', '~> 4.0'
end
```

--------------------------------

### Example Pundit Policy Spec with Matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

A basic RSpec example demonstrating how to use `pundit-matchers` to test an `ArticlePolicy`. It shows how to define contexts for different user types (visitors, administrators) and use matchers like `permit_only_actions` and `permit_all_actions`.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

  context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to permit_only_actions(%i[index show]) }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to permit_all_actions }
  end
end
```

--------------------------------

### Pulling Latest Main Branch - Shell

Source: https://github.com/pundit-community/pundit-matchers/blob/main/RELEASE.md

Pulls the latest changes from the 'main' branch of the 'origin' remote repository to ensure the local branch is up-to-date before starting the release process.

```Shell
git pull origin main
```

--------------------------------

### Testing New/Create Action Pairs with Pundit Matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Demonstrates the use of shortcut matchers like `forbid_new_and_create_actions` and `permit_new_and_create_actions` to test authorization for common action pairs (`new`/`create`). This example tests whether visitors and administrators are authorized to create articles using an ArticlePolicy. This requires RSpec and the Pundit Matchers gem.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

  context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to forbid_new_and_create_actions }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to permit_new_and_create_actions }
  end
end
```

--------------------------------

### Testing Allowed Actions with permit_only_actions Matcher - Ruby

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Provides a complete RSpec example demonstrating the use of the `permit_only_actions` matcher within different RSpec contexts to test policy permissions for visitors and administrators, ensuring only specified actions are permitted.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

  context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to permit_only_actions(%i[index show]) }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to permit_only_actions(%i[index show new create edit update]) }
  end
end
```

--------------------------------

### Testing Attribute Authorization with Pundit Matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Shows how to test authorization for specific attributes using the `permit_attribute` and `forbid_attribute` matchers, typically used with policies that implement a `permitted_attributes` method. This example tests whether visitors and administrators can set the `:publish` attribute when creating an article. This requires RSpec and the Pundit Matchers gem.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

  context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to permit_new_and_create_actions }
    it { is_expected.to forbid_attribute(:publish) }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to permit_new_and_create_actions }
    it { is_expected.to permit_attribute(:publish) }
  end
end
```

--------------------------------

### Testing Forbidden Actions with forbid_only_actions Matcher - Ruby

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Presents an RSpec example using the `forbid_only_actions` matcher within different contexts to test which actions are explicitly forbidden by the policy for different user types.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

  context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to forbid_only_actions(%i[new create edit update destroy]) }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to forbid_only_actions(%i[destroy]) }
  end
end
```

--------------------------------

### Testing Nested Attribute Permissions (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

This RSpec example demonstrates how to test authorization for nested attributes using the `permit_attribute` matcher in Pundit Matchers, specifying the nested structure using a hash.

```ruby
it 'permits nested attributes for address' do
  is_expected.to(
    permit_attribute(address_attributes: [:country])
  )
end
```

--------------------------------

### Testing Pundit Policy Scope Resolution in RSpec

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

This RSpec example demonstrates how to test a Pundit Policy::Scope's resolution. It uses `let` to define the resolved scope and test records, verifying that published articles are included and unpublished articles are excluded for a visitor (nil user).

```ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:resolved_scope) do
    described_class::Scope.new(user, Article.all).resolve
  end

  let(:user) { nil }

  context 'when visitor accesses a published article' do
    let(:article) { Article.create(publish: true) }

    it 'includes article in resolved scope' do
      expect(resolved_scope).to include(article)
    end
  end

  context 'when visitor accesses 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
  end
end
```

--------------------------------

### Pushing Release Branch - Shell

Source: https://github.com/pundit-community/pundit-matchers/blob/main/RELEASE.md

Pushes the newly created release branch with the committed changes to the 'origin' remote repository on GitHub.

```Shell
git push origin release-version-1.0.0
```

--------------------------------

### Releasing Gem with Rake - Shell

Source: https://github.com/pundit-community/pundit-matchers/blob/main/RELEASE.md

Executes the 'release' Rake task, which automates the process of building the gem, publishing it to RubyGems.org, creating a version tag (prefixed with 'v'), and pushing the tag to GitHub.

```Shell
rake release
```

--------------------------------

### Creating Release Branch - Shell

Source: https://github.com/pundit-community/pundit-matchers/blob/main/RELEASE.md

Creates and switches to a new Git branch specifically for the release, branching off from the current 'main' branch. The branch name should reflect the version number being released.

```Shell
git checkout -b release-version-1.0.0
```

--------------------------------

### Defining Test Data with let and Testing Action Permission - Ruby

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Illustrates using RSpec `let` statements to create test user and article objects and testing if the policy permits a specific action using the `permit_action` matcher.

```Ruby
let(:user) { User.create }
let(:article) { Article.new(user_id: user.id) }

it { is_expected.to permit_action(:destroy) }
```

--------------------------------

### Pundit Matchers Multiple Actions Argument Syntax (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Illustrates the different ways to pass action arguments to the `permit_actions` and `forbid_actions` matchers in Pundit Matchers. It shows equivalent syntax using an array of symbols, an array with `%i` literal, and a list of individual symbols. This requires RSpec and the Pundit Matchers gem.

```Ruby
it { is_expected.to forbid_actions([:show, :create, :update]) }
it { is_expected.to forbid_actions(%i[show create update]) }
it { is_expected.to forbid_actions(:show, :create, :update) }
```

--------------------------------

### Committing Release Changes - Shell

Source: https://github.com/pundit-community/pundit-matchers/blob/main/RELEASE.md

Commits the changes made for the release (e.g., updates to CHANGELOG, README, gemspec) to the current branch. The commit message should clearly indicate the release version.

```Shell
git commit -am "Release version 1.0.0"
```

--------------------------------

### Equivalent Syntax for permit_attributes Matcher (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

This snippet illustrates different ways to pass attributes to the `permit_attributes` and `permit_mass_assignment_of` matchers in Pundit Matchers, showing that arrays, symbols, and multiple arguments are accepted and equivalent.

```ruby
it { is_expected.to permit_attributes([:first_name, :last_name]) }
it { is_expected.to permit_attributes(%i[first_name last_name]) }
it { is_expected.to permit_attributes(:first_name, :last_name) }
it { is_expected.to permit_mass_assignment_of(:first_name, :last_name) }
```

--------------------------------

### Testing Multiple Actions Authorization with Pundit Matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Shows how to test authorization for multiple actions using the `permit_only_actions` and `forbid_actions` matchers in RSpec. It defines contexts for different user roles (visitor, administrator) and verifies which actions are permitted or forbidden for each role on an ArticlePolicy. This requires RSpec and the Pundit Matchers gem.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

  context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to permit_only_actions(%i[index show]) }
    it { is_expected.to forbid_actions(%i[create update destroy]) }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to permit_only_actions(%i[index show new create edit update]) }
    it { is_expected.to forbid_actions(%i[destroy]) }
  end
end
```

--------------------------------

### Testing ArticlePolicy for Administrators with pundit-matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

RSpec spec file testing the `ArticlePolicy` for an administrator user. It defines contexts for creating new articles, accessing published articles, and accessing unpublished articles, verifying permitted actions and attributes using `pundit-matchers`. Administrators generally have broader permissions than visitors.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:resolved_scope) do
    described_class::Scope.new(user, Article.all).resolve
  end

  let(:user) { User.new(administrator: true) }

  context 'when administrator creates a new article' do
    let(:article) { Article.new }

    it { is_expected.to permit_new_and_create_actions }
  end

  context 'when administrator accesses 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 { is_expected.to permit_all_actions }
  end

  context 'when administrator accesses 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 { is_expected.to permit_all_actions }
  end

  describe 'permitted attributes for administrator' do
    it { is_expected.to permit_attribute(:publish) }
    it do
      is_expected.to permit_attribute(:publish).for_action(:create)
    end
    it do
      is_expected.to permit_attribute(:publish).for_action(:update)
    end
    it { is_expected.to permit_attribute(:slug) }
    it { is_expected.to permit_attribute(:slug).for_action(:create) }
    it { is_expected.to permit_attribute(:slug).for_action(:update) }
  end
end
```

--------------------------------

### Testing All Actions with permit_all_actions and forbid_all_actions Matchers - Ruby

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Illustrates the use of the `forbid_all_actions` and `permit_all_actions` matchers as shorthand for testing policies where all actions are expected to be either forbidden or permitted, shown within different user contexts.

```Ruby
RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

   context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to forbid_all_actions }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to permit_all_actions }
  end
end
```

--------------------------------

### Testing ArticlePolicy for Visitors with pundit-matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

RSpec spec file testing the `ArticlePolicy` for a visitor user. It defines contexts for creating new articles, accessing published articles, and accessing unpublished articles, verifying permitted actions and attributes using `pundit-matchers`.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:resolved_scope) do
    described_class::Scope.new(user, Article.all).resolve
  end

  let(:user) { nil }

  context 'when visitor creates a new article' do
    let(:article) { Article.new }

    it { is_expected.to permit_new_and_create_actions }
  end

  context 'when visitor accesses 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 { is_expected.to permit_only_actions(%i[index show]) }
  end

  context 'when visitor accesses 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 { is_expected.to forbid_all_actions }
  end

  describe 'permitted attributes for visitor' do
    it { is_expected.to forbid_attribute(:publish) }
    it do
      is_expected.to forbid_attribute(:publish).for_action(:create)
    end
    it do
      is_expected.to forbid_attribute(:publish).for_action(:update)
    end
    it { is_expected.to forbid_attribute(:slug) }
    it { is_expected.to permit_attribute(:slug).for_action(:create) }
    it { is_expected.to forbid_attribute(:slug).for_action(:update) }
  end
end
```

--------------------------------

### Testing Action-Specific Attribute Permissions with Pundit Matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

This RSpec test suite shows how to use the composable `permit_attribute(...).for_action(...)` and `forbid_attribute(...).for_action(...)` matchers to test attribute authorization that varies based on the action being performed (e.g., `:create` vs `:update`) for different user roles.

```ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

  context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to permit_only_actions(%i[new create edit update]) }
    it { is_expected.to forbid_attribute(:slug) }
    it { is_expected.to permit_attribute(:slug).for_action(:create) }
    it { is_expected.to forbid_attribute(:slug).for_action(:update) }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to permit_only_actions(%i[new create edit update]) }
    it { is_expected.to permit_attribute(:slug) }
    it { is_expected.to permit_attribute(:slug).for_action(:create) }
    it { is_expected.to permit_attribute(:slug).for_action(:update) }
  end
end
```

--------------------------------

### Testing Attribute Permissions with Pundit Matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

This RSpec test suite demonstrates how to use the `permit_attribute` and `forbid_attribute` matchers from Pundit Matchers to verify attribute authorization for different user roles (visitors and administrators) on an `ArticlePolicy`. It shows how to test single attributes and arrays of attributes.

```ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:article) { Article.new }

  context 'with visitors' do
    let(:user) { nil }

    it { is_expected.to permit_attribute(:name) }
    it { is_expected.to forbid_attribute(:description) }
  end

  context 'with administrators' do
    let(:user) { User.new(administrator: true) }

    it { is_expected.to permit_attributes(%i[name description]) }
  end
end
```

--------------------------------

### Testing Single Action Authorization with Pundit Matchers (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Demonstrates how to test authorization for a single action (e.g., `:update`) within an RSpec test for a Pundit policy. It uses the `permit_action` and `forbid_action` matchers to verify policy behavior based on different user contexts (e.g., author vs. non-author). This requires RSpec and the Pundit Matchers gem.

```Ruby
require 'rails_helper'

RSpec.describe ArticlePolicy do
  subject { described_class.new(user, article) }

  let(:user) { User.create }

  context 'when user updates an article that they authored' do
    let(:article) { Article.create(user_id: user.id) }

    it { is_expected.to permit_action(:update) }
  end

  context 'when user updates an article that they did not author' do
    let(:article) { Article.create(user_id: nil) }

    it { is_expected.to forbid_action(:update) }
  end
end
```

--------------------------------

### Run Rubocop Code Style Check (Shell)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Execute the Rubocop linter script to check for code style violations before submitting a pull request. The goal is to ensure no new violations are introduced.

```Shell
bin/rubocop
```

--------------------------------

### Requiring pundit-matchers in spec_helper (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Include the `pundit/matchers` library at the top of your RSpec `spec_helper.rb` file to make the matchers available in your tests.

```Ruby
require 'pundit/matchers'
```

--------------------------------

### Configuring Pundit Matchers User Aliases (Ruby)

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Configure `pundit-matchers` to use a different attribute name for the "user" model (e.g., `:account`) globally or for specific policies if your application uses a non-standard naming convention.

```Ruby
Pundit::Matchers.configure do |config|
  # Change the default user alias
  config.default_user_alias = :account

  # Change the user alias for a specific policy
  config.user_aliases = { 'Post' => :account }
end
```

--------------------------------

### Declaring RSpec Subject for Pundit Policy - Ruby

Source: https://github.com/pundit-community/pundit-matchers/blob/main/README.md

Defines the RSpec subject for a Pundit policy spec, initializing it with the user and record objects that the policy will use for authorization checks.

```Ruby
subject { described_class.new(user, article) }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.