rspec-fire 0.1

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/HISTORY

@@ -0,0 +1,2 @@
+0.1 - 3 September 2011
+  * Initial release

data/README.md

@@ -0,0 +1,112 @@
+rspec-fire
+==========
+
+Making your test doubles more resilient.
+
+    Once,
+    a younger brother came to him,
+    and asked,
+
+    "Father,
+    I have made and kept my little rule,
+    my fast,
+    my meditation and silence.
+    I strived to cleanse my heart of thoughts,
+    what more must I do?"
+
+    The elder rose up and,
+    stretched out his hands,
+    his fingers became like ten lamps ablaze.
+    He said,
+
+    "Why not be totally changed into fire?"
+
+      -- Desert Way, Charlie Hunter
+
+Test doubles are sweet for isolating your unit tests, but we lost something in the translation from typed languages. Ruby doesn't have a compiler that can verify the contracts being mocked out are indeed legit. This hurts larger refactorings, since you can totally change a collaborator --- renaming methods, changing the number of arguments --- and all the mocks that were standing in for it will keep pretending everything is ok.
+
+`rspec-fire` mitigates that problem, with very little change to your existing coding style.
+
+One solution would be to disallow stubbing of methods that don't exist. This is what mocha does with its `Mocha::Configuration.prevent(:stubbing_non_existent_method)` option. The downside is, you now have to load the collaborators/dependencies that you are mocking, which kind of defeats the purpose of isolated testing. Not ideal.
+
+Another solution, that `rspec-fire` adopts, is a more relaxed version that only checks that the methods exist _if the doubled class has already been loaded_. No checking will happen when running the spec in isolation, but when run in the context of the full app (either as a full spec run or by explicitly preloading collaborators on the command line) a failure will be triggered if an invalid method is being stubbed.
+
+Usage
+-----
+
+It's a gem!
+
+    gem install rspec-fire
+
+Bit of setup in your `spec_helper.rb`:
+
+    require 'rspec/fire'
+
+    RSpec.configure do |config|
+      config.include(RSpec::Fire)
+    end
+
+Specify the class being doubled in your specs:
+
+    describe User, '#suspend!' do
+      it 'sends a notification' do
+        # Only this one line differs from how you write specs normally
+        notifier = fire_double("EmailNotifier")
+
+        notifier.should_receive(:notify).with("suspended as")
+
+        user = User.new(notifier)
+        user.suspend!
+      end
+    end
+
+Run your specs:
+
+    rspec spec/user_spec.rb                         # Isolated, will pass always
+    rspec -Ilib/email_notifier.rb spec/user_spec.rb # Will fail if EmailNotifier#notify method is not defined
+
+Currently only method presence/absense is checked, but theoretically arity can be checked also.
+
+Protips
+-------
+
+### Using with an existing Rails project
+
+Create a new file `unit_helper.rb` that _does not_ require `spec_helper.rb`. Require this file where needed for isolated tests. To run an isolated spec in the context of your app:
+
+    rspec -rspec/spec_helper.rb spec/unit/my_spec.rb
+
+### Doubling class methods
+
+Particularly handy for `ActiveRecord` finders. Use `fire_class_double`. If you dig into the code, you'll find you can create subclasses of `FireDouble` to check for *any* set of methods.
+
+### Mocking Done Right (tm)
+
+* Only mock methods on collaborators, _not_ the class under test.
+* Only mock public methods.
+* Extract common mock setup to keep your specs [DRY](http://en.wikipedia.org/wiki/DRY).
+
+If you can't meet these criteria, your object is probably violating [SOLID](http://en.wikipedia.org/wiki/SOLID) principles and you should either refactor or use a non-isolated test.
+
+Compatibility
+-------------
+
+Only RSpec 2 is supported. Tested on all the rubies.
+
+[![Build Status](https://secure.travis-ci.org/xaviershay/rspec-fire.png)](http://travis-ci.org/xaviershay/rspec-fire)
+
+Developing
+----------
+
+    git clone https://github.com/xaviershay/rspec-fire.git
+    bundle install
+    bundle exec rake spec
+
+Patches welcome! I won't merge anything that isn't spec'ed, but I can help you out with that if you are getting stuck.
+
+Still need to support `#stub_chain` and `#with` methods.
+
+Status
+------
+
+`rspec-fire` is pretty new and not used widely. Yet.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |opts|
+  opts.rspec_opts = '--format documentation'
+end
+
+desc 'Default: run specs.'
+task :default => :spec

data/lib/rspec/fire.rb

@@ -0,0 +1,92 @@
+require 'rspec/mocks'
+
+module RSpec
+  module Fire
+    class FireDouble < RSpec::Mocks::Mock
+      def initialize(doubled_class, *args)
+        args << {} unless Hash === args.last
+
+        @__doubled_class_name = doubled_class
+        @__checked_methods    = :public_instance_methods
+
+        # __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)
+        super
+      end
+
+      def should_not_receive(method_name)
+        ensure_implemented(method_name)
+        super
+      end
+
+      def stub(method_name)
+        ensure_implemented(method_name)
+        super
+      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)
+        end
+      end
+
+      def recursive_const_get object, name
+        name.split('::').inject(Object) {|klass,name| klass.const_get name }
+      end
+
+      def recursive_const_defined? object, name
+        !!name.split('::').inject(Object) {|klass,name|
+          if klass && klass.const_defined?(name)
+            klass.const_get name
+          end
+        }
+      end
+
+      def implement(expected_methods, checked_methods)
+        RSpec::Matchers::Matcher.new(:implement, expected_methods, checked_methods) do |expected_methods, checked_methods|
+          unimplemented_methods = lambda {|doubled_class|
+            implemented_methods = doubled_class.send(checked_methods)
+            expected_methods - implemented_methods.map(&:to_sym) # to_sym for non-1.9 compat
+          }
+
+          match do |doubled_class|
+            unimplemented_methods[ doubled_class ].empty?
+          end
+
+          failure_message_for_should do |doubled_class|
+            implemented_methods   = Object.public_methods - doubled_class.send(checked_methods)
+            "%s does not implement:\n%s" % [
+              doubled_class,
+              unimplemented_methods[ doubled_class ].sort.map {|x|
+                "  #{x}"
+              }.join("\n")
+            ]
+          end
+        end
+      end
+    end
+
+    class FireClassDouble < FireDouble
+      def initialize(*args)
+        super
+        @__checked_methods = :public_methods
+      end
+    end
+
+    def fire_double(*args)
+      FireDouble.new(*args)
+    end
+
+    def fire_class_double(*args)
+      FireClassDouble.new(*args)
+    end
+  end
+end

data/rspec-fire.gemspec

@@ -0,0 +1,23 @@
+Gem::Specification.new do |s|
+  s.name     = 'rspec-fire'
+  s.version  = '0.1'
+  s.summary  = 'More resilient test doubles for RSpec.'
+  s.platform = Gem::Platform::RUBY
+  s.authors  = ["Xavier Shay"]
+  s.email    = ["hello@xaviershay.com"]
+  s.homepage = "http://github.com/xaviershay/rspec-fire"
+  s.has_rdoc = false
+
+  s.require_path = 'lib'
+  s.files        = Dir.glob("{spec,lib}/**/*.rb") +
+                   %w(
+                     Gemfile
+                     README.md
+                     HISTORY
+                     Rakefile
+                     rspec-fire.gemspec
+                   )
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec', '~> 2.5'
+end

data/spec/fire_double_spec.rb

@@ -0,0 +1,71 @@
+require 'spec_helper'
+
+class TestObject
+  def defined_method
+    raise "Y U NO MOCK?"
+  end
+end
+
+class TestClass
+  def self.defined_method
+    raise "Y U NO MOCK?"
+  end
+end
+
+shared_examples_for 'a fire-enhanced double method' do
+  describe 'doubled class is not loaded' do
+    let(:doubled_object) { fire_double("UnloadedObject") }
+    should_allow(:undefined_method)
+  end
+
+  describe 'doubled class is loaded' do
+    should_allow(:defined_method)
+    should_not_allow(:undefined_method)
+  end
+end
+
+shared_examples_for 'a fire-enhanced double' do
+  def self.should_allow(method_name)
+    it "should allow #{method_name}" do
+      lambda {
+        doubled_object.send(method_under_test, method_name)
+      }.should_not raise_error
+      doubled_object.rspec_reset
+    end
+  end
+
+  def self.should_not_allow(method_name)
+    it "should not allow #{method_name}" do
+      lambda {
+        doubled_object.send(method_under_test, method_name)
+      }.should fail_matching("#{method_name} does not implement", method_name)
+    end
+  end
+
+  describe '#should_receive' do
+    let(:method_under_test) { :should_receive }
+    it_should_behave_like 'a fire-enhanced double method'
+  end
+
+  describe '#should_not_receive' do
+    let(:method_under_test) { :should_not_receive }
+    it_should_behave_like 'a fire-enhanced double method'
+  end
+
+  describe '#stub' do
+    let(:method_under_test) { :stub }
+    it_should_behave_like 'a fire-enhanced double method'
+  end
+end
+
+describe '#fire_double' do
+  let(:doubled_object) { fire_double("TestObject") }
+
+  it_should_behave_like 'a fire-enhanced double'
+end
+
+describe '#fire_class_double' do
+  let(:doubled_object) { fire_class_double("TestClass") }
+
+  it_should_behave_like 'a fire-enhanced double'
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require 'rspec/fire'
+
+RSpec.configure do |config|
+  config.include(RSpec::Fire)
+
+  def fail_matching(*messages)
+    raise_error(RSpec::Expectations::ExpectationNotMetError) {|error|
+      messages.all? {|message|
+        error.message =~ /#{Regexp.escape(message)}/
+      }
+    }
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: rspec-fire
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Xavier Shay
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-09-03 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &2162234400 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2162234400
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2162233580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: *2162233580
+description: 
+email:
+- hello@xaviershay.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- spec/fire_double_spec.rb
+- spec/spec_helper.rb
+- lib/rspec/fire.rb
+- Gemfile
+- README.md
+- HISTORY
+- Rakefile
+- rspec-fire.gemspec
+homepage: http://github.com/xaviershay/rspec-fire
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: More resilient test doubles for RSpec.
+test_files: []