alex/pretend

A library for stubbing in python

pretend

Pretend is a library to make stubbing with Python easier.

What is stubbing?

Stubbing is a technique for writing tests. You may hear the term mixed up with mocks, fakes, or doubles. Basically a stub is an object that returns pre-canned responses, rather than doing any computation.

Martin Fowler does a good job explaining the terms in his Mocks Aren't Stubs article.

How do I install pretend?

It's easy with pip!

$ pip install pretend

How do I use pretend?

It's easy, the stub function makes it easy to create a stub:

>>> from pretend import stub
>>> x = stub(country_code="US")
>>> some_function(x)

Here x will be an object with a single attribute country_code which has the value "US". Unlike mocks, x will not respond to any other attribute or methods, nor does it have any methods for making assertions about what you accessed.

If you want to add a method to the stub, simply provide a function to it:

>>> from pretend import stub
>>> x = stub(country_code=lambda: "US")
>>> x.country_code()
'US'

It's important to note that functions on stubs do not take a self argument, this is because stubs should be returning pre-canned values, not doing computations.

Exceptions with pretend

Sometimes a method you want to stub doesn't return a value, but instead raises an exception. To make this easy, pretend provides a helper function, raiser, it can be used like so:

>>> from pretend import stub, raiser
>>> x = stub(func=raiser(ValueError))
>>> x.func()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pretend.py", line 74, in inner
    raise exc
ValueError

Why is stubbing better?

Ideally stubbing tests how your system responds to a particular input, rather than which API is used. Stubbing still requires you to write tests that check the results of a computation, rather than looking for side effects. This doesn't always work though, so you do sometimes still need mocking (e.g. sometimes you really want to check for a side effect.)

How do I get my stub into place?

If you come from other mocking libraries you're probably used to a patch method to put a mock in place. pretend doesn't include anything like this, a) we believe it's better, where possible, to pass stubs as arguments rather than monkey patch them into place, b) we believe that when you do need to monkey patch something into place you should use something provided by your testing tool. py.test includes such a tool.

What if I really need to record the calls?

If you really really need to, pretend includes a call_recorder utility:

>>> from pretend import call_recorder, call
>>> f = call_recorder(lambda a: a + 2)
>>> f(3)
5
>>> assert f.calls == [call(3)]

Who wrote this?

pretend is by Alex Gaynor, who was just tired of not having a good stubbing tool for Python. The name is from Idan Gazit.

pretend's Issues

Calls with missing dunder methods have teh wrong semantics

x = stub()
x + 2

will raise a KeyError instead of a TypeError

__repr__/__str__ for stub objects

It's not very convenient to debug stub objects in tests. I mean

AssertionError: Lists differ: [[<pretend.stub object at 0x37... != [[<pretend.stub object at 0x37...

First differing element 1:
[<pretend.stub object at 0x379cb90>, <pretend.stub object at 0x379cb50>]
[<pretend.stub object at 0x379cb50>, <pretend.stub object at 0x379cb90>]

Maybe we should add some special argument, which will be interpreted as return value of repr/str functions?
Something like

User = stub
user1, user2 = User(__str='User @l0kix2'), User(__str='User @alex')

So in traceback in test we will see

First differing element 1:
['User @l0kix2', 'User @alex']
['User @alex', 'User @l0kix2']

I can try to make a pull-request, if this idea is ok.

Add support for raising Exceptions

Since lambdas don’t allow raising of Exceptions, I have currently to write a helper function that just raises its argument. It would be great if pretend supported this out-of-the-box somehow.

Bonus points if it’d work on descriptors too.

New Release?

The repository has some nice features (callable stubs) that aren't in the current PyPI release.

Is there anything I can to to help bring a 1.0.9 or 1.1 release to fruition?

Add a pretend.ANY

So with the call recorder it's often a useful thing to be able to make a parameter that matches anything. Perhaps it's a current timestamp or a random value, whatever it is you don't know what it is.

Mock has mock.ANY and I'm finding myself installing mock just for mock.ANY.

Some magic methods are missing

Examples include: __getitem__, __enter__, __exit__.