README

= Amok, a compact mock library

Amok is a simple and compact mock library that is independent of any
testing framework but made to work nicely with test/spec and bacon.
It provides mocking and stubbing of any object's methods.


== Whirl-wind tour

  Amok.new(Item) {
    on.find(1) {
      Amok.with(:name => "Deschutes",
                :description => "Deschutes model Guitar",
                :unit_price => Money.new(2400.00))
    }
  }

  Item.find(1).name.should.equal "Deschutes"

  Amok.with(Google4R::Checkout::CheckoutCommand) { |obj, mock|
    mock.on.new { |*args|
      Amok.new(Google4R::Checkout::CheckoutCommand.new(*args)) {
        need(1).send_to_google_checkout {
          Amok.with(:redirect_url => "http://google.response.url")
        }
      }
    }

    Item.find(1).purchase.redirect_url.should.equal "http://google.response.url"
  }


== Implemented features

Amok.new(obj)::
  creates a mock definition object to stub methods of obj.

Amok.with(obj) { |obj, mock| ... }::
  Use Amok.with to automatically check at the end of the block whether
  required methods have been called.

Amok.make(hash)::
  is used to conveniently make mocks that return the hash values when
  the hash key is sent.

mock.on._method_ {...}::
  run the block when _method_ is sent.  The block can call
  +mock.previous(_method_, ...)+ to call the original method.

mock.on._method_(_args_...) {...}::
  run the block when _method_ is sent with exactly the same _args_,
  else run the original method.  The block can call
  +mock.previous(_method_, ...)+ to call the original method.

mock.on(method, args) {...}::
  like mock.on._method_, but _method_ can be passed as a symbol and _args_.
  (This allows you to define methods that require empty _args_,
  because mock.on._method_() does not check _args_.)

mock.need._method_::
  check that _method_ is called

mock.need(n)._method_::
  check that _method_ is called exactly _n_ times.

mock.need._method_ {...}::
  like mock.on._method_ {...}, but check that _method_ is called.

mock.need(n)._method_ {...}::
  like mock.on._method_ {...}, but check that _method_ is called exactly
  _n_ times.

mock.need(method, args, n) {...}::
  same as mock.need(n)._method_(args).

mock.never._method_::
  check that _method_ is never called.

mock.never(method)::
  same as mock.never._method_.

mock.successful?::
  returns true if all checks passed.

mock.errors::
  returns an array of failed checks.

mock.validate::
  raises Amok::Failed when checks failed.


== Words of advice

Mocking and stubbing are possibly dangerous operations, and easily can
change the meaning of your tests in ways you don't intent.  Be alert,
and only use them when needed.  Remember, the purpose of your tests is
to test your code, and not test your mocks.


== Thanks to

* raggi and jazen for making me write it.
* mfp for instance_exec.
* authors of all previous mock libraries for inspiration.


== History

* September 25th, 2008: Coding started.


== Contact

Please mail bugs, suggestions and patches to
<mailto:chneukirchen@gmail.com>.

Git repository (rebased patches on master are most welcome):
git://github.com/chneukirchen/amok.git

Project page:
http://github.com/chneukirchen/amok/tree/master


== Copying

Copyright (C) 2008 Christian Neukirchen <http://purl.org/net/chneukirchen>

Amok is freely distributable under the terms of an MIT-style license.
See COPYING or http://www.opensource.org/licenses/mit-license.php.


== Links

Mocks Aren't Stubs:: <http://martinfowler.com/articles/mocksArentStubs.html>

Christian Neukirchen:: <http://chneukirchen.org/>