### Setup Development Environment

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/CONTRIBUTING.md

Run this script to install all necessary dependencies for working on the project.

```bash
bin/setup
```

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

### Inline Test Setup with Bundler and RSpec

Source: https://github.com/thoughtbot/shoulda-matchers/wiki/Reproducing-bugs-using-inline-test

This script sets up an in-memory SQLite database, defines models, and configures Shoulda Matchers for RSpec. It's designed to be run directly using the `ruby` command.

```ruby
require 'bundler/inline'
require 'rspec/autorun'
require 'rspec/core/formatters/progress_formatter'
require 'rspec/core/profiler'

gemfile true do
  source 'https://rubygems.org'
  gem 'sqlite3'
  gem 'rspec-expectations'

  gem 'activerecord', '~> 5.2'
  gem 'shoulda-matchers', '~> 3.0'
end

require 'active_record'
require 'active_record/relation'

ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')

ActiveRecord::Schema.define do
  create_table :users, force: true do |t|
  end

  create_table :posts, force: true do |t|
    t.references :user, index: true, foreign_key: true
  end
end

class User < ActiveRecord::Base
end

class Post < ActiveRecord::Base
  belongs_to :user
end

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :active_record
  end
end

RSpec.describe Post, type: :model do
  it { is_expected.to belong_to(:user) }

  it { is_expected.to belong_to(:moderator) }
end

```

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

### Include Matchers in Non-Rails Projects

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Manually include ActiveModel and ActiveRecord matchers in RSpec example groups for non-Rails projects.

```ruby
RSpec.describe MySpecialModel do
  include Shoulda::Matchers::ActiveModel
  include Shoulda::Matchers::ActiveRecord
end
```

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

### Configure RSpec to Include Matchers by Type

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Configure RSpec to automatically include ActiveModel and ActiveRecord matchers for example groups tagged with type: :model.

```ruby
RSpec.configure do |config|
  config.include(Shoulda::Matchers::ActiveModel, type: :model)
  config.include(Shoulda::Matchers::ActiveRecord, type: :model)
end
```

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

### ActiveRecord Object with Validation Scopes

Source: https://github.com/thoughtbot/shoulda-matchers/wiki/Usage-with-validation_scopes

An example ActiveRecord model demonstrating standard validations alongside validations defined within a `validation_scope` block. This serves as the target for testing.

```ruby
class Obj < ActiveRecord::Base
  validates :name, presence: true

  validation_scope :warnings do |o|
    o.validates :address, presence: true
  end
end
```

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

### Overriding Subject for Model Validations in Minitest (Shoulda)

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Demonstrates overriding the subject for testing model validations in Minitest using Shoulda, with an example using FactoryBot.

```ruby
# Minitest (Shoulda)
class PostTest < ActiveSupport::TestCase
  context 'validations' do
    subject { build(:post) }

    should validate_presence_of(:title)
  end
end
```

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

### Minitest (Shoulda): Handling Non-Case-Swappable Values with Existing Record

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/docs/errors/NonCaseSwappableValueError.md

For Minitest, when the uniqueness validation is case-sensitive and the test value is non-case-swappable, ensure an existing record with a different, alpha-character-containing value is present. This example shows how to create a user with a unique username.

```ruby
class User < ActiveRecord::Base
  validates_uniqueness_of :username
end

class UserTest < ActiveSupport::TestCase
  context "validations" do
    subject do
      # Note that "123" == "123".swapcase. This is a problem!
      User.new(username: "123")
    end

    should "validate uniqueness of :username" do
      # So you can either override it like this, or just fix the subject.
      user = User.create!(username: "john123")
      assert_accepts validate_uniqueness_of(:username), record
    end
  end
end
```

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

### Controller Test with HTTP Status Assertion in RSpec

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Example of a controller test in RSpec that asserts the HTTP status of a response. Note that some matchers like 'permit' are not suitable for direct use with 'subject' in this context.

```ruby
RSpec.describe PostsController, type: :controller do
  describe 'GET #index' do
    subject { get :index }

    # This may work...
    it { should have_http_status(:success) }
    # ...but this will not!
    it { should permit(:title, :body).for(:post) }
  end
end
```

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

### RSpec: Handling Non-Case-Swappable Values with Existing Record

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/docs/errors/NonCaseSwappableValueError.md

When the uniqueness validation is case-sensitive and the test value is non-case-swappable, provide an existing record with a different value that contains alpha characters. This example demonstrates overriding the subject or fixing it by creating a user with a distinct username.

```ruby
class User < ActiveRecord::Base
  validates_uniqueness_of :username
end

RSpec.describe User, type: :model do
  context "validations" do
    subject do
      # Note that "123" == "123".swapcase. This is a problem!
      User.new(username: "123")
    end

    it do
      # So you can either override it like this, or just fix the subject.
      user = User.create!(username: "john123")
      expect(user).to validate_uniqueness_of(:username)
    end
  end
end
```

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

### View Generated Documentation

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

Open the locally generated documentation in your web browser.

```bash
open doc/index.html
```

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

### Autogenerate YARD Documentation

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

Launch a process that automatically watches source files for changes and generates HTML documentation. This is useful for active documentation updates.

```bash
bundle exec rake docs:autogenerate
```

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

### Publish Specific Version Documentation with Custom Redirect

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

This command allows publishing documentation for a specific version while manually setting the auto-redirected version. Replace 'version' and 'latest_version' with the desired version strings.

```bash
bundle exec rake docs:publish[version, latest_version]
```

```bash
bundle exec rake docs:publish[4.0.0, 3.7.2]
```

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

### List available appraisals

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/CONTRIBUTING.md

Run this command to see a list of all available appraisals, which are Gemfiles tailored for different Rails versions.

```bash
bundle exec appraisal list
```

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

### Run a unit test

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/CONTRIBUTING.md

Execute a specific unit test by providing the appraisal name and the path to the test file. Unit tests exercise matcher code file by file in the context of a real Rails application.

```bash
bundle exec appraisal rails_5_2 rspec spec/unit/shoulda/matchers/active_model/validate_inclusion_of_matcher_spec.rb
```

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

### Publish Latest Documentation

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

Use this command to publish the documentation for the latest version of the gem. It updates the auto-redirect on the index page to point to the most recent version's documentation.

```bash
bundle exec rake docs:publish_latest
```

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

### Run Unit Tests with Zeus

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

Use Zeus for faster unit test execution by preloading the Rails environment. This command targets a specific unit test file.

```bash
bundle exec zeus rspec spec/unit/shoulda/matchers/active_model/validate_inclusion_of_matcher_spec.rb
```

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

### Generate YARD Documentation

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

Generate project documentation locally using YARD. This command processes Ruby files, CHANGELOG.md, and Markdown files in docs/ to create HTML output in the doc directory.

```bash
bundle exec yard doc
```

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

### Run an acceptance test

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/CONTRIBUTING.md

Execute a specific acceptance test using the appraisal name and the test file path. Acceptance tests exercise matchers in the context of a real Ruby or Rails application, with the application set up and torn down for each test.

```bash
bundle exec appraisal rails_5_2 rspec spec/acceptance/rails_integration_spec.rb
```

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

### Run all tests

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/CONTRIBUTING.md

Execute all tests in the project using the rake command. This is a quick way to check your work against the latest supported Ruby and Rails version.

```bash
bundle exec rake
```

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

### Use `is_expected.to` Syntax

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Demonstrates using the `is_expected.to` RSpec syntax with shoulda-matchers, an alternative to the preferred `should` syntax.

```ruby
RSpec.describe Person, type: :model do
  it { is_expected.to validate_presence_of(:name) }
end
```

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

### Run a specific appraisal

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/CONTRIBUTING.md

Use this command to run tests with a specific appraisal, which is a Gemfile centered around a Rails version. This is useful when fixing bugs for a particular Rails version.

```bash
bundle exec appraisal <appraisal name> ...
```

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

### Create Zeus Alias for RSpec

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

Define a shell alias 'zr' for 'bundle exec zeus rspec' to shorten the command for running tests with Zeus.

```bash
alias zr="bundle exec zeus rspec"
```

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

### Controller Test with Response and Render Template Assertions in RSpec

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Shows a controller test in RSpec using 'before' to set up the action and asserting the HTTP status and rendered template. This approach is necessary when 'subject' is not appropriate for certain matchers.

```ruby
RSpec.describe PostsController, type: :controller do
  describe 'GET #index' do
    before { get :index }

    # Notice that we have to assert have_http_status on the response here...
    it { expect(response).to have_http_status(:success) }
    # ...but we do not have to provide a subject for render_template
    it { should render_template('index') }
  end
end
```

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

### Release Gem with Rake Task

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

Use the 'rake release' task to push the gem to RubyGems and publish documentation to GitHub Pages.

```bash
rake release
```

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

### Configure Shoulda::Matchers for Minitest

Source: https://github.com/thoughtbot/shoulda-matchers/wiki/Usage-with-minitest-matchers_vaccine

Configure shoulda-matchers in your test_helper.rb to integrate with the Minitest test framework and Rails library.

```ruby
Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :minitest
    with.library :rails
  end
end
```

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

### Model Associations and Validations in RSpec

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Demonstrates how to test model associations and validations using Shoulda Matchers in an RSpec test suite.

```ruby
# RSpec
RSpec.describe MenuItem, type: :model do
  describe 'associations' do
    it { should belong_to(:category).class_name('MenuCategory') }
  end

  describe 'validations' do
    it { should validate_presence_of(:name) }
    it { should validate_uniqueness_of(:name).scoped_to(:category_id) }
  end
end
```

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

### Configure Shoulda Matchers for Minitest in Non-Rails Apps

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Place this configuration at the bottom of test/test_helper.rb for non-Rails apps using ActiveRecord or ActiveModel.

```ruby
Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :minitest

    # Keep as many of these lines as are necessary:
    with.library :active_record
    with.library :active_model
  end
end
```

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

### Model Associations and Validations in Minitest (Shoulda)

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Shows how to test model associations and validations using Shoulda Matchers within a Minitest test case.

```ruby
# Minitest (Shoulda)
class MenuItemTest < ActiveSupport::TestCase
  context 'associations' do
    should belong_to(:category).class_name('MenuCategory')
  end

  context 'validations' do
    should validate_presence_of(:name)
    should validate_uniqueness_of(:name).scoped_to(:category_id)
  end
end
```

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

### Add Shoulda Gem to Gemfile for Minitest

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

If using the Shoulda umbrella gem, ensure it's the latest version. Otherwise, add shoulda-matchers to your Gemfile.

```ruby
group :test do
  gem 'shoulda', '~> 4.0'
end
```

```ruby
group :test do
  gem 'shoulda-matchers', '~> 7.0'
end
```

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

### Configure Shoulda Matchers for RSpec in Rails Apps

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Place this configuration at the bottom of spec/rails_helper.rb to integrate with RSpec and Rails.

```ruby
Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :rails
  end
end
```

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

### Add minitest-matchers_vaccine to Gemfile

Source: https://github.com/thoughtbot/shoulda-matchers/wiki/Usage-with-minitest-matchers_vaccine

Include the shoulda-matchers and minitest-matchers_vaccine gems in your test group within the Gemfile.

```ruby
group :test do
  gem 'shoulda-matchers'
  gem 'minitest-matchers_vaccine'
end
```

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

### Test Case for Validation Scopes

Source: https://github.com/thoughtbot/shoulda-matchers/wiki/Usage-with-validation_scopes

This test case demonstrates how to use the `rewire_errors_to_warnings` helper to test validations defined within a `validation_scope`. It includes tests for both regular validations and those within the scope.

```ruby
include ValidationScopesHelpers
subject(:obj) { FactoryBot.build :obj }

context "regular validation tests" do
  it { is_expected.to validate_presence_of(:name) }
end

context "validation warning tests" do
  before { rewire_errors_to_warnings(obj) }

  it { is_expected.to validate_presence_of(:address) }
end
```

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

### Configure Shoulda Matchers for RSpec in Non-Rails Apps

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Place this configuration at the bottom of spec/spec_helper.rb for non-Rails apps using ActiveRecord or ActiveModel.

```ruby
Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec

    # Keep as many of these lines as are necessary:
    with.library :active_record
    with.library :active_model
  end
end
```

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

### Grant RubyGems Ownership

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/MAINTAINING.md

Use this command to grant ownership permissions for the shoulda-matchers gem on RubyGems to another user by providing their email address.

```bash
gem owner shoulda-matchers -a <email address>
```

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

### Monkey Patch for Validation Scopes

Source: https://github.com/thoughtbot/shoulda-matchers/wiki/Usage-with-validation_scopes

This helper module rewires an object's `valid?` and `errors` methods to work with validation_scopes by treating warnings as errors. Include this in your test helpers.

```ruby
module ValidationScopesHelpers
  def rewire_errors_to_warnings(object)
    def object.valid?
      has_warnings?
    end

    def object.errors
      warnings
    end
  end
end
```

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

### Test validation with @subject and must in Minitest

Source: https://github.com/thoughtbot/shoulda-matchers/wiki/Usage-with-minitest-matchers_vaccine

Write a Minitest test case using the `@subject` instance variable and `must` for concise validation assertions.

```ruby
class UserTest < Minitest::Test
  def setup
    @subject = User.new
  end

  def test_validation
    must validate_presence_of :email
  end
end
```

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

### Add Shoulda Matchers to Gemfile for RSpec

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Include shoulda-matchers in your test group in the Gemfile. Ensure you are using the latest version.

```ruby
group :test do
  gem 'shoulda-matchers', '~> 7.0'
end
```

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

### Test validation with assert_must in Minitest

Source: https://github.com/thoughtbot/shoulda-matchers/wiki/Usage-with-minitest-matchers_vaccine

Write a Minitest test case to assert that a model validates the presence of a specific attribute using `assert_must`.

```ruby
class UserTest < Minitest::Test
  def test_validation
    user = User.new
    assert_must validate_presence_of(:email), user
  end
end
```

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

### Overriding Subject for Model Validations in RSpec

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/README.md

Illustrates how to override the default subject when testing model validations in RSpec, using FactoryBot to build a model instance.

```ruby
# RSpec
RSpec.describe Post, type: :model do
  describe 'validations' do
    # Here we're using FactoryBot, but you could use anything
    subject { build(:post) }

    it { should validate_presence_of(:title) }
  end
end
```

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

### Minitest (Shoulda): Case-Insensitive Uniqueness Validation

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/docs/errors/NonCaseSwappableValueError.md

For Minitest, to make uniqueness validation case-insensitive, include `case_sensitive: false` in the model's validation and use the `.case_insensitive` modifier with the matcher. This ensures that values like "123" are handled appropriately.

```ruby
class User < ActiveRecord::Base
  validates_uniqueness_of :username, case_sensitive: false
end

class UserTest < ActiveSupport::TestCase
  context "validations" do
    subject do
      # Note that "123" == "123".swapcase, but it's okay
      User.new(username: "123")
    end

    should validate_uniqueness_of(:username).case_insensitive
  end
end
```

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

### RSpec: Case-Insensitive Uniqueness Validation

Source: https://github.com/thoughtbot/shoulda-matchers/blob/main/docs/errors/NonCaseSwappableValueError.md

If the uniqueness validation should not be case-sensitive, add `case_sensitive: false` to the model validation and use the `.case_insensitive` modifier on the matcher. This allows non-case-swappable values to be handled correctly.

```ruby
class User < ActiveRecord::Base
  validates_uniqueness_of :username, case_sensitive: false
end

RSpec.describe User, type: :model do
  context "validations" do
    subject do
      # Note that "123" == "123".swapcase, but it's okay
      User.new(username: "123")
    end

    it { should validate_uniqueness_of(:username).case_insensitive }
  end
end
```

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