rspec-fire 0.2.2 → 0.3.0

data/HISTORY

@@ -4,8 +4,11 @@
 0.2 - 3 September 2011
   * Checks method arity when a 'with' call is present
 
-0.2.1 - 14 January 2011
+0.2.1 - 14 January 2012
   * rspec 2.8 support
 
-0.2.2 - 31 January 2011
-  * Added missing require needed for some code bases.
+0.2.2 - 31 January 2012
+  * Added missing require needed for some code bases.
+
+0.3.0 - 17 March 2012
+  * Added support for doubling constants.

data/README.md

@@ -63,6 +63,12 @@ Bit of setup in your `spec_helper.rb`:
 
 Specify the class being doubled in your specs:
 
+    class User < Struct.new(:notifier)
+      def suspend!
+        notifier.notify("suspended as")
+      end
+    end
+
     describe User, '#suspend!' do
       it 'sends a notification' do
         # Only this one line differs from how you write specs normally
@@ -97,6 +103,81 @@ the context of your app:
 
     rspec -rspec/spec_helper.rb spec/unit/my_spec.rb
 
+### Doubling constants
+
+A particularly excellent feature. You can stub out constants using
+`fire_replaced_class_double`, removing the need to dependency inject
+collaborators (a technique that can sometimes be cumbersome).
+
+    class User
+      def suspend!
+        EmailNotifier.notify("suspended as")
+      end
+    end
+
+    describe User, '#suspend!' do
+      it 'sends a notification' do
+        # Only this one line differs from how you write specs normally
+        notifier = fire_replaced_class_double("EmailNotifier")
+
+        # Alternately, you can use this fluent interface
+        notifier = fire_class_double("EmailNotifier").as_replaced_constant
+
+        notifier.should_receive(:notify).with("suspended as")
+
+        user = User.new
+        user.suspend!
+      end
+    end
+
+This will probably become the default behaviour once we figure out a better
+name for it.
+
+### Stubbing Constants
+
+The constant stubbing logic used when doubling class constants can be
+used for any constant.
+
+    class MapReduceRunner
+      ITEMS_PER_BATCH = 1000
+    end
+
+    describe MapReduceRunner, "when it has too many items for one batch" do
+      it "breaks the items up into smaller batches" do
+        # the test would be really slow if we had to make more than 1000 items,
+        # so let's change the threshold for this one test.
+        stub_const("MapReduceRunner::ITEMS_PER_BATCH", 10)
+
+        MapReduceRunner.run_with(twenty_items)
+      end
+    end
+
+### Transferring nested constants to doubled constants
+
+When you use `fire_replaced_class_double` to replace a class or module
+that also acts as a namespace for other classes and constants, your
+access to these constants is cut off for the duration of the example
+(since the doubled constant does not automatically have all of the
+nested constants). The `:transfer_nested_constants` option is provided
+to deal with this:
+
+    module MyCoolGem
+      class Widget
+      end
+    end
+
+    # once you do this, you can no longer access MyCoolGem::Widget in your example...
+    fire_replaced_class_double("MyCoolGem")
+
+    # ...unless you tell rspec-fire to transfer all nested constants
+    fire_class_double("MyCoolGem").as_replaced_constant(:transfer_nested_constants => true)
+
+    # ...or give it a list of constants to transfer
+    fire_class_double("MyCoolGem").as_replaced_constant(:transfer_nested_constants => [:Widget])
+
+    # You can also use this when using #stub_const directly
+    stub_const("MyCoolGem", :transfer_nested_constants => true)
+
 ### Doubling class methods
 
 Particularly handy for `ActiveRecord` finders. Use `fire_class_double`. If you

data/lib/rspec/fire.rb

@@ -5,11 +5,11 @@ require 'delegate'
 module RSpec
   module Fire
     module RecursiveConstMethods
-      def recursive_const_get object, name
+      def recursive_const_get name
         name.split('::').inject(Object) {|klass,name| klass.const_get name }
       end
 
-      def recursive_const_defined? object, name
+      def recursive_const_defined? name
         !!name.split('::').inject(Object) {|klass,name|
           if klass && klass.const_defined?(name)
             klass.const_get name
@@ -24,10 +24,11 @@ module RSpec
 
       AM = RSpec::Mocks::ArgumentMatchers
 
-      def initialize(doubled_class_name, method_finder, backing)
-        @doubled_class_name = doubled_class_name
+      def initialize(double, method_finder, backing)
+        @double             = double
         @method_finder      = method_finder
         @backing            = backing
+        @sym = backing.respond_to?(:sym) ? @backing.sym : @backing.message
         super(backing)
       end
 
@@ -50,10 +51,8 @@ module RSpec
       protected
 
       def ensure_arity(actual)
-        if recursive_const_defined?(Object, @doubled_class_name)
-          recursive_const_get(Object, @doubled_class_name).
-            send(@method_finder, sym).
-            should have_arity(actual)
+        @double.with_doubled_class do |klass|
+          klass.send(@method_finder, @sym).should have_arity(actual)
         end
       end
 
@@ -69,23 +68,13 @@ module RSpec
       end
     end
 
-    class FireDouble < RSpec::Mocks::Mock
+    module FireDoublable
       extend RSpec::Matchers::DSL
       include RecursiveConstMethods
 
-      def initialize(doubled_class, *args)
-        args << {} unless Hash === args.last
-
-        @__doubled_class_name = doubled_class
-
-        # __declared_as copied from rspec/mocks definition of `double`
-        args.last[:__declared_as] = 'FireDouble'
-        super(doubled_class, *args)
-      end
-
       def should_receive(method_name)
         ensure_implemented(method_name)
-        ShouldProxy.new(@__doubled_class_name, @__method_finder, super)
+        ShouldProxy.new(self, @__method_finder, super)
       end
 
       def should_not_receive(method_name)
@@ -98,12 +87,17 @@ module RSpec
         super
       end
 
+      def with_doubled_class
+        if recursive_const_defined?(@__doubled_class_name)
+          yield recursive_const_get(@__doubled_class_name)
+        end
+      end
+
       protected
 
       def ensure_implemented(*method_names)
-        if recursive_const_defined?(Object, @__doubled_class_name)
-          recursive_const_get(Object, @__doubled_class_name).
-            should implement(method_names, @__checked_methods)
+        with_doubled_class do |klass|
+          klass.should implement(method_names, @__checked_methods)
         end
       end
 
@@ -131,20 +125,190 @@ module RSpec
       end
     end
 
-    class FireObjectDouble < FireDouble
-      def initialize(*args)
+    class FireObjectDouble < RSpec::Mocks::Mock
+      include FireDoublable
+
+      def initialize(doubled_class, *args)
+        args << {} unless Hash === args.last
+
+        @__doubled_class_name = doubled_class
+
+        # __declared_as copied from rspec/mocks definition of `double`
+        args.last[:__declared_as] = 'FireDouble'
         super
         @__checked_methods = :public_instance_methods
         @__method_finder   = :instance_method
       end
     end
 
-    class FireClassDouble < FireDouble
-      def initialize(*args)
-        super
-        @__checked_methods = :public_methods
-        @__method_finder   = :method
+    class FireClassDoubleBuilder
+      def self.build(doubled_class, stubs = {})
+        Module.new do
+          extend FireDoublable
+
+          @__doubled_class_name = doubled_class
+          @__checked_methods = :public_methods
+          @__method_finder   = :method
+
+          stubs.each do |message, response|
+            stub(message).and_return(response)
+          end
+
+          def self.as_replaced_constant(options = {})
+            @__original_class = ConstantStubber.stub!(@__doubled_class_name, self, options)
+            extend AsReplacedConstant
+            self
+          end
+
+          def self.to_s
+            @__doubled_class_name + " (fire double)"
+          end
+
+          def self.inspect
+            to_s
+          end
+
+          def self.name
+            @__doubled_class_name
+          end
+
+          def self.method_missing(name, *args)
+            __mock_proxy.raise_unexpected_message_error(name, *args)
+          end
+        end
+      end
+
+      module AsReplacedConstant
+        def with_doubled_class
+          yield @__original_class if @__original_class
+        end
+      end
+    end
+
+    class ConstantStubber
+      extend RecursiveConstMethods
+
+      class DefinedConstantReplacer
+        include RecursiveConstMethods
+        attr_reader :original_value
+
+        def initialize(full_constant_name, stubbed_value, transfer_nested_constants)
+          @full_constant_name        = full_constant_name
+          @stubbed_value             = stubbed_value
+          @transfer_nested_constants = transfer_nested_constants
+        end
+
+        def stub!
+          context_parts = @full_constant_name.split('::')
+          @const_name = context_parts.pop
+          @context = recursive_const_get(context_parts.join('::'))
+          @original_value = @context.const_get(@const_name)
+
+          constants_to_transfer = verify_constants_to_transfer!
+
+          @context.send(:remove_const, @const_name)
+          @context.const_set(@const_name, @stubbed_value)
+
+          transfer_nested_constants(constants_to_transfer)
+        end
+
+        def rspec_reset
+          if recursive_const_get(@full_constant_name).equal?(@stubbed_value)
+            @context.send(:remove_const, @const_name)
+            @context.const_set(@const_name, @original_value)
+          end
+        end
+
+        def transfer_nested_constants(constants)
+          constants.each do |const|
+            @stubbed_value.const_set(const, original_value.const_get(const))
+          end
+        end
+
+        def verify_constants_to_transfer!
+          return [] unless @transfer_nested_constants
+
+          { @original_value => "the original value", @stubbed_value => "the stubbed value" }.each do |value, description|
+            unless 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
+          end
+
+          if @transfer_nested_constants.is_a?(Array)
+            @transfer_nested_constants = @transfer_nested_constants.map(&:to_s) if RUBY_VERSION == '1.8.7'
+            undefined_constants = @transfer_nested_constants - @original_value.constants
+
+            if undefined_constants.any?
+              available_constants = @original_value.constants - @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
+            @original_value.constants
+          end
+        end
+      end
+
+      class UndefinedConstantSetter
+        include RecursiveConstMethods
+
+        def initialize(full_constant_name, stubbed_value)
+          @full_constant_name = full_constant_name
+          @stubbed_value      = stubbed_value
+        end
+
+        def original_value
+          # always nil
+        end
+
+        def stub!
+          context_parts = @full_constant_name.split('::')
+          const_name = context_parts.pop
+
+          remaining_parts = context_parts.dup
+          @deepest_defined_const = context_parts.inject(Object) do |klass, name|
+            break klass unless klass.const_defined?(name)
+            remaining_parts.shift
+            klass.const_get(name)
+          end
+
+          context = remaining_parts.inject(@deepest_defined_const) do |klass, name|
+            klass.const_set(name, Module.new)
+          end
+
+          @const_to_remove = remaining_parts.first || const_name
+          context.const_set(const_name, @stubbed_value)
+        end
+
+        def rspec_reset
+          if recursive_const_get(@full_constant_name).equal?(@stubbed_value)
+            @deepest_defined_const.send(:remove_const, @const_to_remove)
+          end
+        end
       end
+
+      def self.stub!(constant_name, value, options = {})
+        stubber = if recursive_const_defined?(constant_name)
+          DefinedConstantReplacer.new(constant_name, value, options[:transfer_nested_constants])
+        else
+          UndefinedConstantSetter.new(constant_name, value)
+        end
+
+        stubber.stub!
+        ::RSpec::Mocks.space.add(stubber)
+        stubber.original_value
+      end
+    end
+
+    def stub_const(name, value, options = {})
+      ConstantStubber.stub!(name, value, options)
     end
 
     def fire_double(*args)
@@ -152,7 +316,11 @@ module RSpec
     end
 
     def fire_class_double(*args)
-      FireClassDouble.new(*args)
+      FireClassDoubleBuilder.build(*args)
+    end
+
+    def fire_replaced_class_double(*args)
+      fire_class_double(*args).as_replaced_constant
     end
   end
 end

data/rspec-fire.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name     = 'rspec-fire'
-  s.version  = '0.2.2'
+  s.version  = '0.3.0'
   s.summary  = 'More resilient test doubles for RSpec.'
   s.platform = Gem::Platform::RUBY
   s.authors  = ["Xavier Shay"]

data/spec/fire_double_spec.rb

@@ -1,5 +1,15 @@
 require 'spec_helper'
 
+TOP_LEVEL_VALUE_CONST = 7
+
+RSpec::Mocks::Space.class_eval do
+  # Deal with the fact that #mocks was renamed to #receivers for RSpec 2.9:
+  # https://github.com/rspec/rspec-mocks/commit/17c259ea5143d309e90ca6d53d40f6356ac2d0a5
+  unless private_instance_methods.map(&:to_sym).include?(:receivers)
+    alias_method :receivers, :mocks
+  end
+end
+
 module TestMethods
   def defined_method
     raise "Y U NO MOCK?"
@@ -16,6 +26,14 @@ end
 
 class TestClass
   extend TestMethods
+
+  M = :m
+  N = :n
+
+  class Nested
+    class NestedEvenMore
+    end
+  end
 end
 
 shared_examples_for 'a fire-enhanced double method' do
@@ -134,4 +152,294 @@ describe '#fire_class_double' do
   let(:doubled_object) { fire_class_double("TestClass") }
 
   it_should_behave_like 'a fire-enhanced double'
+
+  it 'uses a module for the doubled object so that it supports nested constants like a real class' do
+    doubled_object.should be_a(Module)
+  end
+
+  it 'has a readable string representation' do
+    doubled_object.to_s.should include("TestClass (fire double)")
+    doubled_object.inspect.should include("TestClass (fire double)")
+  end
+
+  it 'assigns the class name' do
+    TestClass.name.should eq("TestClass")
+    doubled_object.name.should eq("TestClass")
+  end
+
+  it 'raises a mock expectation error for undefind methods' do
+    expect {
+      doubled_object.abc
+    }.to raise_error(RSpec::Mocks::MockExpectationError)
+  end
+
+  it 'allows stubs to be specified as a hash' do
+    double = fire_class_double("SomeClass", :a => 5, :b => 8)
+    double.a.should eq(5)
+    double.b.should eq(8)
+  end
+end
+
+def reset_rspec_mocks
+  ::RSpec::Mocks.space.reset_all
+end
+
+describe '#fire_replaced_class_double (for an existing class)' do
+  let(:doubled_object) { fire_replaced_class_double("TestClass") }
+
+  it_should_behave_like 'a fire-enhanced double'
+
+  it 'replaces the constant for the duration of the test' do
+    orig_class = TestClass
+    doubled_object.should_not be(orig_class)
+    TestClass.should be(doubled_object)
+    reset_rspec_mocks
+    TestClass.should be(orig_class)
+  end
+
+  it 'supports transferring nested constants to the double' do
+    fire_class_double("TestClass").as_replaced_constant(:transfer_nested_constants => true)
+    TestClass::M.should eq(:m)
+    TestClass::N.should eq(:n)
+  end
+end
+
+describe '#fire_replaced_class_double (for a non-existant class)' do
+  it 'allows any method to be mocked' do
+    double = fire_replaced_class_double("A::B::C")
+    double.should_receive(:foo).with("a").and_return(:bar)
+    A::B::C.foo("a").should eq(:bar)
+  end
+end
+
+shared_examples_for "loaded constant stubbing" do |const_name|
+  include RSpec::Fire::RecursiveConstMethods
+  let!(:original_const_value) { const }
+  after { change_const_value_to(original_const_value) }
+
+  define_method :const do
+    recursive_const_get(const_name)
+  end
+
+  define_method :parent_const do
+    recursive_const_get("Object::" + const_name.sub(/(::)?[^:]+\z/, ''))
+  end
+
+  define_method :last_const_part do
+    const_name.split('::').last
+  end
+
+  def change_const_value_to(value)
+    parent_const.send(:remove_const, last_const_part)
+    parent_const.const_set(last_const_part, value)
+  end
+
+  it 'allows it to be stubbed' do
+    const.should_not eq(7)
+    stub_const(const_name, 7)
+    const.should eq(7)
+  end
+
+  it 'resets it to its original value when rspec clears its mocks' do
+    original_value = const
+    original_value.should_not eq(:a)
+    stub_const(const_name, :a)
+    reset_rspec_mocks
+    const.should be(original_value)
+  end
+
+  it 'does not reset the value to its original value when rspec clears its mocks if the example modifies the value of the constant' do
+    stub_const(const_name, :a)
+    change_const_value_to(new_const_value = Object.new)
+    reset_rspec_mocks
+    const.should be(new_const_value)
+  end
+
+  it 'returns the original value' do
+    orig_value = const
+    returned_value = stub_const(const_name, 7)
+    returned_value.should be(orig_value)
+  end
+end
+
+shared_examples_for "unloaded constant stubbing" do |const_name|
+  include RSpec::Fire::RecursiveConstMethods
+  before { recursive_const_defined?(const_name).should be_false }
+
+  define_method :const do
+    recursive_const_get(const_name)
+  end
+
+  define_method :parent_const do
+    recursive_const_get("Object::" + const_name.sub(/(::)?[^:]+\z/, ''))
+  end
+
+  define_method :last_const_part do
+    const_name.split('::').last
+  end
+
+  def change_const_value_to(value)
+    parent_const.send(:remove_const, last_const_part)
+    parent_const.const_set(last_const_part, value)
+  end
+
+  it 'allows it to be stubbed' do
+    stub_const(const_name, 7)
+    const.should eq(7)
+  end
+
+  it 'removes the constant when rspec clears its mocks' do
+    stub_const(const_name, 7)
+    reset_rspec_mocks
+    recursive_const_defined?(const_name).should be_false
+  end
+
+  it 'does not remove the constant when the example manually sets it' do
+    begin
+      stub_const(const_name, 7)
+      stubber = RSpec::Mocks.space.send(:receivers).first
+      change_const_value_to(new_const_value = Object.new)
+      reset_rspec_mocks
+      const.should equal(new_const_value)
+    ensure
+      change_const_value_to(7)
+      stubber.rspec_reset
+    end
+  end
+
+  it 'returns nil since it was not originally set' do
+    stub_const(const_name, 7).should be_nil
+  end
+
+  it 'ignores the :transfer_nested_constants if passed' do
+    stub = Module.new
+    stub_const(const_name, stub, :transfer_nested_constants => true)
+    stub.constants.should eq([])
+  end
+end
+
+describe "#stub_const" do
+  context 'for a loaded unnested constant' do
+    it_behaves_like "loaded constant stubbing", "TestClass"
+
+    it 'allows nested constants to be transferred to a stub module' do
+      tc_nested = TestClass::Nested
+      stub = Module.new
+      stub_const("TestClass", stub, :transfer_nested_constants => true)
+      stub::M.should eq(:m)
+      stub::N.should eq(:n)
+      stub::Nested.should be(tc_nested)
+    end
+
+    it 'allows nested constants to be selectively transferred to a stub module' do
+      stub = Module.new
+      stub_const("TestClass", stub, :transfer_nested_constants => [:M, :N])
+      stub::M.should eq(:m)
+      stub::N.should eq(:n)
+      defined?(stub::Nested).should be_false
+    end
+
+    it 'raises an error if asked to transfer nested constants but given an object that does not support them' do
+      original_tc = TestClass
+      stub = Object.new
+      expect {
+        stub_const("TestClass", stub, :transfer_nested_constants => true)
+      }.to raise_error(ArgumentError)
+
+      TestClass.should be(original_tc)
+
+      expect {
+        stub_const("TestClass", stub, :transfer_nested_constants => [:M])
+      }.to raise_error(ArgumentError)
+
+      TestClass.should be(original_tc)
+    end
+
+    it 'raises an error if asked to transfer nested constants on a constant that does not support nested constants' do
+      stub = Module.new
+      expect {
+        stub_const("TOP_LEVEL_VALUE_CONST", stub, :transfer_nested_constants => true)
+      }.to raise_error(ArgumentError)
+
+      TOP_LEVEL_VALUE_CONST.should eq(7)
+
+      expect {
+        stub_const("TOP_LEVEL_VALUE_CONST", stub, :transfer_nested_constants => [:M])
+      }.to raise_error(ArgumentError)
+
+      TOP_LEVEL_VALUE_CONST.should eq(7)
+    end
+
+    it 'raises an error if asked to transfer a nested constant that is not defined' do
+      original_tc = TestClass
+      defined?(TestClass::V).should be_false
+      stub = Module.new
+
+      expect {
+        stub_const("TestClass", stub, :transfer_nested_constants => [:V])
+      }.to raise_error(/cannot transfer nested constant.*V/i)
+
+      TestClass.should be(original_tc)
+    end
+  end
+
+  context 'for a loaded nested constant' do
+    it_behaves_like "loaded constant stubbing", "TestClass::Nested"
+  end
+
+  context 'for a loaded deeply nested constant' do
+    it_behaves_like "loaded constant stubbing", "TestClass::Nested::NestedEvenMore"
+  end
+
+  context 'for an unloaded unnested constant' do
+    it_behaves_like "unloaded constant stubbing", "X"
+  end
+
+  context 'for an unloaded nested constant' do
+    it_behaves_like "unloaded constant stubbing", "X::Y"
+
+    it 'removes the root constant when rspec clears its mocks' do
+      defined?(X).should be_false
+      stub_const("X::Y", 7)
+      reset_rspec_mocks
+      defined?(X).should be_false
+    end
+  end
+
+  context 'for an unloaded deeply nested constant' do
+    it_behaves_like "unloaded constant stubbing", "X::Y::Z"
+
+    it 'removes the root constant when rspec clears its mocks' do
+      defined?(X).should be_false
+      stub_const("X::Y::Z", 7)
+      reset_rspec_mocks
+      defined?(X).should be_false
+    end
+  end
+
+  context 'for an unloaded constant nested within a loaded constant' do
+    it_behaves_like "unloaded constant stubbing", "TestClass::X"
+
+    it 'removes the unloaded constant but leaves the loaded constant when rspec resets its mocks' do
+      defined?(TestClass).should be_true
+      defined?(TestClass::X).should be_false
+      stub_const("TestClass::X", 7)
+      reset_rspec_mocks
+      defined?(TestClass).should be_true
+      defined?(TestClass::X).should be_false
+    end
+  end
+
+  context 'for an unloaded constant nested deeply within a deeply nested loaded constant' do
+    it_behaves_like "unloaded constant stubbing", "TestClass::Nested::NestedEvenMore::X::Y::Z"
+
+    it 'removes the first unloaded constant but leaves the loaded nested constant when rspec resets its mocks' do
+      defined?(TestClass::Nested::NestedEvenMore).should be_true
+      defined?(TestClass::Nested::NestedEvenMore::X).should be_false
+      stub_const("TestClass::Nested::NestedEvenMore::X::Y::Z", 7)
+      reset_rspec_mocks
+      defined?(TestClass::Nested::NestedEvenMore).should be_true
+      defined?(TestClass::Nested::NestedEvenMore::X).should be_false
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-fire
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-31 00:00:00.000000000 Z
+date: 2012-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2156305180 !ruby/object:Gem::Requirement
+  requirement: &2153330640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2156305180
+  version_requirements: *2153330640
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2156304600 !ruby/object:Gem::Requirement
+  requirement: &2153330120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,7 +32,7 @@ dependencies:
         version: '2.5'
   type: :development
   prerelease: false
-  version_requirements: *2156304600
+  version_requirements: *2153330120
 description: 
 email:
 - hello@xaviershay.com