tdubs 0.2.0

Example

from unittest import TestCase

from tdubs import Stub, Mock, calling, verify


# The thing I want to test:
class Greeter(object):

    # tdubs works best with code that has injectable dependencies:
    def __init__(self, prompter=None, printer=None):
        self.prompter = prompter or input
        self.printer = printer or print

    def greet(self, greeting):
        fname = self.prompter('First name:')
        lname = self.prompter('Last name:')
        self.printer('%s, %s %s!' % (greeting, fname, lname))


class TestGreeter(TestCase):
    def setUp(self):
        # use stubs to provide canned responses to queries:
        prompter = Stub()
        calling(prompter).passing('First name:').returns('Justin')
        calling(prompter).passing('Last name:').returns('Blake')

        # use mocks to verify commands:
        self.printer = Mock()

        self.greeter = Greeter(prompter, self.printer)

    def test_prints_greeting_to_full_name(self):
        self.greeter.greet('Greetings')
        verify(self.printer).called_with('Greetings, Justin Blake!')

Usage

>>> from tdubs import Stub
>>> my_stub = Stub('my_stub')

>>> my_stub.some_attribute
<Stub name='some_attribute' ...>

>>> my_stub.some_attribute = 'some value'
>>> my_stub.some_attribute
'some value'

>>> my_stub = Stub('my_stub', predefined_attribute='predefined value')
>>> my_stub.predefined_attribute
'predefined value'

>>> my_stub['some_key']
<Stub name='some_key' ...>
>>> my_stub['some_key'] = 'some dict value'
>>> my_stub['some_key']
'some dict value'

>>> my_stub['another_key'].foo = 'foo'
>>> my_stub['another_key'].foo
'foo'

>>> my_stub()
Traceback (most recent call last):
    ...
TypeError: <Stub name='my_stub' ...> is not callable ...

>>> from tdubs import calling
>>> calling(my_stub).returns('some return value')
>>> my_stub()
'some return value'

>>> calling(my_stub.some_method).returns('some method result')
>>> my_stub.some_method()
'some method result'

>>> calling(my_stub).passing('some argument').returns('specific value')
>>> my_stub('some argument')
'specific value'

>>> my_stub()
'some return value'

>>> calling(my_stub.kaboom).raises(Exception('Kaboom!'))
>>> my_stub.kaboom()
Traceback (most recent call last):
    ...
Exception: Kaboom!

>>> from tdubs import Mock
>>> my_mock = Mock('my_mock')

>>> my_mock()
<Mock ...>
>>> my_mock('arg1', 'arg2', foo='bar')
<Mock ...>

>>> from tdubs import calls
>>> calls(my_mock)
[<Call args=() kwargs={}>, <Call args=('arg1', 'arg2') kwargs={'foo': 'bar'}>]

>>> from tdubs import verify
>>> verify(my_mock).called()
True

>>> new_mock = Mock('new_mock')
>>> verify(new_mock).called()
Traceback (most recent call last):
    ...
VerificationError: expected <Mock ...> to be called, but it wasn't

>>> verify(my_mock).called_with('arg1', 'arg2', foo='bar')
True
>>> verify(my_mock).called_with('foo')
Traceback (most recent call last):
    ...
VerificationError: expected <Mock ...> to be called with ('foo'), ...

>>> verify(new_mock).not_called()
True
>>> new_mock()
<Mock ...>
>>> verify(new_mock).not_called()
Traceback (most recent call last):
    ...
VerificationError: expected <Mock ...> to not be called, but it was

>>> verify(new_mock).not_called_with('foo')
True
>>> new_mock('foo')
<Mock ...>
>>> verify(new_mock).not_called_with('foo')
Traceback (most recent call last):
    ...
VerificationError: expected <Mock ...> to not be called with (...), ...

Stubs vs. Mocks

You should use Stub when you are testing behavior that depends on the state or return value of some other object. For example, the behavior of the Greeter in the Example above depends on the return value of prompter, so I’m using a stub.

Stubs are not callable by default. You must explicitly stub a return value if you expect it to be called. This is to avoid false positives in your tests for behavior that may depend on the truthiness of that call.

Mocks are callable by default, because they are designed to record calls for verification after execution. You should use Mock when you only need to verify that something was called. For example, I need to verify whether or not printer was called with the correct string, so I’m using a mock.

You can think of it this way: use Stub for queries, and Mock for commands. If the separation isn’t clear, spend some time thinking about your design. Would it be better with distinct queries and commands? (If you really need both, use Mock, since it extends Stub).

Further reading:

• Mocks aren’t Stubs

• The Little Mocker

• Mock Roles, not Objects

Patching Imports

I personally try to avoid doing this, but if you really want to, you could use python’s patch and specify you would like a tdubs double instead of the default unittest.mock.MagicMock by passing the using option to patch like this: patch('path.to.object', new=Stub('my tdubs stub')). For example:

>>> def yell_a_file(path):
...     try:
...         handle = open(path, 'r')
...         contents = handle.read()
...     finally:
...         handle.close()
...     return contents.upper()
...
>>> try:
...     from unittest.mock import patch
... except ImportError:
...     from mock import patch
...
>>> with patch('%s.open' % __name__, new=Stub('open')) as stubbed_open:
...     handle = Mock('handle')
...     calling(stubbed_open).passing('my_file.txt', 'r').returns(handle)
...     calling(handle.read).returns('file contents')
...     assert yell_a_file('my_file.txt') == 'FILE CONTENTS'
...     verify(handle.close).called()
True

Why?

Python 3 already has unittest.mock, and there are several other third-party test double packages, but none felt like the right fit for how I like to TDD.

This is what I wanted out of a test double library:

1. The ability to treat a double as a callable with return values specific to the arguments passed in. This is so I can treat stubs as pure stubs, without needing to verify I passed the right arguments to my query methods. You can see that in action in the example above.

2. The ability to verify calls after they are made, without setting up expectations first. This is so my tests read like a story:

   # set up:
   my_mock = Mock()
   
   # execute:
   my_func(my_mock)
   
   # verify:
   verify(my_mock).called()

3. Test doubles with zero public attributes from the library. This is to avoid conflicts with the object being replaced in tests. For example:

   Since all attributes on a mock return a new mock, the following assertion will always evaluate to True:

   >>> try:
   ...     from unittest import mock
   ... except ImportError:
   ...     import mock
   ...
   >>> mock.Mock().asssert_called_with('foo')  # oops!
   <Mock ...>

   Notice the typo? If not, you may get a false positive in your test.

   tdubs avoids this by using a new object for verifications:

   >>> from tdubs import Mock, verify
   >>> verify(Mock()).callled_with('foo')  # oops!
   Traceback (most recent call last):
        ...
   AttributeError: 'Verification' object has no attribute 'callled_with'

   Notice the typo? If not, it doesn’t matter. Python noticed!

I also like the distinction between stubs and mocks (see Stubs vs. Mocks), but it’s not one of the reasons I originally decided to write tdubs.

Installation

pip install tdubs

Development

Clone the project.

Install dev dependencies:

pip install -r requirements.txt

Run the tests:

nosetests

Lint and test the code automatically when changes are made (see tube.py):

stir