shoulda-matchers 5.3.0 → 6.1.0

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

@@ -0,0 +1,532 @@
+module Shoulda
+  module Matchers
+    module ActiveModel
+      # The `validate_comparison_of` matcher tests usage of the
+      # `validates_comparison_of` validation.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attr_accessor :gpa
+      #
+      #       validates_comparison_of :gpa, greater_than: 10
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it { should validate_comparison_of(:gpa).greater_than(10) }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:gpa).greater_than(10)
+      #     end
+      #
+      # #### Qualifiers
+      #
+      # ##### on
+      #
+      # Use `on` if your validation applies only under a certain context.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attribute :number_of_dependents, :integer
+      #       attr_accessor :number_of_dependents
+      #
+      #       validates_comparison_of :number_of_dependents, on: :create, greater_than: 0
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it do
+      #         should validate_comparison_of(:number_of_dependents).
+      #           greater_than(0).
+      #           on(:create)
+      #       end
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:number_of_dependents).greater_than(0).on(:create)
+      #     end
+      #
+      # ##### is_less_than
+      #
+      # Use `is_less_than` to test usage of the the `:less_than` option. This
+      # asserts that the attribute can take a value which is less than the
+      # given value and cannot take a value which is greater than or equal to
+      # it. It can also accept methods or procs that returns a given value.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attribute :number_of_cars, :integer
+      #       attr_accessor :number_of_cars
+      #
+      #       validates_comparison_of :number_of_cars, less_than: :current_number_of_cars
+      #
+      #       def current_number_of_cars
+      #         10
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it do
+      #         should validate_comparison_of(:number_of_cars).
+      #           is_less_than(:current_number_of_cars)
+      #       end
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:number_of_cars).
+      #         is_less_than(:current_number_of_cars)
+      #     end
+      #
+      # ##### is_less_than_or_equal_to
+      #
+      # Use `is_less_than_or_equal_to` to test usage of the
+      # `:less_than_or_equal_to` option. This asserts that the attribute can
+      # take a value which is less than or equal to the given value and cannot
+      # take a value which is greater than it. It can also accept methods or
+      # procs that returns a given value.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attr_accessor :birth_date
+      #
+      #       validates_comparison_of :birth_date, less_than_or_equal_to: Date.new(1987, 12, 31)
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it do
+      #         should validate_comparison_of(:birth_date).
+      #           is_less_than_or_equal_to(Date.new(1987, 12, 31))
+      #       end
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:birth_date).
+      #         is_less_than_or_equal_to(Date.new(1987, 12, 31))
+      #     end
+      #
+      # ##### is_greater_than_or_equal_to
+      #
+      # Use `is_greater_than_or_equal_to` to test usage of the
+      # `:greater_than_or_equal_to` option. This asserts that the attribute can
+      # take a value which is greater than or equal to the given value and
+      # cannot take a value which is less than it.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attribute :birth_date, :date
+      #       attr_accessor :birth_date
+      #
+      #       validates_comparison_of :birth_date,
+      #                                greater_than_or_equal_to: -> { 18.years.ago.to_date }
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it do
+      #         should validate_comparison_of(:birth_date).
+      #           is_greater_than_or_equal_to(-> { 18.years.ago.to_date })
+      #       end
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:birth_date).
+      #         is_greater_than_or_equal_to(-> { 18.years.ago.to_date })
+      #     end
+      #
+      # ##### is_greater_than
+      #
+      # Use `is_greater_than` to test usage of the `:greater_than` option.
+      # This asserts that the attribute can take a value which is greater than
+      # the given value and cannot take a value less than or equal to it.
+      # It can also accept methods or procs that returns a given value.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attribute :legal_age, :integer
+      #       attr_accessor :legal_age
+      #
+      #       validates_comparison_of :legal_age, greater_than: 21
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it do
+      #         should validate_comparison_of(:legal_age).
+      #           is_greater_than(21)
+      #       end
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:legal_age).
+      #         is_greater_than(21)
+      #     end
+      #
+      # ##### is_equal_to
+      #
+      # Use `is_equal_to` to test usage of the `:equal_to` option. This asserts
+      # that the attribute can take a value which is equal to the given value
+      # and cannot take a value which is not equal. It can also accept methods or
+      # procs that returns a given value.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attribute :favorite_color, :string
+      #       attr_accessor :favorite_color
+      #
+      #       validates_comparison_of :favorite_color, equal_to: "blue"
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it { should validate_comparison_of(:favorite_color).is_equal_to("blue") }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:favorite_color).is_equal_to("blue")
+      #     end
+      #
+      #
+      # ##### is_other_than
+      #
+      # Use `is_other_than` to test usage of the `:other_than` option.
+      # This asserts that the attribute can take a number which is not equal to
+      # the given value.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attr_accessor :legal_age
+      #
+      #       validates_comparison_of :legal_age, other_than: 21
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it do
+      #         should validate_comparison_of(:legal_age).
+      #           is_other_than(21)
+      #       end
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:legal_age).
+      #         is_other_than(21)
+      #     end
+      #
+      # ##### with_message
+      #
+      # Use `with_message` if you are using a custom validation message.
+      #
+      #     class Person
+      #       include ActiveModel::Model
+      #       attr_accessor :number_of_dependents
+      #
+      #       validates_comparison_of :number_of_dependents, greater_than: 0
+      #         message: 'Number of dependents must be a number'
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Person, type: :model do
+      #       it do
+      #         should validate_comparison_of(:number_of_dependents).
+      #           is_greater_than(0).
+      #           with_message('Number of dependents must be a number')
+      #       end
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PersonTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:number_of_dependents).
+      #         is_greater_than(0).
+      #         with_message('Number of dependents must be a number')
+      #     end
+      #
+      # ##### allow_nil
+      #
+      # Use `allow_nil` to assert that the attribute allows nil.
+      #
+      #     class Post
+      #       include ActiveModel::Model
+      #       attr_accessor :age
+      #
+      #       validates_comparison_of :age, greater_than: 0, allow_nil: true
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Post, type: :model do
+      #       it { should validate_comparison_of(:age).is_greater_than(0).allow_nil }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PostTest < ActiveSupport::TestCase
+      #       should validate_comparison_of(:age).is_greater_than(0).allow_nil
+      #     end
+      #
+      # @return [ValidateComparisonOfMatcher]
+      #
+      def validate_comparison_of(attr)
+        ValidateComparisonOfMatcher.new(attr)
+      end
+
+      # @private
+      class ValidateComparisonOfMatcher < ValidationMatcher
+        NUMERIC_NAME = 'number'.freeze
+        DEFAULT_DIFF_TO_COMPARE = 1
+
+        attr_reader :diff_to_compare, :number_of_submatchers
+
+        def initialize(attribute)
+          super
+          @submatchers = []
+          @diff_to_compare = DEFAULT_DIFF_TO_COMPARE
+          @expects_to_allow_nil = false
+          @comparison_submatcher = false
+        end
+
+        def allow_nil
+          @expects_to_allow_nil = true
+          prepare_submatcher(allow_value_matcher(nil))
+          self
+        end
+
+        def expects_to_allow_nil?
+          @expects_to_allow_nil
+        end
+
+        def is_greater_than(value)
+          prepare_submatcher(comparison_matcher_for(value, :>).for(attribute))
+          self
+        end
+
+        def is_greater_than_or_equal_to(value)
+          prepare_submatcher(comparison_matcher_for(value, :>=).for(attribute))
+          self
+        end
+
+        def is_equal_to(value)
+          prepare_submatcher(comparison_matcher_for(value, :==).for(attribute))
+          self
+        end
+
+        def is_less_than(value)
+          prepare_submatcher(comparison_matcher_for(value, :<).for(attribute))
+          self
+        end
+
+        def is_less_than_or_equal_to(value)
+          prepare_submatcher(comparison_matcher_for(value, :<=).for(attribute))
+          self
+        end
+
+        def is_other_than(value)
+          prepare_submatcher(comparison_matcher_for(value, :!=).for(attribute))
+          self
+        end
+
+        def matches?(subject)
+          @subject = subject
+          @number_of_submatchers = @submatchers.size
+          unless @comparison_matcher
+            raise(ArgumentError, "matcher isn't qualified with any comparison matcher")
+          end
+
+          qualify_submatchers
+          first_submatcher_that_fails_to_match.nil?
+        end
+
+        def does_not_match?(subject)
+          @subject = subject
+          @number_of_submatchers = @submatchers.size
+
+          qualify_submatchers
+          first_submatcher_that_fails_to_not_match.nil?
+        end
+
+        def simple_description
+          String.new.tap do |description|
+            description << "validate that :#{attribute} looks like "
+            description << Shoulda::Matchers::Util.a_or_an(allowed_type_name)
+
+            if comparison_descriptions.present?
+              description << " #{comparison_descriptions}"
+            end
+          end
+        end
+
+        def failure_message
+          overall_failure_message.dup.tap do |message|
+            message << "\n"
+            message << failure_message_for_first_submatcher_that_fails_to_match
+          end
+        end
+
+        def failure_message_when_negated
+          overall_failure_message_when_negated.dup.tap do |message|
+            message << "\n"
+            message <<
+              failure_message_for_first_submatcher_that_fails_to_not_match
+          end
+        end
+
+        def given_numeric_column?
+          attribute_is_active_record_column? &&
+            [:integer, :float, :decimal].include?(column_type)
+        end
+
+        private
+
+        def attribute_is_active_record_column?
+          columns_hash.key?(attribute.to_s)
+        end
+
+        def column_type
+          columns_hash[attribute.to_s].type
+        end
+
+        def columns_hash
+          if subject.class.respond_to?(:columns_hash)
+            subject.class.columns_hash
+          else
+            {}
+          end
+        end
+
+        def prepare_submatcher(submatcher)
+          add_submatcher(submatcher)
+          submatcher
+        end
+
+        def comparison_matcher_for(value, operator)
+          @comparison_matcher = true
+          ComparisonMatcher.
+            new(self, value, operator).
+            for(attribute)
+        end
+
+        def add_submatcher(submatcher)
+          @submatchers << submatcher
+        end
+
+        def qualify_submatchers
+          @submatchers.each do |submatcher|
+            if @expects_strict
+              submatcher.strict
+            end
+
+            if @expected_message.present?
+              submatcher.with_message(@expected_message)
+            end
+
+            if @context
+              submatcher.on(@context)
+            end
+
+            submatcher.ignoring_interference_by_writer(
+              ignore_interference_by_writer,
+            )
+          end
+        end
+
+        def number_of_submatchers_for_failure_message
+          if has_been_qualified?
+            number_of_submatchers - 1
+          else
+            number_of_submatchers
+          end
+        end
+
+        def has_been_qualified?
+          @submatchers.any? { |submatcher| submatcher_qualified?(submatcher) }
+        end
+
+        def submatcher_qualified?(submatcher)
+          submatcher.instance_of?(ComparisonMatcher)
+        end
+
+        def first_submatcher_that_fails_to_match
+          @_first_submatcher_that_fails_to_match ||=
+            @submatchers.detect do |submatcher|
+              !submatcher.matches?(subject)
+            end
+        end
+
+        def first_submatcher_that_fails_to_not_match
+          @_first_submatcher_that_fails_to_not_match ||=
+            @submatchers.detect do |submatcher|
+              submatcher.matches?(subject)
+            end
+        end
+
+        def failure_message_for_first_submatcher_that_fails_to_match
+          build_submatcher_failure_message_for(
+            first_submatcher_that_fails_to_match,
+            :failure_message,
+          )
+        end
+
+        def failure_message_for_first_submatcher_that_fails_to_not_match
+          build_submatcher_failure_message_for(
+            first_submatcher_that_fails_to_not_match,
+            :failure_message_when_negated,
+          )
+        end
+
+        def build_submatcher_failure_message_for(
+          submatcher,
+          failure_message_method
+        )
+          failure_message = submatcher.public_send(failure_message_method)
+          submatcher_description = submatcher.simple_description.
+            sub(/\bvalidate that\b/, 'validates').
+            sub(/\bdisallow\b/, 'disallows').
+            sub(/\ballow\b/, 'allows')
+          submatcher_message =
+            if number_of_submatchers_for_failure_message > 1
+              "In checking that #{model.name} #{submatcher_description}, " +
+                failure_message[0].downcase +
+                failure_message[1..]
+            else
+              failure_message
+            end
+
+          Shoulda::Matchers.word_wrap(submatcher_message, indent: 2)
+        end
+
+        def comparison_descriptions
+          description_array = submatcher_comparison_descriptions
+          if description_array.empty?
+            ''
+          else
+            submatcher_comparison_descriptions.join(' and ')
+          end
+        end
+
+        def submatcher_comparison_descriptions
+          @submatchers.inject([]) do |arr, submatcher|
+            arr << if submatcher.respond_to? :comparison_description
+                     submatcher.comparison_description
+                   end
+          end
+        end
+
+        def allowed_type_name
+          'value'
+        end
+
+        def non_numeric_value
+          'abcd'
+        end
+      end
+    end
+  end
+end

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

@@ -3,10 +3,10 @@ module Shoulda
     module ActiveModel
       # The `validate_exclusion_of` matcher tests usage of the
       # `validates_exclusion_of` validation, asserting that an attribute cannot
-      # take a blacklist of values, and inversely, can take values outside of
+      # take a blocklist of values, and inversely, can take values outside of
       # this list.
       #
-      # If your blacklist is an array of values, use `in_array`:
+      # If your blocklist an array of values, use `in_array`:
       #
       #     class Game
       #       include ActiveModel::Model
@@ -29,7 +29,7 @@ module Shoulda
       #         in_array(['Mac', 'Linux'])
       #     end
       #
-      # If your blacklist is a range of values, use `in_range`:
+      # If your blocklist is a range of values, use `in_range`:
       #
       #     class Game
       #       include ActiveModel::Model

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

@@ -3,14 +3,15 @@ require 'date'
 
 module Shoulda
   module Matchers
+    # @private
     class ExampleClass; end
 
     module ActiveModel
       # The `validate_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.
+      # take a allowlist of values and cannot take values outside of this list.
       #
-      # If your whitelist is an array of values, use `in_array`:
+      # If your allowlist is an array of values, use `in_array`:
       #
       #     class Issue
       #       include ActiveModel::Model
@@ -34,7 +35,7 @@ module Shoulda
       #         in_array(['open', 'resolved', 'unresolved'])
       #     end
       #
-      # If your whitelist is a range of values, use `in_range`:
+      # If your allowlist is a range of values, use `in_range`:
       #
       #     class Issue
       #       include ActiveModel::Model

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

@@ -3,7 +3,7 @@ module Shoulda
     module ActiveModel
       # The `validate_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.
+      # used against string columns and associations and not integer columns.
       #
       # #### Qualifiers
       #
@@ -36,7 +36,8 @@ module Shoulda
       #
       # 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.
+      # the given length and cannot take a string which is shorter. This qualifier
+      # also works for associations.
       #
       #     class User
       #       include ActiveModel::Model
@@ -61,7 +62,8 @@ module Shoulda
       #
       # 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.
+      # the given length and cannot take a string which is longer. This qualifier
+      # also works for associations.
       #
       #     class User
       #       include ActiveModel::Model
@@ -84,7 +86,8 @@ module Shoulda
       #
       # Use `is_equal_to` 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.
+      # length and cannot take a string which is shorter or longer. This qualifier
+      # also works for associations.
       #
       #     class User
       #       include ActiveModel::Model
@@ -106,7 +109,7 @@ module Shoulda
       # ##### is_at_least + is_at_most
       #
       # Use `is_at_least` and `is_at_most` together to test usage of the `:in`
-      # option.
+      # option. This qualifies also works for associations.
       #
       #     class User
       #       include ActiveModel::Model
@@ -260,6 +263,29 @@ module Shoulda
       #       should validate_length_of(:bio).is_at_least(15).allow_blank
       #     end
       #
+      # ##### as_array
+      #
+      # Use `as_array` if you have an ActiveModel model and the attribute being validated
+      # is designed to store an array. (This is not necessary if you have an ActiveRecord
+      # model with an array column, as the matcher will detect this automatically.)
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       attribute :arr, array: true
+      #
+      #       validates_length_of :arr, minimum: 15
+      #     end
+      #
+      #     # RSpec
+      #     describe User do
+      #       it { should validate_length_of(:arr).as_array.is_at_least(15) }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class UserTest < ActiveSupport::TestCase
+      #       should validate_length_of(:arr).as_array.is_at_least(15)
+      #     end
+      #
       def validate_length_of(attr)
         ValidateLengthOfMatcher.new(attr)
       end
@@ -275,6 +301,11 @@ module Shoulda
           @long_message = nil
         end
 
+        def as_array
+          @options[:array] = true
+          self
+        end
+
         def is_at_least(length)
           @options[:minimum] = length
           @short_message ||= :too_short
@@ -451,15 +482,39 @@ module Shoulda
         end
 
         def allows_length_of?(length, message)
-          allows_value_of(string_of_length(length), message)
+          allows_value_of(value_of_length(length), message)
         end
 
         def disallows_length_of?(length, message)
-          disallows_value_of(string_of_length(length), message)
+          disallows_value_of(value_of_length(length), message)
+        end
+
+        def value_of_length(length)
+          if array_column?
+            ['x'] * length
+          elsif collection_association?
+            Array.new(length) { association_reflection.klass.new }
+          else
+            'x' * length
+          end
+        end
+
+        def array_column?
+          @options[:array] || super
+        end
+
+        def collection_association?
+          association? && [:has_many, :has_and_belongs_to_many].include?(
+            association_reflection.macro,
+          )
+        end
+
+        def association?
+          association_reflection.present?
         end
 
-        def string_of_length(length)
-          'x' * length
+        def association_reflection
+          model.try(:reflect_on_association, @attribute)
         end
 
         def translated_short_message