= CROSS-STUB makes cross process stubbing possible !!

== Introduction

Existing mocking/stubbing frameworks support only stubbing in the current process. This is OK most of the time. However, when running cucumber integration test suite in non-webrat mode, these in-process stubbing frameworks simply doesn't help. Eg. I want Time.now to always return a timing that should be a Sunday, how do I do that when running cucumber in selenium, culerity, steam, blah, blah mode? It doesn't seem straight-forward me.

(Let's not argue whether stubbing should be encouraged. It is an itch, the poor itch needs to be scratched.)

== Getting Started

It's hosted on gemcutter.org.

  $ sudo gem install cross-stub

== Setting Up

If you are using rails, you are in luck:

  $ ./script/generate cucumber
  $ ./script/generate cross_stub

== Using It

Using cross-stub is simple:

#1. Simple returning of nil or non-nil value:

  class Someone
    def self.laugh
      'HaHa'
    end
  end

  Someone.xstub(:laugh)
  Someone.laugh # yields: nil

  Someone.xstub(:laugh, 'HoHo')
  Someone.laugh # yields: 'HoHo'

#2. If a stubbed method requires argument, pass :xstub a proc:

  Someone.xstub do
    def loves(other)
      "I love #{other}"
    end
  end

  Someone.loves('you') # yields: 'I love you'

#3. Something more complicated:

  something = 'hello'
  Someone.xstub do
    def do_action(who, action)
      %\#{who} #{action} #{something}\
    end
  end

  Someone.do_action('i', 'say') # failure !!

The above fails as a result of undefined variable/method 'something', to workaround we can have:

  Someone.xstub(:something => 'hello') do
    def do_action(who, action)
      %\#{who} #{action} #{something}\
    end
  end

  Someone.do_action('i', 'say') # yields: 'i say hello'

== Caveats

1. Cross-stub uses ruby's Marshal class to dump & load the stubs, thus it has the same limitations as Marshal

2. Cross-stub only supports stubbing of class methods, since it makes no sense to do cross process stubbing of instances

== Contacts

Written 2009 by:

1. NgTzeYang, contact ngty77[at]gmail.com or http://github.com/ngty

2. WongLiangZan, contact liangzan[at]gmail.com or http://github.com/liangzan

Released under the MIT license