Using Fudge¶

Fudging A Web Service¶

When testing code that uses a web service you probably want a fast set of tests that don’t depend on an actual web service on the Internet. This is a good scenario in which to use mock objects. Say you have a Twitter bot that looks something like this:

>>> import oauthtwitter
>>> def post_msg_to_twitter(msg):
...     api = oauthtwitter.OAuthApi(
...         '<consumer_key>', '<consumer_secret>',
...         '<oauth_token>', '<oauth_token_secret>'
...     )
...     api.UpdateStatus(msg)
...     print "Sent: %s" % msg
>>>

Since the oauthtwitter module is maintained independently, your code should work as long as it calls the right methods.

A Simple Test Case¶

You can use Fudge to replace the OAuthApi class with a fake and declare an expectation of how it should be used:

>>> import fudge
>>> @fudge.patch('oauthtwitter.OAuthApi')
... def test(FakeOAuthApi):
...     (FakeOAuthApi.expects_call()
...                  .with_args('<consumer_key>', '<consumer_secret>',
...                             '<oauth_token>', '<oauth_token_secret>')
...                  .returns_fake()
...                  .expects('UpdateStatus').with_arg_count(1))
...
...     post_msg_to_twitter("hey there fellow testing freaks!")
>>>

Let’s break this down:

The patch decorator will temporarily patch in a fake object for the duration of the test and expose it as an argument to the test. This allows you to add expectations or stubs.
The fake object you see here expects a call (class instantiation) with four arguments having specific string values. The returned value is an object instance (a new fake) that expects you to call fake_oauth.UpdateStatus() with one argument.
Finally, post_msg_to_twitter() is called.

Let’s run the test!

>>> test()
Sent: hey there fellow testing freaks!

Sweet, it passed.

Fudge lets you declare expectations as loose or as tight as you want. If you don’t care about the exact arguments, you can leave off the call to fudge.Fake.with_args(). If you don’t care if a method is actually called you can use fudge.Fake.provides() instead of fudge.Fake.expects(). Likewise, fudge.Fake.with_arg_count() can be used when you don’t want to worry about the actual argument values. There are argument inspectors for checking values in other ways.

Fake objects without patches (dependency injection)¶

If you don’t need to patch anything, you can use the fudge.test() decorator instead. This will ensure an exception is raised in case any expectations aren’t met. Here’s an example:

>>> def send_msg(api):
...     if False: # a mistake
...         api.UpdateStatus('hello')
...
>>> @fudge.test
... def test_msg():
...     FakeOAuthApi = (fudge.Fake('OAuthApi')
...                          .is_callable()
...                          .expects('UpdateStatus'))
...     api = FakeOAuthApi()
...     send_msg(api)
...
>>> test_msg()
Traceback (most recent call last):
...
AssertionError: fake:OAuthApi.UpdateStatus() was not called

Stubs Without Expectations¶

If you want a fake object where the methods can be called but are not expected to be called, the code is just the same but instead of Fake.expects() you use Fake.provides(). Here is an example of always returning True for the method is_logged_in():

>>> def show_secret_word():
...     import auth
...     user = auth.current_user()
...     if user.is_logged_in():
...         print "Bird is the word"
...     else:
...         print "Access denied"
...
>>> @fudge.patch('auth.current_user')
... def test_secret_word(current_user):
...     user = current_user.expects_call().returns_fake()
...     user = user.provides('is_logged_in').returns(True)
...     show_secret_word()
...
>>> test_secret_word()
Bird is the word

Note that if user.is_logged_in() is not called then no error will be raised because it’s provided, not expected:

Replacing A Method¶

Sometimes returning a static value isn’t good enough, you actually need to run some code. You can do this using Fake.calls() like this:

>>> auth = fudge.Fake()
>>> def check_user(username):
...     if username=='bert':
...         print "Bird is the word"
...     else:
...         print "Access denied"
...
>>> auth = auth.provides('show_secret_word_for_user').calls(check_user)
>>> # Now, the check_user function gets called instead:
>>> auth.show_secret_word_for_user("bert")
Bird is the word
>>> auth.show_secret_word_for_user("ernie")
Access denied

Cascading Objects¶

Some objects you might want to work with will spawn a long chain of objects. Here is an example of fudging a cascading SQLAlchemy query. Notice that Fake.returns_fake() is used to specify that session.query(User) should return a new object. Notice also that because query() should be iterable, it is set to return a list of fake User objects.

>>> import fudge
>>> session = fudge.Fake('session')
>>> query = (session.provides('query')
...                 .returns_fake()
...                 .provides('order_by')
...                 .returns(
...                     [fudge.Fake('User').has_attr(name='Al', lastname='Capone')]
...                 )
... )
>>> from models import User
>>> for instance in session.query(User).order_by(User.id):
...     print instance.name, instance.lastname
...
Al Capone

Multiple Return Values¶

Let’s say you want to test code that needs to call a function multiple times and get back multiple values. Up until now, you’ve just seen the Fake.returns() method which will return a value infinitely. To change that, call Fake.next_call() to advance the call sequence. Here is an example using a shopping cart scenario:

>>> cart = (fudge.Fake('cart')
...              .provides('add')
...              .with_args('book')
...              .returns({'contents': ['book']})
...              .next_call()
...              .with_args('dvd')
...              .returns({'contents': ['book', 'dvd']}))
>>> cart.add('book')
{'contents': ['book']}
>>> cart.add('dvd')
{'contents': ['book', 'dvd']}
>>> cart.add('monkey')
Traceback (most recent call last):
...
AssertionError: This attribute of fake:cart can only be called 2 time(s).

Expecting A Specific Call Order¶

You may need to test an object that expects its methods to be called in a specific order. Just preface any calls to fudge.Fake.expects() with fudge.Fake.remember_order() like this:

>>> import fudge
>>> session = (fudge.Fake("session").remember_order()
...                                 .expects("get_count").returns(0)
...                                 .expects("set_count").with_args(5)
...                                 .expects("get_count").returns(5))
...
>>> session.get_count()
0
>>> session.set_count(5)
>>> session.get_count()
5
>>> fudge.verify()

A descriptive error is printed if you call things out of order:

>>> session.set_count(5)
Traceback (most recent call last):
...
AssertionError: Call #1 was fake:session.set_count(5); Expected: #1 fake:session.get_count()[0], #2 fake:session.set_count(5), #3 fake:session.get_count()[1], end

Allowing any call or attribute (a complete stub)¶

If you need an object that lazily provides any call or any attribute then you can declare fudge.Fake.is_a_stub(). Any requested method or attribute will always return a new fudge.Fake instance making it easier to work complex objects. Here is an example:

>>> Server = fudge.Fake('xmlrpclib.Server').is_a_stub()
>>> pypi = Server('http://pypi.python.org/pypi')
>>> pypi.list_packages()
fake:xmlrpclib.Server().list_packages()
>>> pypi.package_releases()
fake:xmlrpclib.Server().package_releases()

Stubs like this carry on infinitely:

>>> f = fudge.Fake('base').is_a_stub()
>>> f.one.two.three().four
fake:base.one.two.three().four

Note

When using fudge.Fake.is_a_stub() you can’t lazily access any attributes or methods if they have the same name as a Fake method, like returns() or with_args(). You would need to declare expectations for those directly using fudge.expects(), etc.

Working with Arguments¶

The fudge.Fake.with_args() method optionally allows you to declare expectations of how arguments should be sent to your object. It’s usually sufficient to expect an exact argument value but sometimes you need to use fudge.inspector functions for dynamic values.

Here is a short example:

>>> import fudge
>>> from fudge.inspector import arg
>>> image = (fudge.Fake("image")
...               .expects("save")
...               .with_args("JPEG", arg.endswith(".jpg"), resolution=arg.any())
... )

This declaration is very flexible; it allows the following calls:

>>> image.save("JPEG", "/tmp/unicorns-and-rainbows.jpg", resolution=72)
>>> image.save("JPEG", "/tmp/me-being-serious.jpg", resolution=96)

The Fake class also provides a without_args method, which functions just the opposite. With it, you can declare arguments that you expect NOT to be provided.

>>> image = (fudge.Fake('image')
...               .expects('save')
...               .without_args('GIF', filename=arg.endswith('.gif')))

This expectation will pass for any call that does not provide the string 'GIF' as a positional argument and does not provide a filename keyword argument that ends in '.gif'

>>> image.save('JPEG', filename="funny_cat6.jpg")
>>> image.save('total nonsense', {'fizz': 'buzz'})

There also inverted version of all the fudge.inspector.arg methods, available on the fudge.inspector.arg_not object. The methods all have the same name, but assert the opposite of the arg versions. See the docstrings for the various fudge.inspector.arg methods for examples of their usage.

fudge.inspector.arg_not can also be called on an object to match anything except that object.

That’s it! See the fudge API for details:

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¶

Table of Contents

Previous topic

Next topic

This Page