shoulda-matchers 2.6.1 → 2.6.2

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

@@ -1,29 +1,225 @@
 require 'bigdecimal'
 
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-
-      # Ensure that the attribute's value is in the range specified
+    module ActiveModel
+      # The `ensure_inclusion_of` matcher tests usage of the
+      # `validates_inclusion_of` validation, asserting that an attribute can
+      # take a whitelist of values and cannot take values outside of this list.
+      #
+      # If your whitelist is an array of values, use `in_array`:
+      #
+      #     class Issue
+      #       include ActiveModel::Model
+      #       attr_accessor :state
+      #
+      #       validates_inclusion_of :state, in: %w(open resolved unresolved)
+      #     end
+      #
+      #     # RSpec
+      #     describe Issue do
+      #       it do
+      #         should ensure_inclusion_of(:state).
+      #           in_array(%w(open resolved unresolved))
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class IssueTest < ActiveSupport::TestCase
+      #       should ensure_inclusion_of(:state).
+      #         in_array(%w(open resolved unresolved))
+      #     end
+      #
+      # If your whitelist is a range of values, use `in_range`:
+      #
+      #     class Issue
+      #       include ActiveModel::Model
+      #       attr_accessor :priority
+      #
+      #       validates_inclusion_of :priority, in: 1..5
+      #     end
+      #
+      #     # RSpec
+      #     describe Issue do
+      #       it { should ensure_inclusion_of(:state).in_range(1..5) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class IssueTest < ActiveSupport::TestCase
+      #       should ensure_inclusion_of(:state).in_range(1..5)
+      #     end
+      #
+      # #### Optional qualifiers
+      #
+      # ##### with_message
+      #
+      # Use `with_message` if you are using a custom validation message.
+      #
+      #     class Issue
+      #       include ActiveModel::Model
+      #       attr_accessor :severity
+      #
+      #       validates_inclusion_of :severity,
+      #         in: %w(low medium high),
+      #         message: 'Severity must be low, medium, or high'
+      #     end
+      #
+      #     # RSpec
+      #     describe Issue do
+      #       it do
+      #         should ensure_inclusion_of(:severity).
+      #           in_array(%w(low medium high)).
+      #           with_message('Severity must be low, medium, or high')
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class IssueTest < ActiveSupport::TestCase
+      #       should ensure_inclusion_of(:severity).
+      #         in_array(%w(low medium high)).
+      #         with_message('Severity must be low, medium, or high')
+      #     end
+      #
+      # ##### with_low_message
+      #
+      # Use `with_low_message` if you have a custom validation message for when
+      # a given value is too low.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attr_accessor :age
+      #
+      #       validate :age_must_be_valid
+      #
+      #       private
+      #
+      #       def age_must_be_valid
+      #         if age < 65
+      #           self.errors.add :age, 'You do not receive any benefits'
+      #         end
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe Person do
+      #       it do
+      #         should ensure_inclusion_of(:age).
+      #           in_range(0..65).
+      #           with_low_message('You do not receive any benefits')
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should ensure_inclusion_of(:age).
+      #         in_range(0..65).
+      #         with_low_message('You do not receive any benefits')
+      #     end
+      #
+      # ##### with_high_message
+      #
+      # Use `with_high_message` if you have a custom validation message for
+      # when a given value is too high.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attr_accessor :age
+      #
+      #       validate :age_must_be_valid
+      #
+      #       private
+      #
+      #       def age_must_be_valid
+      #         if age > 21
+      #           self.errors.add :age, "You're too old for this stuff"
+      #         end
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe Person do
+      #       it do
+      #         should ensure_inclusion_of(:age).
+      #           in_range(0..21).
+      #           with_high_message("You're too old for this stuff")
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should ensure_inclusion_of(:age).
+      #         in_range(0..21).
+      #         with_high_message("You're too old for this stuff")
+      #     end
+      #
+      # ##### allow_nil
+      #
+      # Use `allow_nil` to assert that the attribute allows nil.
+      #
+      #     class Issue
+      #       include ActiveModel::Model
+      #       attr_accessor :state
+      #
+      #       validates_presence_of :state
+      #       validates_inclusion_of :state,
+      #         in: %w(open resolved unresolved),
+      #         allow_nil: true
+      #     end
+      #
+      #     # RSpec
+      #     describe Issue do
+      #       it do
+      #         should ensure_inclusion_of(:state).
+      #           in_array(%w(open resolved unresolved)).
+      #           allow_nil
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class IssueTest < ActiveSupport::TestCase
+      #       should ensure_inclusion_of(:state).
+      #         in_array(%w(open resolved unresolved)).
+      #         allow_nil
+      #     end
+      #
+      # ##### allow_blank
+      #
+      # Use `allow_blank` to assert that the attribute allows blank.
+      #
+      #     class Issue
+      #       include ActiveModel::Model
+      #       attr_accessor :state
+      #
+      #       validates_presence_of :state
+      #       validates_inclusion_of :state,
+      #         in: %w(open resolved unresolved),
+      #         allow_blank: true
+      #     end
+      #
+      #     # RSpec
+      #     describe Issue do
+      #       it do
+      #         should ensure_inclusion_of(:state).
+      #           in_array(%w(open resolved unresolved)).
+      #           allow_blank
+      #       end
+      #     end
       #
-      # Options:
-      # * <tt>in_array</tt> - the array of allowed values for this attribute
-      # * <tt>in_range</tt> - the range of allowed values for this attribute
-      # * <tt>with_low_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. Regexp or string. Defaults to the
-      #   translation for :inclusion.
-      # * <tt>with_high_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. Regexp or string. Defaults to the
-      #   translation for :inclusion.
+      #     # Test::Unit
+      #     class IssueTest < ActiveSupport::TestCase
+      #       should ensure_inclusion_of(:state).
+      #         in_array(%w(open resolved unresolved)).
+      #         allow_blank
+      #     end
       #
-      # Example:
-      #   it { should ensure_inclusion_of(:age).in_range(0..100) }
+      # @return [EnsureInclusionOfMatcher]
       #
       def ensure_inclusion_of(attr)
         EnsureInclusionOfMatcher.new(attr)
       end
 
-      class EnsureInclusionOfMatcher < ValidationMatcher # :nodoc:
+      # @private
+      class EnsureInclusionOfMatcher < ValidationMatcher
         ARBITRARY_OUTSIDE_STRING = 'shouldamatchersteststring'
         ARBITRARY_OUTSIDE_FIXNUM = 123456789
         ARBITRARY_OUTSIDE_DECIMAL = BigDecimal.new('0.123456789')
@@ -45,6 +241,12 @@ EOT
         def initialize(attribute)
           super(attribute)
           @options = {}
+          @array = nil
+          @range = nil
+          @minimum = nil
+          @maximum = nil
+          @low_message = nil
+          @high_message = nil
         end
 
         def in_array(array)

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

@@ -1,45 +1,211 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-
-      # Ensures that the length of the attribute is validated. Only works with
-      # string/text columns because it uses a string to check length.
-      #
-      # Options:
-      # * <tt>is_at_least</tt> - minimum length of this attribute
-      # * <tt>is_at_most</tt> - maximum length of this attribute
-      # * <tt>is_equal_to</tt> - exact requred length of this attribute
-      # * <tt>with_short_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. Regexp or string.  Defaults to the
-      #   translation for :too_short.
-      # * <tt>with_long_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. Regexp or string.  Defaults to the
-      #   translation for :too_long.
-      # * <tt>with_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. Regexp or string.  Defaults to the
-      #   translation for :wrong_length. Used in conjunction with
-      #   <tt>is_equal_to</tt>.
-      #
-      # 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/) }
+    module ActiveModel
+      # The `ensure_length_of` matcher tests usage of the `validates_length_of`
+      # matcher. Note that this matcher is intended to be used against string
+      # columns and not integer columns.
+      #
+      # #### Qualifiers
+      #
+      # ##### is_at_least
+      #
+      # Use `is_at_least` to test usage of the `:minimum` option. This asserts
+      # that the attribute can take a string which is equal to or longer than
+      # the given length and cannot take a string which is shorter.
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       attr_accessor :bio
+      #
+      #       validates_length_of :bio, minimum: 15
+      #     end
+      #
+      #     # RSpec
+      #
+      #     describe User do
+      #       it { should ensure_length_of(:bio).is_at_least(15) }
+      #     end
+      #
+      #     # Test::Unit
+      #
+      #     class UserTest < ActiveSupport::TestCase
+      #       should ensure_length_of(:bio).is_at_least(15)
+      #     end
+      #
+      # ##### is_at_most
+      #
+      # Use `is_at_most` to test usage of the `:maximum` option. This asserts
+      # that the attribute can take a string which is equal to or shorter than
+      # the given length and cannot take a string which is longer.
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       attr_accessor :status_update
+      #
+      #       validates_length_of :status_update, maximum: 140
+      #     end
+      #
+      #     # RSpec
+      #     describe User do
+      #       it { should ensure_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)
+      #     end
+      #
+      # ##### is_equal_to
+      #
+      # Use `is_at_equal` to test usage of the `:is` option. This asserts that
+      # the attribute can take a string which is exactly equal to the given
+      # length and cannot take a string which is shorter or longer.
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       attr_accessor :favorite_superhero
+      #
+      #       validates_length_of :favorite_superhero, is: 6
+      #     end
+      #
+      #     # RSpec
+      #     describe User do
+      #       it { should ensure_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)
+      #     end
+      #
+      # ##### is_at_least + is_at_most
+      #
+      # Use `is_at_least` and `is_at_most` together to test usage of the `:in`
+      # option.
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       attr_accessor :password
+      #
+      #       validates_length_of :password, in: 5..30
+      #     end
+      #
+      #     # RSpec
+      #     describe User do
+      #       it do
+      #         should ensure_length_of(:password).
+      #           is_at_least(5).is_at_most(30)
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UserTest < ActiveSupport::TestCase
+      #       should ensure_length_of(:password).
+      #         is_at_least(5).is_at_most(30)
+      #     end
+      #
+      # ##### with_message
+      #
+      # Use `with_message` if you are using a custom validation message.
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       attr_accessor :api_token
+      #
+      #       validates_length_of :api_token,
+      #         minimum: 10,
+      #         message: "Password isn't long enough"
+      #     end
+      #
+      #     # RSpec
+      #     describe User do
+      #       it do
+      #         should ensure_length_of(:password).
+      #           is_at_least(10).
+      #           with_message("Password isn't long enough")
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UserTest < ActiveSupport::TestCase
+      #       should ensure_length_of(:password).
+      #         is_at_least(10).
+      #         with_message("Password isn't long enough")
+      #     end
+      #
+      # ##### with_short_message
+      #
+      # Use `with_short_message` if you are using a custom "too short" message.
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       attr_accessor :secret_key
+      #
+      #       validates_length_of :secret_key,
+      #         in: 15..100,
+      #         too_short: 'Secret key must be more than 15 characters'
+      #     end
+      #
+      #     # RSpec
+      #     describe User do
+      #       it do
+      #         should ensure_length_of(:secret_key).
+      #           is_at_least(15).
+      #           with_short_message('Secret key must be more than 15 characters')
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UserTest < ActiveSupport::TestCase
+      #       should ensure_length_of(:secret_key).
+      #         is_at_least(15).
+      #         with_short_message('Secret key must be more than 15 characters')
+      #     end
+      #
+      # ##### with_long_message
+      #
+      # Use `with_long_message` if you are using a custom "too long" message.
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       attr_accessor :secret_key
+      #
+      #       validates_length_of :secret_key,
+      #         in: 15..100,
+      #         too_long: 'Secret key must be less than 100 characters'
+      #     end
+      #
+      #     # RSpec
+      #     describe User do
+      #       it do
+      #         should ensure_length_of(:secret_key).
+      #           is_at_most(100).
+      #           with_long_message('Secret key must be less than 100 characters')
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UserTest < ActiveSupport::TestCase
+      #       should ensure_length_of(:secret_key).
+      #         is_at_most(100).
+      #         with_long_message('Secret key must be less than 100 characters')
+      #     end
+      #
+      # @return [EnsureLengthOfMatcher]
+      #
       def ensure_length_of(attr)
         EnsureLengthOfMatcher.new(attr)
       end
 
-      class EnsureLengthOfMatcher < ValidationMatcher # :nodoc:
+      # @private
+      class EnsureLengthOfMatcher < ValidationMatcher
         include Helpers
 
         def initialize(attribute)
           super(attribute)
           @options = {}
+          @short_message = nil
+          @long_message = nil
         end
 
         def is_at_least(length)