### Home Classes Methods

### In Files

- lib/shoulda/active_record/matchers.rb
- lib/shoulda/active_record/matchers/validate_numericality_of_matcher.rb
- lib/shoulda/active_record/matchers/validate_format_of_matcher.rb
- lib/shoulda/active_record/matchers/validation_matcher.rb
- lib/shoulda/active_record/matchers/validate_uniqueness_of_matcher.rb
- lib/shoulda/active_record/matchers/validate_presence_of_matcher.rb
- lib/shoulda/active_record/matchers/allow_mass_assignment_of_matcher.rb
- lib/shoulda/active_record/matchers/ensure_inclusion_of_matcher.rb
- lib/shoulda/active_record/matchers/validate_acceptance_of_matcher.rb
- lib/shoulda/active_record/matchers/ensure_length_of_matcher.rb
- lib/shoulda/active_record/matchers/have_db_column_matcher.rb
- lib/shoulda/active_record/matchers/association_matcher.rb
- lib/shoulda/active_record/matchers/have_db_index_matcher.rb
- lib/shoulda/active_record/matchers/allow_value_matcher.rb
- lib/shoulda/active_record/matchers/have_readonly_attribute_matcher.rb

### Methods

- #allow_mass_assignment_of
- #allow_value
- #belong_to
- #ensure_inclusion_of
- #ensure_length_of
- #have_and_belong_to_many
- #have_db_column
- #have_db_index
- #have_many
- #have_one
- #have_readonly_attribute
- #validate_acceptance_of
- #validate_format_of
- #validate_numericality_of
- #validate_presence_of
- #validate_uniqueness_of

### Files

- CONTRIBUTION_GUIDELINES.rdoc
- README.rdoc

### Class/Module Index

Quicksearch

- Shoulda
- Shoulda::ActionController
- Shoulda::ActionController::Macros
- Shoulda::ActionController::Matchers
- Shoulda::ActionMailer
- Shoulda::ActionMailer::Assertions
- Shoulda::ActionMailer::Matchers
- Shoulda::ActiveRecord
- Shoulda::ActiveRecord::Assertions
- Shoulda::ActiveRecord::Helpers
- Shoulda::ActiveRecord::Macros
- Shoulda::ActiveRecord::Matchers
- Shoulda::Assertions
- Shoulda::ClassMethods
- Shoulda::Helpers
- Shoulda::InstanceMethods
- Shoulda::Macros
- ActionController
- Test

No matching classes.

# Shoulda::ActiveRecord::Matchers

# Matchers for your active record models

These matchers will test most of the validations and associations for your ActiveRecord models.

    describe User do
      it { should validate_presence_of(:name) }
      it { should validate_presence_of(:phone_number) }
      %w(abcd 1234).each do |value|
        it { should_not allow_value(value).for(:phone_number) }
      end
      it { should allow_value("(123) 456-7890").for(:phone_number) }
      it { should_not allow_mass_assignment_of(:password) }
      it { should have_one(:profile) }
      it { should have_many(:dogs) }
      it { should have_many(:messes).through(:dogs) }
      it { should belong_to(:lover) }
    end

### Public Instance Methods

allow_mass_assignment_of(value) click to toggle source

Ensures that the attribute can be set on mass update.

    it { should_not allow_mass_assignment_of(:password) }
    it { should allow_mass_assignment_of(:first_name) }

    # File lib/shoulda/active_record/matchers/allow_mass_assignment_of_matcher.rb, line 10
    def allow_mass_assignment_of(value)
      AllowMassAssignmentOfMatcher.new(value)
    end

allow_value(value) click to toggle source

Ensures that the attribute can be set to the given value.

Options:

- `with_message` - value the test expects to find in `errors.on(:attribute)`. Regexp or string. If omitted, the test looks for any errors in `errors.on(:attribute)`.

Example:

    it { should_not allow_value('bad').for(:isbn) }
    it { should allow_value("isbn 1 2345 6789 0").for(:isbn) }

    # File lib/shoulda/active_record/matchers/allow_value_matcher.rb, line 16
    def allow_value(value)
      AllowValueMatcher.new(value)
    end

belong_to(name) click to toggle source

Ensure that the belongs_to relationship exists.

    it { should belong_to(:parent) }

    # File lib/shoulda/active_record/matchers/association_matcher.rb, line 9
    def belong_to(name)
      AssociationMatcher.new(:belongs_to, name)
    end

ensure_inclusion_of(attr) click to toggle source

Ensure that the attribute’s value is in the range specified

Options:

- `in_range` - the range of allowed values for this attribute

- `with_low_message` - value the test expects to find in `errors.on(:attribute)`. Regexp or string. Defaults to the translation for :inclusion.

- `with_high_message` - value the test expects to find in `errors.on(:attribute)`. Regexp or string. Defaults to the translation for :inclusion.

Example:

    it { should ensure_inclusion_of(:age).in_range(0..100) }

    # File lib/shoulda/active_record/matchers/ensure_inclusion_of_matcher.rb, line 19
    def ensure_inclusion_of(attr)
      EnsureInclusionOfMatcher.new(attr)
    end

ensure_length_of(attr) click to toggle source

Ensures that the length of the attribute is validated.

Options:

- `is_at_least` - minimum length of this attribute

- `is_at_most` - maximum length of this attribute

- `is_equal_to` - exact requred length of this attribute

- `with_short_message` - value the test expects to find in `errors.on(:attribute)`. Regexp or string. Defaults to the translation for :too_short.

- `with_long_message` - value the test expects to find in `errors.on(:attribute)`. Regexp or string. Defaults to the translation for :too_long.

- `with_message` - value the test expects to find in `errors.on(:attribute)`. Regexp or string. Defaults to the translation for :wrong_length. Used in conjunction with `is_equal_to`.

Examples:

    it { should ensure_length_of(:password).
                  is_at_least(6).
                  is_at_most(20) }
    it { should ensure_length_of(:name).
                  is_at_least(3).
                  with_short_message(/not long enough/) }
    it { should ensure_length_of(:ssn).
                  is_equal_to(9).
                  with_message(/is invalid/) }

    # File lib/shoulda/active_record/matchers/ensure_length_of_matcher.rb, line 32
    def ensure_length_of(attr)
      EnsureLengthOfMatcher.new(attr)
    end

have_and_belong_to_many(name) click to toggle source

Ensures that the has_and_belongs_to_many relationship exists, and that the join table is in place.

    it { should have_and_belong_to_many(:posts) }

    # File lib/shoulda/active_record/matchers/association_matcher.rb, line 51
    def have_and_belong_to_many(name)
      AssociationMatcher.new(:has_and_belongs_to_many, name)
    end

have_db_column(column) click to toggle source

Ensures the database column exists.

Options:

- `of_type` - db column type (:integer, :string, etc.)

- `with_options` - same options available in migrations (:default, :null, :limit, :precision, :scale)

Examples:

    it { should_not have_db_column(:admin).of_type(:boolean) }
    it { should have_db_column(:salary).
                  of_type(:decimal).
                  with_options(:precision => 10, :scale => 2) }

    # File lib/shoulda/active_record/matchers/have_db_column_matcher.rb, line 18
    def have_db_column(column)
      HaveDbColumnMatcher.new(:have_db_column, column)
    end

have_db_index(columns) click to toggle source

Ensures that there are DB indices on the given columns or tuples of columns.

Options:

- `unique` - whether or not the index has a unique constraint. Use `true` to explicitly test for a unique constraint. Use `false` to explicitly test for a non-unique constraint. Use `nil` if you don't care whether the index is unique or not. Default = `nil`

Examples:

    it { should have_db_index(:age) }
    it { should have_db_index([:commentable_type, :commentable_id]) }
    it { should have_db_index(:ssn).unique(true) }

    # File lib/shoulda/active_record/matchers/have_db_index_matcher.rb, line 21
    def have_db_index(columns)
      HaveDbIndexMatcher.new(:have_index, columns)
    end

have_many(name) click to toggle source

Ensures that the has_many relationship exists. Will also test that the associated table has the required columns. Works with polymorphic associations.

Options:

- `through` - association name for `has_many :through`

- `dependent` - tests that the association makes use of the dependent option.

Example:

    it { should_have_many(:friends) }
    it { should_have_many(:enemies).through(:friends) }
    it { should_have_many(:enemies).dependent(:destroy) }

    # File lib/shoulda/active_record/matchers/association_matcher.rb, line 27
    def have_many(name)
      AssociationMatcher.new(:has_many, name)
    end

have_one(name) click to toggle source

Ensure that the has_one relationship exists. Will also test that the associated table has the required columns. Works with polymorphic associations.

Options:

- `:dependent` - tests that the association makes use of the dependent option.

Example:

    it { should have_one(:god) } # unless hindu

    # File lib/shoulda/active_record/matchers/association_matcher.rb, line 42
    def have_one(name)
      AssociationMatcher.new(:has_one, name)
    end

have_readonly_attribute(value) click to toggle source

Ensures that the attribute cannot be changed once the record has been created.

    it { should have_readonly_attributes(:password) }

    # File lib/shoulda/active_record/matchers/have_readonly_attribute_matcher.rb, line 10
    def have_readonly_attribute(value)
      HaveReadonlyAttributeMatcher.new(value)
    end

validate_acceptance_of(attr) click to toggle source

Ensures that the model cannot be saved the given attribute is not accepted.

Options:

- `with_message` - value the test expects to find in `errors.on(:attribute)`. Regexp or string. Defaults to the translation for `:accepted`.

Example:

    it { should validate_acceptance_of(:eula) }

    # File lib/shoulda/active_record/matchers/validate_acceptance_of_matcher.rb, line 16
    def validate_acceptance_of(attr)
      ValidateAcceptanceOfMatcher.new(attr)
    end

validate_format_of(attr) click to toggle source

Ensures that the model is not valid if the given attribute is not formatted correctly.

Options:

- `with_message` - value the test expects to find in `errors.on(:attribute)`. `Regexp` or `String`. Defaults to the translation for `:blank`.

- `with(string to test against)`

- `not_with(string to test against)`

Examples:

    it { should validate_format_of(:name).
                  with('12345').
                  with_message(/is not optional/) }
    it { should validate_format_of(:name).
                  not_with('12D45').
                  with_message(/is not optional/) }

    # File lib/shoulda/active_record/matchers/validate_format_of_matcher.rb, line 23
    def validate_format_of(attr)
      ValidateFormatOfMatcher.new(attr)
    end

validate_numericality_of(attr) click to toggle source

Ensure that the attribute is numeric

Options:

- `with_message` - value the test expects to find in `errors.on(:attribute)`. Regexp or string. Defaults to the translation for `:not_a_number`.

Example:

    it { should validate_numericality_of(:age) }

    # File lib/shoulda/active_record/matchers/validate_numericality_of_matcher.rb, line 15
    def validate_numericality_of(attr)
      ValidateNumericalityOfMatcher.new(attr)
    end

validate_presence_of(attr) click to toggle source

Ensures that the model is not valid if the given attribute is not present.

Options:

- `with_message` - value the test expects to find in `errors.on(:attribute)`. `Regexp` or `String`. Defaults to the translation for `:blank`.

Examples:

    it { should validate_presence_of(:name) }
    it { should validate_presence_of(:name).
                  with_message(/is not optional/) }

    # File lib/shoulda/active_record/matchers/validate_presence_of_matcher.rb, line 18
    def validate_presence_of(attr)
      ValidatePresenceOfMatcher.new(attr)
    end

validate_uniqueness_of(attr) click to toggle source

Ensures that the model is invalid if the given attribute is not unique.

Internally, this uses values from existing records to test validations, so this will always fail if you have not saved at least one record for the model being tested, like so:

    describe User do
      before(:each) { User.create!(:email => 'address@example.com') }
      it { should validate_uniqueness_of(:email) }
    end

Options:

- `with_message` - value the test expects to find in `errors.on(:attribute)`. `Regexp` or `String`. Defaults to the translation for `:taken`.

- `scoped_to` - field(s) to scope the uniqueness to.

- `case_insensitive` - ensures that the validation does not check case. Off by default. Ignored by non-text attributes.

Examples:

    it { should validate_uniqueness_of(:keyword) }
    it { should validate_uniqueness_of(:keyword).with_message(/dup/) }
    it { should validate_uniqueness_of(:email).scoped_to(:name) }
    it { should validate_uniqueness_of(:email).
                  scoped_to(:first_name, :last_name) }
    it { should validate_uniqueness_of(:keyword).case_insensitive }

    # File lib/shoulda/active_record/matchers/validate_uniqueness_of_matcher.rb, line 33
    def validate_uniqueness_of(attr)
      ValidateUniquenessOfMatcher.new(attr)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.