shoulda-matchers 2.6.1 → 2.6.2

data/lib/shoulda/matchers/active_model.rb

@@ -22,33 +22,8 @@ require 'shoulda/matchers/active_model/allow_mass_assignment_of_matcher'
 require 'shoulda/matchers/active_model/errors'
 require 'shoulda/matchers/active_model/have_secure_password_matcher'
 
-
 module Shoulda
   module Matchers
-    # = Matchers for your active record models
-    #
-    # These matchers will test most of the validations of ActiveModel::Validations.
-    #
-    #   describe User do
-    #     it { should validate_presence_of(:name) }
-    #     it { should validate_presence_of(:phone_number) }
-    #     %w(abcd 1234).each do |value|
-    #       it { should_not allow_value(value).for(:phone_number) }
-    #     end
-    #     it { should allow_value('(123) 456-7890').for(:phone_number) }
-    #     it { should_not allow_mass_assignment_of(:password) }
-    #     it { should allow_value('Activated', 'Pending').for(:status).strict }
-    #     it { should_not allow_value('Amazing').for(:status).strict }
-    #   end
-    #
-    # These tests work with the following model:
-    #
-    # class User < ActiveRecord::Base
-    #   validates_presence_of :name
-    #   validates_presence_of :phone_number
-    #   validates_inclusion_of :status, in: %w(Activated Pending), strict: true
-    #   attr_accessible :name, :phone_number
-    # end
     module ActiveModel
     end
   end

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

@@ -1,21 +1,78 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-
-      # Ensures that the attribute can be set on mass update.
+    module ActiveModel
+      # The `allow_mass_assignment_of` matcher tests usage of Rails 3's
+      # `attr_accessible` and `attr_protected` macros, asserting that an
+      # attribute in your model is contained in either the whitelist or
+      # blacklist and thus can or cannot be set via mass assignment.
+      #
+      #     class Post
+      #       include ActiveModel::Model
+      #       include ActiveModel::MassAssignmentSecurity
+      #       attr_accessor :title
+      #
+      #       attr_accessible :title
+      #     end
+      #
+      #     class User
+      #       include ActiveModel::Model
+      #       include ActiveModel::MassAssignmentSecurity
+      #       attr_accessor :encrypted_password
+      #
+      #       attr_protected :encrypted_password
+      #     end
+      #
+      #     # RSpec
+      #     describe Post do
+      #       it { should allow_mass_assignment_of(:title) }
+      #     end
+      #
+      #     describe User do
+      #       it { should_not allow_mass_assignment_of(:encrypted_password) }
+      #     end
+      #
+      #     # Test::Unit
+      #     class PostTest < ActiveSupport::TestCase
+      #       should allow_mass_assignment_of(:title)
+      #     end
+      #
+      #     class UserTest < ActiveSupport::TestCase
+      #       should_not allow_mass_assignment_of(:encrypted_password)
+      #     end
+      #
+      # #### Optional qualifiers
+      #
+      # ##### as
+      #
+      # Use `as` if your mass-assignment rules apply only under a certain role
+      # *(Rails >= 3.1 only)*.
+      #
+      #     class Post
+      #       include ActiveModel::Model
+      #       include ActiveModel::MassAssignmentSecurity
+      #       attr_accessor :title
+      #
+      #       attr_accessible :title, as: :admin
+      #     end
       #
-      #   it { should_not allow_mass_assignment_of(:password) }
-      #   it { should allow_mass_assignment_of(:first_name) }
+      #     # RSpec
+      #     describe Post do
+      #       it { should allow_mass_assignment_of(:title).as(:admin) }
+      #     end
       #
-      # In Rails 3.1 you can check role as well:
+      #     # Test::Unit
+      #     class PostTest < ActiveSupport::TestCase
+      #       should allow_mass_assignment_of(:title).as(:admin)
+      #     end
       #
-      #   it { should allow_mass_assignment_of(:first_name).as(:admin) }
+      # @return [AllowMassAssignmentOfMatcher]
       #
       def allow_mass_assignment_of(value)
         AllowMassAssignmentOfMatcher.new(value)
       end
 
-      class AllowMassAssignmentOfMatcher # :nodoc:
+      # @private
+      class AllowMassAssignmentOfMatcher
         attr_reader :failure_message, :failure_message_when_negated
 
         alias failure_message_for_should failure_message

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

@@ -1,23 +1,164 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-
-      # Ensures that the attribute can be set to the given value or values. If
-      # multiple values are given the match succeeds only if all given values
-      # are allowed. Otherwise, the matcher fails at the first bad value in the
-      # argument list (the remaining arguments are not processed then).
+    module ActiveModel
+      # The `allow_value` matcher is used to test that an attribute of a model
+      # can or cannot be set to a particular value or values. It is most
+      # commonly used in conjunction with the `validates_format_of` validation.
+      #
+      # #### should
+      #
+      # In the positive form, `allow_value` asserts that an attribute can be
+      # set to one or more values, succeeding if none of the values cause the
+      # record to be invalid:
+      #
+      #     class UserProfile
+      #       include ActiveModel::Model
+      #       attr_accessor :website_url
+      #
+      #       validates_format_of :website_url, with: URI.regexp
+      #     end
+      #
+      #     # RSpec
+      #     describe UserProfile do
+      #       it do
+      #         should allow_value('http://foo.com', 'http://bar.com/baz').
+      #           for(:website_url)
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UserProfileTest < ActiveSupport::TestCase
+      #       should allow_value('http://foo.com', 'http://bar.com/baz').
+      #         for(:website_url)
+      #     end
+      #
+      # #### should_not
+      #
+      # In the negative form, `allow_value` asserts that an attribute cannot be
+      # set to one or more values, succeeding if the *first* value causes the
+      # record to be invalid.
+      #
+      # **This can be surprising** so in this case if you need to check that
+      # *all* of the values are invalid, use separate assertions:
+      #
+      #     class UserProfile
+      #       include ActiveModel::Model
+      #       attr_accessor :website_url
+      #
+      #       validates_format_of :website_url, with: URI.regexp
+      #     end
+      #
+      #     describe UserProfile do
+      #       # One assertion: 'buz' and 'bar' will not be tested
+      #       it { should_not allow_value('fiz', 'buz', 'bar').for(:website_url) }
+      #
+      #       # Three assertions, all tested separately
+      #       it { should_not allow_value('fiz').for(:website_url) }
+      #       it { should_not allow_value('buz').for(:website_url) }
+      #       it { should_not allow_value('bar').for(:website_url) }
+      #     end
+      #
+      # #### Qualifiers
+      #
+      # ##### on
+      #
+      # Use `on` if your validation applies only under a certain context.
+      #
+      #     class UserProfile
+      #       include ActiveModel::Model
+      #       attr_accessor :birthday_as_string
+      #
+      #       validates_format_of :birthday_as_string,
+      #         with: /^(\d+)-(\d+)-(\d+)$/,
+      #         on: :create
+      #     end
+      #
+      #     # RSpec
+      #     describe UserProfile do
+      #       it do
+      #         should allow_value('2013-01-01').
+      #           for(:birthday_as_string).
+      #           on(:create)
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UserProfileTest < ActiveSupport::TestCase
+      #       should allow_value('2013-01-01').
+      #         for(:birthday_as_string).
+      #         on(:create)
+      #     end
+      #
+      # ##### with_message
+      #
+      # Use `with_message` if you are using a custom validation message.
+      #
+      #     class UserProfile
+      #       include ActiveModel::Model
+      #       attr_accessor :state
+      #
+      #       validates_format_of :state,
+      #         with: /^(open|closed)$/,
+      #         message: 'State must be open or closed'
+      #     end
+      #
+      #     # RSpec
+      #     describe UserProfile do
+      #       it do
+      #         should allow_value('open', 'closed').
+      #           for(:state).
+      #           with_message('State must be open or closed')
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class UserProfileTest < ActiveSupport::TestCase
+      #       should allow_value('open', 'closed').
+      #         for(:state).
+      #         with_message('State must be open or closed')
+      #     end
+      #
+      # Use `with_message` with the `:against` option if the attribute the
+      # validation message is stored under is different from the attribute
+      # being validated.
+      #
+      #     class UserProfile
+      #       include ActiveModel::Model
+      #       attr_accessor :sports_team
+      #
+      #       validate :sports_team_must_be_valid
+      #
+      #       private
+      #
+      #       def sports_team_must_be_valid
+      #         if sports_team !~ /^(Broncos|Titans)$/i
+      #           self.errors.add :chosen_sports_team,
+      #             'Must be either a Broncos fan or a Titans fan'
+      #         end
+      #       end
+      #     end
+      #
+      #     # RSpec
+      #     describe UserProfile do
+      #       it do
+      #         should allow_value('Broncos', 'Titans').
+      #           for(:sports_team).
+      #           with_message('Must be either a Broncos or Titans fan',
+      #             against: :chosen_sports_team
+      #           )
+      #       end
+      #     end
       #
-      # Options:
-      # * <tt>with_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. Regexp or string. If omitted,
-      #   the test looks for any errors in <tt>errors.on(:attribute)</tt>.
-      # * <tt>strict</tt> - expects the model to raise an exception when the
-      #   validation fails rather than adding to the errors collection. Used for
-      #   testing `validates!` and the `strict: true` validation options.
+      #     # Test::Unit
+      #     class UserProfileTest < ActiveSupport::TestCase
+      #       should allow_value('Broncos', 'Titans').
+      #         for(:sports_team).
+      #         with_message('Must be either a Broncos or Titans fan',
+      #           against: :chosen_sports_team
+      #         )
+      #     end
       #
-      # Example:
-      #   it { should_not allow_value('bad').for(:isbn) }
-      #   it { should allow_value('isbn 1 2345 6789 0').for(:isbn) }
+      # @return [AllowValueMatcher]
       #
       def allow_value(*values)
         if values.empty?
@@ -27,7 +168,8 @@ module Shoulda # :nodoc:
         end
       end
 
-      class AllowValueMatcher # :nodoc:
+      # @private
+      class AllowValueMatcher
         include Helpers
 
         attr_accessor :attribute_with_message
@@ -95,7 +237,7 @@ module Shoulda # :nodoc:
           message_finder.allow_description(allowed_values)
         end
 
-        private
+        protected
 
         attr_accessor :values_to_match, :message_finder_factory,
           :instance, :attribute_to_set, :attribute_to_check_message_against,

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

@@ -1,13 +1,13 @@
 require 'forwardable'
 
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-      class DisallowValueMatcher # :nodoc:
+    module ActiveModel
+      # @private
+      class DisallowValueMatcher
         extend Forwardable
 
         def_delegators :allow_matcher, :_after_setting_value
-
         def initialize(value)
           @allow_matcher = AllowValueMatcher.new(value)
         end
@@ -46,7 +46,7 @@ module Shoulda # :nodoc:
           self
         end
 
-        private
+        protected
 
         attr_reader :allow_matcher
       end

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

@@ -1,24 +1,103 @@
-module Shoulda # :nodoc:
+module Shoulda
   module Matchers
-    module ActiveModel # :nodoc:
-
-      # Ensure that the attribute's value is not in the range specified
+    module ActiveModel
+      # The `ensure_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
+      # this list.
+      #
+      # If your blacklist is an array of values, use `in_array`:
+      #
+      #     class Game
+      #       include ActiveModel::Model
+      #       attr_accessor :supported_os
+      #
+      #       validates_exclusion_of :supported_os, in: ['Mac', 'Linux']
+      #     end
+      #
+      #     # RSpec
+      #     describe Game do
+      #       it do
+      #         should ensure_exclusion_of(:supported_os).
+      #           in_array(['Mac', 'Linux'])
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class GameTest < ActiveSupport::TestCase
+      #       should ensure_exclusion_of(:supported_os).
+      #         in_array(['Mac', 'Linux'])
+      #     end
+      #
+      # If your blacklist is a range of values, use `in_rnage`:
+      #
+      #     class Game
+      #       include ActiveModel::Model
+      #       attr_accessor :supported_os
+      #
+      #       validates_exclusion_of :supported_os, in: ['Mac', 'Linux']
+      #     end
+      #
+      #     # RSpec
+      #     describe Game do
+      #       it do
+      #         should ensure_exclusion_of(:floors_with_enemies).
+      #           in_range(5..8)
+      #       end
+      #     end
       #
-      # Options:
-      # * <tt>in_array</tt> - the array of not allowed values for this attribute
-      # * <tt>in_range</tt> - the range of not allowed values for this attribute
-      # * <tt>with_message</tt> - value the test expects to find in
-      #   <tt>errors.on(:attribute)</tt>. Regexp or string. Defaults to the
-      #   translation for :exclusion.
+      #     # Test::Unit
+      #     class GameTest < ActiveSupport::TestCase
+      #       should ensure_exclusion_of(:floors_with_enemies).
+      #         in_range(5..8)
+      #     end
       #
-      # Example:
-      #   it { should ensure_exclusion_of(:age).in_range(30..60) }
+      # #### Qualifiers
+      #
+      # ##### with_message
+      #
+      # Use `with_message` if you are using a custom validation message.
+      #
+      #     class Game
+      #       include ActiveModel::Model
+      #       attr_accessor :weapon
+      #
+      #       validates_exclusion_of :weapon,
+      #         in: ['pistol', 'paintball gun', 'stick'],
+      #         message: 'You chose a puny weapon'
+      #     end
+      #
+      #     # RSpec
+      #     describe Game do
+      #       it do
+      #         should ensure_exclusion_of(:weapon).
+      #           in_array(['pistol', 'paintball gun', 'stick']).
+      #           with_message('You chose a puny weapon')
+      #       end
+      #     end
+      #
+      #     # Test::Unit
+      #     class GameTest < ActiveSupport::TestCase
+      #       should ensure_exclusion_of(:weapon).
+      #         in_array(['pistol', 'paintball gun', 'stick']).
+      #         with_message('You chose a puny weapon')
+      #     end
+      #
+      # @return [EnsureExclusionOfMatcher]
       #
       def ensure_exclusion_of(attr)
         EnsureExclusionOfMatcher.new(attr)
       end
 
-      class EnsureExclusionOfMatcher < ValidationMatcher # :nodoc:
+      # @private
+      class EnsureExclusionOfMatcher < ValidationMatcher
+        def initialize(attribute)
+          super(attribute)
+          @array = nil
+          @range = nil
+          @expected_message = nil
+        end
+
         def in_array(array)
           @array = array
           self