rspec-mocks 2.11.3 → 3.11.1

data/lib/rspec/mocks/mutate_const.rb

@@ -0,0 +1,339 @@
+RSpec::Support.require_rspec_support 'recursive_const_methods'
+
+module RSpec
+  module Mocks
+    # Provides information about constants that may (or may not)
+    # have been mutated by rspec-mocks.
+    class Constant
+      extend Support::RecursiveConstMethods
+
+      # @api private
+      def initialize(name)
+        @name = name
+        @previously_defined = false
+        @stubbed = false
+        @hidden = false
+        @valid_name = true
+        yield self if block_given?
+      end
+
+      # @return [String] The fully qualified name of the constant.
+      attr_reader :name
+
+      # @return [Object, nil] The original value (e.g. before it
+      #   was mutated by rspec-mocks) of the constant, or
+      #   nil if the constant was not previously defined.
+      attr_accessor :original_value
+
+      # @private
+      attr_writer :previously_defined, :stubbed, :hidden, :valid_name
+
+      # @return [Boolean] Whether or not the constant was defined
+      #   before the current example.
+      def previously_defined?
+        @previously_defined
+      end
+
+      # @return [Boolean] Whether or not rspec-mocks has mutated
+      #   (stubbed or hidden) this constant.
+      def mutated?
+        @stubbed || @hidden
+      end
+
+      # @return [Boolean] Whether or not rspec-mocks has stubbed
+      #   this constant.
+      def stubbed?
+        @stubbed
+      end
+
+      # @return [Boolean] Whether or not rspec-mocks has hidden
+      #   this constant.
+      def hidden?
+        @hidden
+      end
+
+      # @return [Boolean] Whether or not the provided constant name
+      #   is a valid Ruby constant name.
+      def valid_name?
+        @valid_name
+      end
+
+      # The default `to_s` isn't very useful, so a custom version is provided.
+      def to_s
+        "#<#{self.class.name} #{name}>"
+      end
+      alias inspect to_s
+
+      # @private
+      def self.unmutated(name)
+        previously_defined = !!recursive_const_defined?(name)
+      rescue NameError
+        new(name) do |c|
+          c.valid_name = false
+        end
+      else
+        new(name) do |const|
+          const.previously_defined = previously_defined
+          const.original_value = recursive_const_get(name) if previously_defined
+        end
+      end
+
+      # Queries rspec-mocks to find out information about the named constant.
+      #
+      # @param [String] name the name of the constant
+      # @return [Constant] an object contaning information about the named
+      #   constant.
+      def self.original(name)
+        mutator = ::RSpec::Mocks.space.constant_mutator_for(name)
+        mutator ? mutator.to_constant : unmutated(name)
+      end
+    end
+
+    # Provides a means to stub constants.
+    class ConstantMutator
+      extend Support::RecursiveConstMethods
+
+      # Stubs a constant.
+      #
+      # @param (see ExampleMethods#stub_const)
+      # @option (see ExampleMethods#stub_const)
+      # @return (see ExampleMethods#stub_const)
+      #
+      # @see ExampleMethods#stub_const
+      # @note It's recommended that you use `stub_const` in your
+      #  examples. This is an alternate public API that is provided
+      #  so you can stub constants in other contexts (e.g. helper
+      #  classes).
+      def self.stub(constant_name, value, options={})
+        unless String === constant_name
+          raise ArgumentError, "`stub_const` requires a String, but you provided a #{constant_name.class.name}"
+        end
+
+        mutator = if recursive_const_defined?(constant_name, &raise_on_invalid_const)
+                    DefinedConstantReplacer
+                  else
+                    UndefinedConstantSetter
+                  end
+
+        mutate(mutator.new(constant_name, value, options[:transfer_nested_constants]))
+        value
+      end
+
+      # Hides a constant.
+      #
+      # @param (see ExampleMethods#hide_const)
+      #
+      # @see ExampleMethods#hide_const
+      # @note It's recommended that you use `hide_const` in your
+      #  examples. This is an alternate public API that is provided
+      #  so you can hide constants in other contexts (e.g. helper
+      #  classes).
+      def self.hide(constant_name)
+        mutate(ConstantHider.new(constant_name, nil, {}))
+        nil
+      end
+
+      # Contains common functionality used by all of the constant mutators.
+      #
+      # @private
+      class BaseMutator
+        include Support::RecursiveConstMethods
+
+        attr_reader :original_value, :full_constant_name
+
+        def initialize(full_constant_name, mutated_value, transfer_nested_constants)
+          @full_constant_name        = normalize_const_name(full_constant_name)
+          @mutated_value             = mutated_value
+          @transfer_nested_constants = transfer_nested_constants
+          @context_parts             = @full_constant_name.split('::')
+          @const_name                = @context_parts.pop
+          @reset_performed           = false
+        end
+
+        def to_constant
+          const = Constant.new(full_constant_name)
+          const.original_value = original_value
+
+          const
+        end
+
+        def idempotently_reset
+          reset unless @reset_performed
+          @reset_performed = true
+        end
+      end
+
+      # Hides a defined constant for the duration of an example.
+      #
+      # @private
+      class ConstantHider < BaseMutator
+        def mutate
+          return unless (@defined = recursive_const_defined?(full_constant_name))
+          @context = recursive_const_get(@context_parts.join('::'))
+          @original_value = get_const_defined_on(@context, @const_name)
+
+          @context.__send__(:remove_const, @const_name)
+        end
+
+        def to_constant
+          return Constant.unmutated(full_constant_name) unless @defined
+
+          const = super
+          const.hidden = true
+          const.previously_defined = true
+
+          const
+        end
+
+        def reset
+          return unless @defined
+          @context.const_set(@const_name, @original_value)
+        end
+      end
+
+      # Replaces a defined constant for the duration of an example.
+      #
+      # @private
+      class DefinedConstantReplacer < BaseMutator
+        def initialize(*args)
+          super
+          @constants_to_transfer = []
+        end
+
+        def mutate
+          @context = recursive_const_get(@context_parts.join('::'))
+          @original_value = get_const_defined_on(@context, @const_name)
+
+          @constants_to_transfer = verify_constants_to_transfer!
+
+          @context.__send__(:remove_const, @const_name)
+          @context.const_set(@const_name, @mutated_value)
+
+          transfer_nested_constants
+        end
+
+        def to_constant
+          const = super
+          const.stubbed = true
+          const.previously_defined = true
+
+          const
+        end
+
+        def reset
+          @constants_to_transfer.each do |const|
+            @mutated_value.__send__(:remove_const, const)
+          end
+
+          @context.__send__(:remove_const, @const_name)
+          @context.const_set(@const_name, @original_value)
+        end
+
+        def transfer_nested_constants
+          @constants_to_transfer.each do |const|
+            @mutated_value.const_set(const, get_const_defined_on(original_value, const))
+          end
+        end
+
+        def verify_constants_to_transfer!
+          return [] unless should_transfer_nested_constants?
+
+          { @original_value => "the original value", @mutated_value => "the stubbed value" }.each do |value, description|
+            next if value.respond_to?(:constants)
+
+            raise ArgumentError,
+                  "Cannot transfer nested constants for #{@full_constant_name} " \
+                  "since #{description} is not a class or module and only classes " \
+                  "and modules support nested constants."
+          end
+
+          if Array === @transfer_nested_constants
+            @transfer_nested_constants = @transfer_nested_constants.map(&:to_s) if RUBY_VERSION == '1.8.7'
+            undefined_constants = @transfer_nested_constants - constants_defined_on(@original_value)
+
+            if undefined_constants.any?
+              available_constants = constants_defined_on(@original_value) - @transfer_nested_constants
+              raise ArgumentError,
+                    "Cannot transfer nested constant(s) #{undefined_constants.join(' and ')} " \
+                    "for #{@full_constant_name} since they are not defined. Did you mean " \
+                    "#{available_constants.join(' or ')}?"
+            end
+
+            @transfer_nested_constants
+          else
+            constants_defined_on(@original_value)
+          end
+        end
+
+        def should_transfer_nested_constants?
+          return true  if @transfer_nested_constants
+          return false unless RSpec::Mocks.configuration.transfer_nested_constants?
+          @original_value.respond_to?(:constants) && @mutated_value.respond_to?(:constants)
+        end
+      end
+
+      # Sets an undefined constant for the duration of an example.
+      #
+      # @private
+      class UndefinedConstantSetter < BaseMutator
+        def mutate
+          @parent = @context_parts.inject(Object) do |klass, name|
+            if const_defined_on?(klass, name)
+              get_const_defined_on(klass, name)
+            else
+              ConstantMutator.stub(name_for(klass, name), Module.new)
+            end
+          end
+
+          @parent.const_set(@const_name, @mutated_value)
+        end
+
+        def to_constant
+          const = super
+          const.stubbed = true
+          const.previously_defined = false
+
+          const
+        end
+
+        def reset
+          @parent.__send__(:remove_const, @const_name)
+        end
+
+      private
+
+        def name_for(parent, name)
+          root = if parent == Object
+                   ''
+                 else
+                   parent.name
+                 end
+          root + '::' + name
+        end
+      end
+
+      # Uses the mutator to mutate (stub or hide) a constant. Ensures that
+      # the mutator is correctly registered so it can be backed out at the end
+      # of the test.
+      #
+      # @private
+      def self.mutate(mutator)
+        ::RSpec::Mocks.space.register_constant_mutator(mutator)
+        mutator.mutate
+      end
+
+      # Used internally by the constant stubbing to raise a helpful
+      # error when a constant like "A::B::C" is stubbed and A::B is
+      # not a module (and thus, it's impossible to define "A::B::C"
+      # since only modules can have nested constants).
+      #
+      # @api private
+      def self.raise_on_invalid_const
+        lambda do |const_name, failed_name|
+          raise "Cannot stub constant #{failed_name} on #{const_name} " \
+                "since #{const_name} is not a module."
+        end
+      end
+    end
+  end
+end

data/lib/rspec/mocks/object_reference.rb

@@ -0,0 +1,149 @@
+module RSpec
+  module Mocks
+    # @private
+    class ObjectReference
+      # Returns an appropriate Object or Module reference based
+      # on the given argument.
+      def self.for(object_module_or_name, allow_direct_object_refs=false)
+        case object_module_or_name
+        when Module
+          if anonymous_module?(object_module_or_name)
+            DirectObjectReference.new(object_module_or_name)
+          else
+            # Use a `NamedObjectReference` if it has a name because this
+            # will use the original value of the constant in case it has
+            # been stubbed.
+            NamedObjectReference.new(name_of(object_module_or_name))
+          end
+        when String
+          NamedObjectReference.new(object_module_or_name)
+        else
+          if allow_direct_object_refs
+            DirectObjectReference.new(object_module_or_name)
+          else
+            raise ArgumentError,
+                  "Module or String expected, got #{object_module_or_name.inspect}"
+          end
+        end
+      end
+
+      if Module.new.name.nil?
+        def self.anonymous_module?(mod)
+          !name_of(mod)
+        end
+      else # 1.8.7
+        def self.anonymous_module?(mod)
+          name_of(mod) == ""
+        end
+      end
+      private_class_method :anonymous_module?
+
+      def self.name_of(mod)
+        MODULE_NAME_METHOD.bind(mod).call
+      end
+      private_class_method :name_of
+
+      # @private
+      MODULE_NAME_METHOD = Module.instance_method(:name)
+    end
+
+    # An implementation of rspec-mocks' reference interface.
+    # Used when an object is passed to {ExampleMethods#object_double}, or
+    # an anonymous class or module is passed to {ExampleMethods#instance_double}
+    # or {ExampleMethods#class_double}.
+    # Represents a reference to that object.
+    # @see NamedObjectReference
+    class DirectObjectReference
+      # @param object [Object] the object to which this refers
+      def initialize(object)
+        @object = object
+      end
+
+      # @return [String] the object's description (via `#inspect`).
+      def description
+        @object.inspect
+      end
+
+      # Defined for interface parity with the other object reference
+      # implementations. Raises an `ArgumentError` to indicate that `as_stubbed_const`
+      # is invalid when passing an object argument to `object_double`.
+      def const_to_replace
+        raise ArgumentError,
+              "Can not perform constant replacement with an anonymous object."
+      end
+
+      # The target of the verifying double (the object itself).
+      #
+      # @return [Object]
+      def target
+        @object
+      end
+
+      # Always returns true for an object as the class is defined.
+      #
+      # @return [true]
+      def defined?
+        true
+      end
+
+      # Yields if the reference target is loaded, providing a generic mechanism
+      # to optionally run a bit of code only when a reference's target is
+      # loaded.
+      #
+      # This specific implementation always yields because direct references
+      # are always loaded.
+      #
+      # @yield [Object] the target of this reference.
+      def when_loaded
+        yield @object
+      end
+    end
+
+    # An implementation of rspec-mocks' reference interface.
+    # Used when a string is passed to {ExampleMethods#object_double},
+    # and when a string, named class or named module is passed to
+    # {ExampleMethods#instance_double}, or {ExampleMethods#class_double}.
+    # Represents a reference to the object named (via a constant lookup)
+    # by the string.
+    # @see DirectObjectReference
+    class NamedObjectReference
+      # @param const_name [String] constant name
+      def initialize(const_name)
+        @const_name = const_name
+      end
+
+      # @return [Boolean] true if the named constant is defined, false otherwise.
+      def defined?
+        !!object
+      end
+
+      # @return [String] the constant name to replace with a double.
+      def const_to_replace
+        @const_name
+      end
+      alias description const_to_replace
+
+      # @return [Object, nil] the target of the verifying double (the named object), or
+      #   nil if it is not defined.
+      def target
+        object
+      end
+
+      # Yields if the reference target is loaded, providing a generic mechanism
+      # to optionally run a bit of code only when a reference's target is
+      # loaded.
+      #
+      # @yield [Object] the target object
+      def when_loaded
+        yield object if object
+      end
+
+    private
+
+      def object
+        return @object if defined?(@object)
+        @object = Constant.original(@const_name).original_value
+      end
+    end
+  end
+end

data/lib/rspec/mocks/order_group.rb

@@ -3,37 +3,78 @@ module RSpec
     # @private
     class OrderGroup
       def initialize
-        @ordering = Array.new
+        @expectations = []
+        @invocation_order = []
+        @index = 0
       end
 
       # @private
       def register(expectation)
-        @ordering << expectation
+        @expectations << expectation
+      end
+
+      def invoked(message)
+        @invocation_order << message
       end
 
       # @private
       def ready_for?(expectation)
-        @ordering.first == expectation
+        remaining_expectations.find(&:ordered?) == expectation
       end
 
       # @private
       def consume
-        @ordering.shift
+        remaining_expectations.each_with_index do |expectation, index|
+          next unless expectation.ordered?
+
+          @index += index + 1
+          return expectation
+        end
+        nil
       end
 
       # @private
       def handle_order_constraint(expectation)
-        return unless @ordering.include?(expectation)
+        return unless expectation.ordered? && remaining_expectations.include?(expectation)
         return consume if ready_for?(expectation)
         expectation.raise_out_of_order_error
       end
 
+      def verify_invocation_order(expectation)
+        expectation.raise_out_of_order_error unless expectations_invoked_in_order?
+        true
+      end
+
       def clear
-        @ordering.clear
+        @index = 0
+        @invocation_order.clear
+        @expectations.clear
       end
 
       def empty?
-        @ordering.empty?
+        @expectations.empty?
+      end
+
+    private
+
+      def remaining_expectations
+        @expectations[@index..-1] || []
+      end
+
+      def expectations_invoked_in_order?
+        invoked_expectations == expected_invocations
+      end
+
+      def invoked_expectations
+        @expectations.select { |e| e.ordered? && @invocation_order.include?(e) }
+      end
+
+      def expected_invocations
+        @invocation_order.map { |invocation| expectation_for(invocation) }.compact
+      end
+
+      def expectation_for(message)
+        @expectations.find { |e| message == e }
       end
     end
   end