# Fudge Documentation

Fudge is a Python module for using fake objects (mocks and stubs) to test real ones.

In readable Python code, you declare what methods are available on your fake and how they should be called. Then you inject that into your application and start testing. This declarative approach means you don’t have to record and playback actions and you don’t have to inspect your fakes after running code. If the fake object was used incorrectly then you’ll see an informative exception message with a traceback that points to the culprit.

Fudge was inspired by Mocha which is a simpler version of jMock. But unlike Mocha, Fudge does not automatically hijack real objects; you explicitly patch them in your test. And unlike jMock, Fudge is only as strict about expectations as you want it to be. If the type of arguments sent to the fake method aren’t important then you don’t have to declare an expectation for them.

## Download / Install

Just type:

    $ pip install fudge

You can get the pip command here. Fudge requires Python 2.5 or higher.

## Installing for Python 3

As of version 0.9.5, Fudge supports Python 3. Just install distribute and type:

    $ python3.x setup.py install

This step will convert the Fudge source code using the 2to3 tool.

## Source

The Fudge source can be downloaded as a tar.gz file from http://pypi.python.org/pypi/fudge

Using Git you can clone the source from https://github.com/fudge-py/fudge/

Fudge is free and open for usage under the MIT license.

## Contents

- Using Fudge
  - Fudging A Web Service
  - A Simple Test Case
  - Fake objects without patches (dependency injection)
  - Stubs Without Expectations
  - Replacing A Method
  - Cascading Objects
  - Multiple Return Values
  - Expecting A Specific Call Order
  - Allowing any call or attribute (a complete stub)
  - Working with Arguments
- Fudge For JavaScript
  - Install
  - Usage
- Why Another Mock Framework?
- Migrating from Fudge 0.9 to 1.0
  - The new @patch and @test decorators
  - Expectations that were declared in setup

## API Reference

- fudge
  - `patch()`
  - `test()`
  - `Fake`
    - `Fake.calls()`
    - `Fake.expects()`
    - `Fake.expects_call()`
    - `Fake.has_attr()`
    - `Fake.has_property()`
    - `Fake.is_a_stub()`
    - `Fake.is_callable()`
    - `Fake.next_call()`
    - `Fake.provides()`
    - `Fake.raises()`
    - `Fake.remember_order()`
    - `Fake.returns()`
    - `Fake.returns_fake()`
    - `Fake.times_called()`
    - `Fake.with_arg_count()`
    - `Fake.with_args()`
    - `Fake.with_kwarg_count()`
    - `Fake.with_matching_args()`
    - `Fake.without_args()`
  - `clear_calls()`
  - `verify()`
  - `with_fakes()`
  - `FakeDeclarationError`
- fudge.inspector
  - `ValueInspector`
    - `ValueInspector.any()`
    - `ValueInspector.any_value()`
    - `ValueInspector.contains()`
    - `ValueInspector.endswith()`
    - `ValueInspector.has_attr()`
    - `ValueInspector.isinstance()`
    - `ValueInspector.passes_test()`
    - `ValueInspector.startswith()`
  - `NotValueInspector`
    - `NotValueInspector.__call__()`
- fudge.patcher
  - `with_patched_object()`
  - `patched_context()`
  - `patch_object()`
  - `PatchHandler`
    - `PatchHandler.patch()`
    - `PatchHandler.restore()`

## Contributing

Please submit bugs and patches, preferably with tests. All contributors will be acknowledged. Thanks!

## Credits

Fudge was created by Kumar McMillan and contains contributions by Cristian Esquivias, Michael Williamson, Luis Fagundes and Jeremy Satterfield.

## Changelog

- 1.1.1

  - Fixes error when providing tuple or list to arg.isinstance

- 1.1.0

  - Changed moved to github and added maintainers

  - Changed remove support for python 3.1 and 3.2 in tests in lieu of 3.4

  - added `fudge.Fake.has_property()`

  - added `IsInstance`

  - added `without_args()`

  - Deprecation warnings are now real warnings.

- 1.0.3

  - Added `fudge.Fake.is_a_stub()` documented here

  - `arg.any_value()` is DEPRECATED in favor of `arg.any()`

  - Attributes declared by `fudge.Fake.has_attr()` are now settable. Thanks to Mike Kent for the bug report.

  - Fixes ImportError when patching certain class methods like smtplib.SMTP.sendmail

  - Fixes representation of chained fakes for class instances.

- 1.0.2

  - Object patching is a lot safer in many cases and now supports getter objects and static methods. Thanks to Michael Foord and mock._patch for ideas and code.

- 1.0.1

  - Fixed ImportError when a patched path traverses object attributes within a module.

- 1.0.0

  - After extensive usage and community input, the fudge interface has been greatly simplified!

  - There is now a way better pattern for setting up fakes. The old way is still supported but you’ll want to write all new code in this pattern once you see how much easier it is.

  - Added `fudge.patch()` and `fudge.test()`

  - Added `fudge.Fake.expects_call()` and `fudge.Fake.is_callable()`

  - Changed: The tests are no longer maintained in Python 2.4 although Fudge probably still supports 2.4

- 0.9.6

  - Added support to patch builtin modules. Thanks to Luis Fagundes for the patch.

- 0.9.5

  - Changed: multiple calls to `fudge.Fake.expects()` behave just like `fudge.Fake.next_call()`. The same goes for `fudge.Fake.provides()`. You probably won’t need to update any old code for this change, it’s just a convenience.

  - Added `fudge.Fake.with_matching_args()` so that expected arguments can be declared more loosely

  - Added support for Python 3

  - Improved support for Jython

- 0.9.4

  - Fixed bug where __init__ would always return the Fake instance of itself. Now you can return a custom object if you want.

- 0.9.3

  - Added `with_args()` to JavaScript Fudge.

  - Fixed bug where argument values that overloaded __eq__ might cause declared expectations to fail (patch from Michael Williamson, Issue 9)

  - Fixed bug where `fudge.Fake.raises()` obscured `fudge.Fake.with_args()` (Issue 6)

  - Fixed `returns_fake()` in JavaScript Fudge.

- 0.9.2

  - Changed: values in failed comparisons are no longer shortened when too long.

  - Changed: `fudge.Fake.calls()` no longer trumps expectations (i.e. `fudge.Fake.with_args()`)

  - Changed: `fudge.Fake.with_args()` is more strict. You will now see an error when arguments are not expected yet keyword arguments were expected and vice versa. This was technically a bug but is listed under changes in case you need to update your code. Note that you can work with arguments more expressively using the new `fudge.inspector` functions.

  - Added `fudge.inspector` for Working with Arguments.

  - Added `fudge.Fake.remember_order()` so that order of expected calls can be verified.

  - Added `fudge.Fake.raises()` for simulating exceptions

  - Added keyword `fudge.Fake.next_call(for_method="other_call")` so that arbitrary methods can be modified (not just the last one).

  - Fixed: error is raised if you declare multiple `fudge.Fake.provides()` for the same Fake. This also applies to `fudge.Fake.expects()`

  - Fixed bug where `fudge.Fake.returns()` did not work if you had replaced a call with `fudge.Fake.calls()`

  - Fixed bug in `fudge.Fake.next_call()` so that this now works: `Fake(callable=True).next_call().returns(...)`

  - Fixed: Improved Python 2.4 compatibility.

  - Fixed bug where `from fudge import *` did not import proper objects.

- 0.9.1

  - DEPRECATED fudge.start() in favor of `fudge.clear_calls()`

  - DEPRECATED fudge.stop() in favor of `fudge.verify()`

  - Added context manager `fudge.patcher.patched_context()` so the with statement can be used for patching (contributed by Cristian Esquivias)

  - Added `fudge.Fake.times_called()` to expect a certain call count (contributed by Cristian Esquivias)

  - Added `Fake(expect_call=True)` to indicate an expected callable. Unlike `Fake(callable=True)` the former will raise an error if not called.

- 0.9.0

  - first release