shoulda-matchers 2.6.1 → 2.6.2

data/lib/shoulda/matchers/active_model/validate_presence_of_matcher.rb

@@ -1,25 +1,95 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-
-      # Ensures that the model is not valid if the given attribute is not
-      # present.
+    module ActiveModel
+      # The `validate_presence_of` matcher tests usage of the
+      # `validates_presence_of` validation.
+      #
+      #     class Robot
+      #       include ActiveModel::Model
+      #       attr_accessor :arms
+      #
+      #       validates_presence_of :arms
+      #     end
+      #
+      #     # RSpec
+      #     describe Robot do
+      #       it { should validate_presence_of(:arms) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class RobotTest < ActiveSupport::TestCase
+      #       should validate_presence_of(:arms)
+      #     end
+      #
+      # #### Caveats
+      #
+      # Under Rails 4 and greater, if your model `has_secure_password` and you
+      # are validating presence of the password using a record whose password
+      # has already been set prior to calling the matcher, you will be
+      # instructed to use a record whose password is empty instead.
+      #
+      # For example, given this scenario:
+      #
+      #     class User < ActiveRecord::Base
+      #       has_secure_password validations: false
+      #
+      #       validates_presence_of :password
+      #     end
+      #
+      #     describe User do
+      #       subject { User.new(password: '123456') }
+      #
+      #       it { should validate_presence_of(:password) }
+      #     end
+      #
+      # the above test will raise an error like this:
+      #
+      #     The validation failed because your User model declares
+      #     `has_secure_password`, and `validate_presence_of` was called on a
+      #     user which has `password` already set to a value. Please use a user
+      #     with an empty `password` instead.
+      #
+      # This happens because `has_secure_password` itself overrides your model
+      # so that it is impossible to set `password` to nil. This means that it is
+      # impossible to test that setting `password` to nil places your model in
+      # an invalid state (which in turn means that the validation itself is
+      # unnecessary).
+      #
+      # #### Qualifiers
+      #
+      # ##### with_message
+      #
+      # Use `with_message` if you are using a custom validation message.
+      #
+      #     class Robot
+      #       include ActiveModel::Model
+      #       attr_accessor :legs
+      #
+      #       validates_presence_of :legs, message: 'Robot has no legs'
+      #     end
+      #
+      #     # RSpec
+      #     describe Robot do
+      #       it do
+      #         should validate_presence_of(:legs).
+      #           with_message('Robot has no legs')
+      #       end
+      #     end
       #
-      # Options:
-      # * <tt>with_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. <tt>Regexp</tt> or <tt>String</tt>.
-      #   Defaults to the translation for <tt>:blank</tt>.
+      #     # Test::Unit
+      #     class RobotTest < ActiveSupport::TestCase
+      #       should validate_presence_of(:legs).
+      #         with_message('Robot has no legs')
+      #     end
       #
-      # Examples:
-      #   it { should validate_presence_of(:name) }
-      #   it { should validate_presence_of(:name).
-      #                 with_message(/is not optional/) }
+      # @return [ValidatePresenceOfMatcher]
       #
       def validate_presence_of(attr)
         ValidatePresenceOfMatcher.new(attr)
       end
 
-      class ValidatePresenceOfMatcher < ValidationMatcher # :nodoc:
+      # @private
+      class ValidatePresenceOfMatcher < ValidationMatcher
         def with_message(message)
           @expected_message = message if message
           self

data/lib/shoulda/matchers/active_model/validate_uniqueness_of_matcher.rb

@@ -1,38 +1,178 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-      # Ensures that the model is invalid if the given attribute is not unique.
-      # It uses the first existing record or creates a new one if no record
-      # exists in the database. It simply uses `validate: false` to get
-      # around validations, so it will probably fail if there are `NOT NULL`
-      # constraints. In that case, you must create a record before calling
-      # `validate_uniqueness_of`.
-      #
-      # Example:
-      #   it { should validate_uniqueness_of(:email) }
-      #
-      # Options:
-      #
-      # * <tt>with_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. <tt>Regexp</tt> or <tt>String</tt>.
-      #   Defaults to the translation for <tt>:taken</tt>.
-      # * <tt>scoped_to</tt> - field(s) to scope the uniqueness to.
-      # * <tt>case_insensitive</tt> - 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 }
+    module ActiveModel
+      # The `validate_uniqueness_of` matcher tests usage of the
+      # `validates_uniqueness_of` validation. It first checks for an existing
+      # instance of your model in the database, creating one if necessary. It
+      # then takes a new record and asserts that it fails validation if the
+      # attribute or attributes you've specified in the validation are set to
+      # values which are the same as those of the pre-existing record (thereby
+      # failing the uniqueness check).
+      #
+      #     class Post < ActiveRecord::Base
+      #       validates_uniqueness_of :permalink
+      #     end
+      #
+      #     # RSpec
+      #     describe Post do
+      #       it { should validate_uniqueness_of(:permalink) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostTest < ActiveSupport::TestCase
+      #       should validate_uniqueness_of(:permalink)
+      #     end
+      #
+      # #### Caveat
+      #
+      # This matcher works a bit differently than other matchers. As noted
+      # before, it will create an instance of your model if one doesn't already
+      # exist. Sometimes this step fails, especially if you have database-level
+      # restrictions on any attributes other than the one which is unique. In
+      # this case, the solution is to **create a record manually** before you
+      # call `validate_uniqueness_of`.
+      #
+      # For example, say you have the following migration and model:
+      #
+      #     class CreatePosts < ActiveRecord::Migration
+      #       def change
+      #         create_table :posts do |t|
+      #           t.string :title
+      #           t.text :content, null: false
+      #         end
+      #       end
+      #     end
+      #
+      #     class Post < ActiveRecord::Base
+      #       validates :title, uniqueness: true
+      #     end
+      #
+      # You may be tempted to test the model like this:
+      #
+      #     describe Post do
+      #       it { should validate_uniqueness_of(:title) }
+      #     end
+      #
+      # However, running this test will fail with something like:
+      #
+      #     Failures:
+      #
+      #       1) Post should require case sensitive unique value for title
+      #          Failure/Error: it { should validate_uniqueness_of(:title) }
+      #          ActiveRecord::StatementInvalid:
+      #            SQLite3::ConstraintException: posts.content may not be NULL: INSERT INTO "posts" ("title") VALUES (?)
+      #
+      # To fix this, you'll need to write this instead:
+      #
+      #     describe Post do
+      #       it do
+      #         Post.create!(content: 'Here is the content')
+      #         should validate_uniqueness_of(:title)
+      #       end
+      #     end
+      #
+      # Or, if you're using
+      # [FactoryGirl](http://github.com/thoughtbot/factory_girl) and you have a
+      # `post` factory defined which automatically sets `content`, you can say:
+      #
+      #     describe Post do
+      #       it do
+      #         FactoryGirl.create(:post)
+      #         should validate_uniqueness_of(:title)
+      #       end
+      #     end
+      #
+      # #### Qualifiers
+      #
+      # ##### with_message
+      #
+      # Use `with_message` if you are using a custom validation message.
+      #
+      #     class Post < ActiveRecord::Base
+      #       validates_uniqueness_of :title, message: 'Please choose another title'
+      #     end
+      #
+      #     # RSpec
+      #     describe Post do
+      #       it do
+      #         should validate_uniqueness_of(:title).
+      #           with_message('Please choose another title')
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostTest < ActiveSupport::TestCase
+      #       should validate_uniqueness_of(:title).
+      #         with_message('Please choose another title')
+      #     end
+      #
+      # ##### scoped_to
+      #
+      # Use `scoped_to` to test usage of the `:scope` option. This asserts that
+      # a new record fails validation if not only the primary attribute is not
+      # unique, but the scoped attributes are not unique either.
+      #
+      #     class Post < ActiveRecord::Base
+      #       validates_uniqueness_of :slug, scope: :user_id
+      #     end
+      #
+      #     # RSpec
+      #     describe Post do
+      #       it { should validate_uniqueness_of(:slug).scoped_to(:journal_id) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostTest < ActiveSupport::TestCase
+      #       should validate_uniqueness_of(:slug).scoped_to(:journal_id)
+      #     end
+      #
+      # ##### case_insensitive
+      #
+      # Use `case_insensitive` to test usage of the `:case_sensitive` option
+      # with a false value. This asserts that the uniquable attributes fail
+      # validation even if their values are a different case than corresponding
+      # attributes in the pre-existing record.
+      #
+      #     class Post < ActiveRecord::Base
+      #       validates_uniqueness_of :key, case_sensitive: false
+      #     end
+      #
+      #     # RSpec
+      #     describe Post do
+      #       it { should validate_uniqueness_of(:key).case_insensitive }
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostTest < ActiveSupport::TestCase
+      #       should validate_uniqueness_of(:key).case_insensitive
+      #     end
+      #
+      # ##### allow_nil
+      #
+      # Use `allow_nil` to assert that the attribute allows nil.
+      #
+      #     class Post < ActiveRecord::Base
+      #       validates_uniqueness_of :author_id, allow_nil: true
+      #     end
+      #
+      #     # RSpec
+      #     describe Post do
+      #       it { should validate_uniqueness_of(:author_id).allow_nil }
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostTest < ActiveSupport::TestCase
+      #       should validate_uniqueness_of(:author_id).allow_nil
+      #     end
+      #
+      # @return [ValidateUniquenessOfMatcher]
       #
       def validate_uniqueness_of(attr)
         ValidateUniquenessOfMatcher.new(attr)
       end
 
-      class ValidateUniquenessOfMatcher < ValidationMatcher # :nodoc:
+      # @private
+      class ValidateUniquenessOfMatcher < ValidationMatcher
         include Helpers
 
         def initialize(attribute)
@@ -115,11 +255,6 @@ module Shoulda # :nodoc:
 
           @subject.class.new.tap do |instance|
             instance.__send__("#{@attribute}=", value)
-            
-            other_non_nullable_columns.each do |non_nullable_column|
-              instance.__send__("#{non_nullable_column.name}=", correct_type_for_column(non_nullable_column))
-            end
-            
             if has_secure_password?
               instance.password = 'password'
               instance.password_confirmation = 'password'
@@ -203,7 +338,7 @@ module Shoulda # :nodoc:
         end
 
         def correct_type_for_column(column)
-          if column.type == :string || column.type == :binary
+          if column.type == :string
             '0'
           elsif column.type == :datetime
             DateTime.now
@@ -225,12 +360,6 @@ module Shoulda # :nodoc:
           end
           value
         end
-
-        def other_non_nullable_columns
-          @subject.class.columns.select do |column|
-            column.name != @attribute && !column.null && !column.primary
-          end
-        end
       end
     end
   end

data/lib/shoulda/matchers/active_model/validation_matcher.rb

@@ -1,7 +1,8 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-      class ValidationMatcher # :nodoc:
+    module ActiveModel
+      # @private
+      class ValidationMatcher
         attr_reader :failure_message
 
         alias failure_message_for_should failure_message
@@ -9,6 +10,8 @@ module Shoulda # :nodoc:
         def initialize(attribute)
           @attribute = attribute
           @strict = false
+          @failure_message = nil
+          @failure_message_when_negated = nil
         end
 
         def on(context)
@@ -60,31 +63,33 @@ module Shoulda # :nodoc:
         end
 
         def allow_value_matcher(value, message)
-          matcher = AllowValueMatcher.
-            new(value).
-            for(@attribute).
-            on(@context).
+          matcher = AllowValueMatcher.new(value).for(@attribute).
             with_message(message)
 
+          if defined?(@context)
+            matcher.on(@context)
+          end
+
           if strict?
             matcher.strict
-          else
-            matcher
           end
+
+          matcher
         end
 
         def disallow_value_matcher(value, message)
-          matcher = DisallowValueMatcher.
-            new(value).
-            for(@attribute).
-            on(@context).
+          matcher = DisallowValueMatcher.new(value).for(@attribute).
             with_message(message)
 
+          if defined?(@context)
+            matcher.on(@context)
+          end
+
           if strict?
             matcher.strict
-          else
-            matcher
           end
+
+          matcher
         end
 
         def strict?

data/lib/shoulda/matchers/active_model/validation_message_finder.rb

@@ -1,8 +1,7 @@
 module Shoulda
   module Matchers
     module ActiveModel
-
-      # Finds message information from a model's #errors method.
+      # @private
       class ValidationMessageFinder
         include Helpers
 

data/lib/shoulda/matchers/active_record.rb

@@ -1,4 +1,5 @@
 require 'shoulda/matchers/active_record/association_matcher'
+require 'shoulda/matchers/active_record/association_matchers'
 require 'shoulda/matchers/active_record/association_matchers/counter_cache_matcher'
 require 'shoulda/matchers/active_record/association_matchers/inverse_of_matcher'
 require 'shoulda/matchers/active_record/association_matchers/order_matcher'
@@ -16,18 +17,6 @@ require 'shoulda/matchers/active_record/accept_nested_attributes_for_matcher'
 
 module Shoulda
   module Matchers
-    # = Matchers for your active record models
-    #
-    # These matchers will test the associations for your
-    # ActiveRecord models.
-    #
-    #   describe User do
-    #     it { should have_one(:profile) }
-    #     it { should have_many(:dogs) }
-    #     it { should have_many(:messes).through(:dogs) }
-    #     it { should belong_to(:lover) }
-    #   end
-    #
     module ActiveRecord
     end
   end