Deprecate ensure_length_of for validate_length_of

NEWS.md

@@ -1,5 +1,10 @@
 # HEAD
 
+### Deprecations
+
+* `ensure_length_of` has been renamed to `validate_length_of`.
+  `ensure_length_of` is deprecated and will be removed in 3.0.0.
+
 ### Bug fixes
 
 * Fix `delegate_method` so that it works again with shoulda-context. ([#591])

lib/shoulda/matchers/active_model.rb

@@ -5,7 +5,7 @@ require 'shoulda/matchers/active_model/validation_message_finder'
 require 'shoulda/matchers/active_model/exception_message_finder'
 require 'shoulda/matchers/active_model/allow_value_matcher'
 require 'shoulda/matchers/active_model/disallow_value_matcher'
-require 'shoulda/matchers/active_model/ensure_length_of_matcher'
+require 'shoulda/matchers/active_model/validate_length_of_matcher'
 require 'shoulda/matchers/active_model/validate_inclusion_of_matcher'
 require 'shoulda/matchers/active_model/validate_exclusion_of_matcher'
 require 'shoulda/matchers/active_model/validate_absence_of_matcher'

lib/shoulda/matchers/active_model/validate_length_of_matcher.rb

@@ -1,9 +1,9 @@
 module Shoulda
   module Matchers
     module ActiveModel
-      # The `ensure_length_of` matcher tests usage of the `validates_length_of`
+      # The `validate_length_of` matcher tests usage of the
-      # matcher. Note that this matcher is intended to be used against string
+      # `validates_length_of` matcher. Note that this matcher is intended to be
-      # columns and not integer columns.
+      # used against string columns and not integer columns.
       #
       # #### Qualifiers
       #
@@ -23,13 +23,13 @@ module Shoulda
       #     # RSpec
       #
       #     describe User do
-      #       it { should ensure_length_of(:bio).is_at_least(15) }
+      #       it { should validate_length_of(:bio).is_at_least(15) }
       #     end
       #
       #     # Test::Unit
       #
       #     class UserTest < ActiveSupport::TestCase
-      #       should ensure_length_of(:bio).is_at_least(15)
+      #       should validate_length_of(:bio).is_at_least(15)
       #     end
       #
       # ##### is_at_most
@@ -47,12 +47,12 @@ module Shoulda
       #
       #     # RSpec
       #     describe User do
-      #       it { should ensure_length_of(:status_update).is_at_most(140) }
+      #       it { should validate_length_of(:status_update).is_at_most(140) }
       #     end
       #
       #     # Test::Unit
       #     class UserTest < ActiveSupport::TestCase
-      #       should ensure_length_of(:status_update).is_at_most(140)
+      #       should validate_length_of(:status_update).is_at_most(140)
       #     end
       #
       # ##### is_equal_to
@@ -70,12 +70,12 @@ module Shoulda
       #
       #     # RSpec
       #     describe User do
-      #       it { should ensure_length_of(:favorite_superhero).is_equal_to(6) }
+      #       it { should validate_length_of(:favorite_superhero).is_equal_to(6) }
       #     end
       #
       #     # Test::Unit
       #     class UserTest < ActiveSupport::TestCase
-      #       should ensure_length_of(:favorite_superhero).is_equal_to(6)
+      #       should validate_length_of(:favorite_superhero).is_equal_to(6)
       #     end
       #
       # ##### is_at_least + is_at_most
@@ -93,14 +93,14 @@ module Shoulda
       #     # RSpec
       #     describe User do
       #       it do
-      #         should ensure_length_of(:password).
+      #         should validate_length_of(:password).
       #           is_at_least(5).is_at_most(30)
       #       end
       #     end
       #
       #     # Test::Unit
       #     class UserTest < ActiveSupport::TestCase
-      #       should ensure_length_of(:password).
+      #       should validate_length_of(:password).
       #         is_at_least(5).is_at_most(30)
       #     end
       #
@@ -120,7 +120,7 @@ module Shoulda
       #     # RSpec
       #     describe User do
       #       it do
-      #         should ensure_length_of(:password).
+      #         should validate_length_of(:password).
       #           is_at_least(10).
       #           with_message("Password isn't long enough")
       #       end
@@ -128,7 +128,7 @@ module Shoulda
       #
       #     # Test::Unit
       #     class UserTest < ActiveSupport::TestCase
-      #       should ensure_length_of(:password).
+      #       should validate_length_of(:password).
       #         is_at_least(10).
       #         with_message("Password isn't long enough")
       #     end
@@ -149,7 +149,7 @@ module Shoulda
       #     # RSpec
       #     describe User do
       #       it do
-      #         should ensure_length_of(:secret_key).
+      #         should validate_length_of(:secret_key).
       #           is_at_least(15).
       #           with_short_message('Secret key must be more than 15 characters')
       #       end
@@ -157,7 +157,7 @@ module Shoulda
       #
       #     # Test::Unit
       #     class UserTest < ActiveSupport::TestCase
-      #       should ensure_length_of(:secret_key).
+      #       should validate_length_of(:secret_key).
       #         is_at_least(15).
       #         with_short_message('Secret key must be more than 15 characters')
       #     end
@@ -178,7 +178,7 @@ module Shoulda
       #     # RSpec
       #     describe User do
       #       it do
-      #         should ensure_length_of(:secret_key).
+      #         should validate_length_of(:secret_key).
       #           is_at_most(100).
       #           with_long_message('Secret key must be less than 100 characters')
       #       end
@@ -186,19 +186,29 @@ module Shoulda
       #
       #     # Test::Unit
       #     class UserTest < ActiveSupport::TestCase
-      #       should ensure_length_of(:secret_key).
+      #       should validate_length_of(:secret_key).
       #         is_at_most(100).
       #         with_long_message('Secret key must be less than 100 characters')
       #     end
       #
-      # @return [EnsureLengthOfMatcher]
+      # @return [ValidateLengthOfMatcher]
       #
+      def validate_length_of(attr)
+        ValidateLengthOfMatcher.new(attr)
+      end
+
+      # @deprecated Use {#validate_length_of} instead.
+      # @return [ValidateLengthOfMatcher]
       def ensure_length_of(attr)
-        EnsureLengthOfMatcher.new(attr)
+        Shoulda::Matchers.warn_about_deprecated_method(
+          :ensure_length_of,
+          :validate_length_of
+        )
+        validate_length_of(attr)
       end
 
       # @private
-      class EnsureLengthOfMatcher < ValidationMatcher
+      class ValidateLengthOfMatcher < ValidationMatcher
         include Helpers
 
         def initialize(attribute)

spec/shoulda/matchers/active_model/validate_length_of_matcher_spec.rb

@@ -1,75 +1,92 @@
 require 'unit_spec_helper'
 
-describe Shoulda::Matchers::ActiveModel::EnsureLengthOfMatcher do
+describe Shoulda::Matchers::ActiveModel do
+  describe '#ensure_length_of' do
+    it 'is aliased to #validate_length_of' do
+      matchers.expects(:validate_length_of).with(:attr)
+
+      silence_warnings do
+        matchers.ensure_length_of(:attr)
+      end
+    end
+  end
+
+  def matchers
+    @_matchers ||= Object.new.extend(described_class)
+  end
+end
+
+describe Shoulda::Matchers::ActiveModel::ValidateLengthOfMatcher do
   context 'an attribute with a non-zero minimum length validation' do
     it 'accepts ensuring the correct minimum length' do
       expect(validating_length(minimum: 4)).
-        to ensure_length_of(:attr).is_at_least(4)
+        to validate_length_of(:attr).is_at_least(4)
     end
 
     it 'rejects ensuring a lower minimum length with any message' do
       expect(validating_length(minimum: 4)).
-        not_to ensure_length_of(:attr).is_at_least(3).with_short_message(/.*/)
+        not_to validate_length_of(:attr).is_at_least(3).with_short_message(/.*/)
     end
 
     it 'rejects ensuring a higher minimum length with any message' do
       expect(validating_length(minimum: 4)).
-        not_to ensure_length_of(:attr).is_at_least(5).with_short_message(/.*/)
+        not_to validate_length_of(:attr).is_at_least(5).with_short_message(/.*/)
     end
 
     it 'does not override the default message with a blank' do
       expect(validating_length(minimum: 4)).
-        to ensure_length_of(:attr).is_at_least(4).with_short_message(nil)
+        to validate_length_of(:attr).is_at_least(4).with_short_message(nil)
     end
   end
 
   context 'an attribute with a minimum length validation of 0' do
     it 'accepts ensuring the correct minimum length' do
       expect(validating_length(minimum: 0)).
-        to ensure_length_of(:attr).is_at_least(0)
+        to validate_length_of(:attr).is_at_least(0)
     end
   end
 
   context 'an attribute with a maximum length' do
     it 'accepts ensuring the correct maximum length' do
       expect(validating_length(maximum: 4)).
-        to ensure_length_of(:attr).is_at_most(4)
+        to validate_length_of(:attr).is_at_most(4)
     end
 
     it 'rejects ensuring a lower maximum length with any message' do
       expect(validating_length(maximum: 4)).
-        not_to ensure_length_of(:attr).is_at_most(3).with_long_message(/.*/)
+        not_to validate_length_of(:attr).is_at_most(3).with_long_message(/.*/)
     end
 
     it 'rejects ensuring a higher maximum length with any message' do
       expect(validating_length(maximum: 4)).
-        not_to ensure_length_of(:attr).is_at_most(5).with_long_message(/.*/)
+        not_to validate_length_of(:attr).is_at_most(5).with_long_message(/.*/)
     end
 
     it 'does not override the default message with a blank' do
       expect(validating_length(maximum: 4)).
-        to ensure_length_of(:attr).is_at_most(4).with_long_message(nil)
+        to validate_length_of(:attr).is_at_most(4).with_long_message(nil)
     end
   end
 
   context 'an attribute with a required exact length' do
     it 'accepts ensuring the correct length' do
-      expect(validating_length(is: 4)).to ensure_length_of(:attr).is_equal_to(4)
+      expect(validating_length(is: 4)).
+        to validate_length_of(:attr).is_equal_to(4)
     end
 
     it 'rejects ensuring a lower maximum length with any message' do
       expect(validating_length(is: 4)).
-        not_to ensure_length_of(:attr).is_equal_to(3).with_message(/.*/)
+        not_to validate_length_of(:attr).is_equal_to(3).with_message(/.*/)
     end
 
     it 'rejects ensuring a higher maximum length with any message' do
       expect(validating_length(is: 4)).
-        not_to ensure_length_of(:attr).is_equal_to(5).with_message(/.*/)
+        not_to validate_length_of(:attr).is_equal_to(5).with_message(/.*/)
     end
 
     it 'does not override the default message with a blank' do
       expect(validating_length(is: 4)).
-        to ensure_length_of(:attr).is_equal_to(4).with_message(nil)
+        to validate_length_of(:attr).is_equal_to(4).with_message(nil)
     end
   end
 
@@ -80,35 +97,35 @@ describe Shoulda::Matchers::ActiveModel::EnsureLengthOfMatcher do
         validates_numericality_of :attr
       end.new
 
-      expect(model).to ensure_length_of(:attr).is_equal_to(4)
+      expect(model).to validate_length_of(:attr).is_equal_to(4)
     end
   end
 
   context 'an attribute with a custom minimum length validation' do
     it 'accepts ensuring the correct minimum length' do
       expect(validating_length(minimum: 4, too_short: 'foobar')).
-        to ensure_length_of(:attr).is_at_least(4).with_short_message(/foo/)
+        to validate_length_of(:attr).is_at_least(4).with_short_message(/foo/)
     end
   end
 
   context 'an attribute with a custom maximum length validation' do
     it 'accepts ensuring the correct minimum length' do
       expect(validating_length(maximum: 4, too_long: 'foobar')).
-        to ensure_length_of(:attr).is_at_most(4).with_long_message(/foo/)
+        to validate_length_of(:attr).is_at_most(4).with_long_message(/foo/)
     end
   end
 
   context 'an attribute with a custom equal validation' do
     it 'accepts ensuring the correct exact length' do
       expect(validating_length(is: 4, message: 'foobar')).
-        to ensure_length_of(:attr).is_equal_to(4).with_message(/foo/)
+        to validate_length_of(:attr).is_equal_to(4).with_message(/foo/)
     end
   end
 
   context 'an attribute without a length validation' do
     it 'rejects ensuring a minimum length' do
       expect(define_model(:example, attr: :string).new).
-        not_to ensure_length_of(:attr).is_at_least(1)
+        not_to validate_length_of(:attr).is_at_least(1)
     end
   end
 
@@ -124,7 +141,8 @@ describe Shoulda::Matchers::ActiveModel::EnsureLengthOfMatcher do
 
       it "does not raise an exception" do
         expect {
-          expect(validating_length(maximum: 4)).to ensure_length_of(:attr).is_at_most(4)
+          expect(validating_length(maximum: 4)).
+            to validate_length_of(:attr).is_at_most(4)
         }.to_not raise_exception
       end
     end
@@ -138,7 +156,7 @@ describe Shoulda::Matchers::ActiveModel::EnsureLengthOfMatcher do
 
       it "does not raise an exception" do
         expect {
-          expect(validating_length(minimum: 4)).to ensure_length_of(:attr).is_at_least(4)
+          expect(validating_length(minimum: 4)).to validate_length_of(:attr).is_at_least(4)
         }.to_not raise_exception
       end
     end
@@ -152,7 +170,8 @@ describe Shoulda::Matchers::ActiveModel::EnsureLengthOfMatcher do
 
       it "does not raise an exception" do
         expect {
-          expect(validating_length(is: 4)).to ensure_length_of(:attr).is_equal_to(4)
+          expect(validating_length(is: 4)).
+            to validate_length_of(:attr).is_equal_to(4)
         }.to_not raise_exception
       end
     end