Add `validate_uniqueness_of_(:foo).allow_blank`

Complements [`validates_uniqueness_of(:foo, allow_blank:
true)`](http://api.rubyonrails.org/classes/ActiveRecord/Validations/ClassMethods.html#method-i-validates_uniqueness_of).

NEWS.md

@@ -11,6 +11,10 @@
   from `validate_uniqueness_of`, your best bet continues to be creating a record
   manually and calling `validate_uniqueness_of` on that instead.
 
+* Add support for `validate_uniqueness_of(:foo).allow_blank` to complement
+  [`validates_uniqueness_of :foo, allow_blank:
+true`](http://api.rubyonrails.org/classes/ActiveRecord/Validations/ClassMethods.html#method-i-validates_uniqueness_of).
+
 # 2.6.1
 
 ### Features
@@ -90,7 +94,7 @@
 * Change `validate_uniqueness_of(...)` so that it provides default values for
   non-nullable attributes.
 
-* Running `rake` now installs Appraisals before running the test suite. 
+* Running `rake` now installs Appraisals before running the test suite.
   (Additionally, we now manage Appraisals using the `appraisal` executable in
   Appraisal 1.0.0.)
 

lib/shoulda/matchers/active_model/validate_uniqueness_of_matcher.rb

@@ -167,6 +167,25 @@ module Shoulda
       #
       # @return [ValidateUniquenessOfMatcher]
       #
+      # ##### allow_blank
+      #
+      # Use `allow_blank` to assert that the attribute allows the empty string.
+      #
+      #     class Post < ActiveRecord::Base
+      #       validates_uniqueness_of :author_id, allow_blank: true
+      #     end
+      #
+      #     # RSpec
+      #     describe Post do
+      #       it { should validate_uniqueness_of(:author_id).allow_blank }
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostTest < ActiveSupport::TestCase
+      #       should validate_uniqueness_of(:author_id).allow_blank
+      #     end
+      #
+      # @return [ValidateUniquenessOfMatcher]
       def validate_uniqueness_of(attr)
         ValidateUniquenessOfMatcher.new(attr)
       end
@@ -200,6 +219,11 @@ module Shoulda
           self
         end
 
+        def allow_blank
+          @options[:allow_blank] = true
+          self
+        end
+
         def description
           result = "require "
           result << "case sensitive " unless @options[:case_insensitive]
@@ -212,9 +236,10 @@ module Shoulda
           @subject = subject.class.new
           @expected_message ||= :taken
           set_scoped_attributes &&
-            validate_everything_except_duplicate_nils? &&
+            validate_everything_except_duplicate_nils_or_blanks? &&
             validate_after_scope_change? &&
-            allows_nil?
+            allows_nil? &&
+            allows_blank?
         end
 
         private
@@ -228,6 +253,15 @@ module Shoulda
           end
         end
 
+        def allows_blank?
+          if @options[:allow_blank]
+            ensure_blank_record_in_database
+            allows_value_of('', @expected_message)
+          else
+            true
+          end
+        end
+
         def existing_record
           @existing_record ||= first_instance
         end
@@ -242,19 +276,23 @@ module Shoulda
           end
         end
 
+        def ensure_blank_record_in_database
+          unless existing_record_is_blank?
+            create_record_in_database(blank_value: true)
+          end
+        end
+
         def existing_record_is_nil?
           @existing_record.present? && existing_value.nil?
         end
 
-        def create_record_in_database(options = {})
-          if options[:nil_value]
-            value = nil
-          else
-            value = 'a'
-          end
+        def existing_record_is_blank?
+          @existing_record.present? && existing_value.strip == ''
+        end
 
+        def create_record_in_database(options = {})
           @subject.class.new.tap do |instance|
-            instance.__send__("#{@attribute}=", value)
+            instance.__send__("#{@attribute}=", value_for_new_record(options))
             if has_secure_password?
               instance.password = 'password'
               instance.password_confirmation = 'password'
@@ -263,6 +301,14 @@ module Shoulda
           end
         end
 
+        def value_for_new_record(options = {})
+          case
+          when options[:nil_value] then nil
+          when options[:blank_value] then ''
+          else 'a'
+          end
+        end
+
         def has_secure_password?
           @subject.class.ancestors.map(&:to_s).include?('ActiveModel::SecurePassword::InstanceMethodsOnActivation')
         end
@@ -284,15 +330,16 @@ module Shoulda
           end
         end
 
-        def validate_everything_except_duplicate_nils?
-          if @options[:allow_nil] && existing_value.nil?
-            create_record_without_nil
+        def validate_everything_except_duplicate_nils_or_blanks?
+          if (@options[:allow_nil] && existing_value.nil?) ||
+             (@options[:allow_blank] && existing_value.blank?)
+            create_record_with_value
           end
 
           disallows_value_of(existing_value, @expected_message)
         end
 
-        def create_record_without_nil
+        def create_record_with_value
           @existing_record = create_record_in_database
         end
 

spec/shoulda/matchers/active_model/validate_uniqueness_of_matcher_spec.rb

@@ -383,6 +383,51 @@ describe Shoulda::Matchers::ActiveModel::ValidateUniquenessOfMatcher do
     end
   end
 
+  context 'when the validation allows blank' do
+    context 'when there is an existing entry with a blank' do
+      it 'should allow_blank' do
+        model = define_model_with_allow_blank
+        model.create!(attr: '')
+        expect(model.new).to matcher.allow_blank
+      end
+    end
+
+    it 'should create a blank and verify that it is allowed' do
+      model = define_model_with_allow_blank
+      expect(model.new).to matcher.allow_blank
+      model.all.any? { |instance| instance.attr.blank? }
+    end
+
+    def define_model_with_allow_blank
+      define_model(:example, attr: :string) do
+        attr_accessible :attr
+        validates_uniqueness_of :attr, allow_blank: true
+      end
+    end
+  end
+
+  context 'when the validation does not allow a blank' do
+    context 'when there is an existing entry with a blank' do
+      it 'should not allow_blank' do
+        model = define_model_without_allow_blank
+        model.create!(attr: '')
+        expect(model.new).not_to matcher.allow_blank
+      end
+    end
+
+    it 'should not allow_blank' do
+      model = define_model_without_allow_blank
+      expect(model.new).not_to matcher.allow_blank
+    end
+
+    def define_model_without_allow_blank
+      define_model(:example, attr: :string) do
+        attr_accessible :attr
+        validates_uniqueness_of :attr
+      end
+    end
+  end
+
   def case_sensitive_validation_with_existing_value(attr_type)
     model = define_model(:example, attr: attr_type) do
       attr_accessible :attr