The 90% use case is that want to stub out a side effect. This is also known as (monkey-)patching. With mockito, it's:
from mockito import when
# stub `os.path.exists`
when(os.path).exists('/foo').thenReturn(True)
os.path.exists('/foo') # => True
os.path.exists('/bar') # -> throws unexpected invocation
So in difference to traditional patching, in mockito you always specify concrete arguments (a call signature), and its outcome, usually a return value via thenReturn or a raised exception via thenRaise. That effectively turns function calls into constants for the time of the test.
There are of course reasons when you don't want to overspecify specific tests. You just want the desired stub answer. Here we go:
when(os.path).exists(...).thenReturn(True)
# now, obviously, you get the same answer, regardless of the arguments
os.path.exists('FooBar') # => True
os.path.exists('BarFoo') # => True
You can combine both stubs. E.g. nothing exists, except one file:
when(os.path).exists(...).thenReturn(False)
when(os.path).exists('.flake8').thenReturn(True)
And because it's a similar pattern, we can introduce :func:`spy2` here. Spies call through the original implementation of a given function. E.g. everything is as it is, except '.flake8' is just not there:
from mockito import spy2
spy2(os.path.exists)
when(os.path).exists('.flake8').thenReturn(False)
Another way to write the same thing is:
when(os.path).exists(...).thenCallOriginalImplementation()
when(os.path).exists('.flake8').thenReturn(False)
And actually spy2 uses thenCallOriginalImplementation under the hood. Why spying at all: either you want the implementation almost intact as above or you need the implementation to stay intact but want to verify its usage. E.g.:
spy2(os.path.exists)
# now do some stuff
do_stuff()
# then verify the we asked for the cache exactly once
verify(os.path, times=1).exists("cache/.foo")
When patching, you MUST not forget to :func:`unstub` of course! You can do this explicitly
from mockito import unstub unstub() # restore os.path module
Usually you do this unconditionally in your teardown function. If you're using pytest, you could define a fixture instead
# conftest.py
import pytest
@pytest.fixture
def unstub():
from mockito import unstub
yield
unstub()
# my_test.py
import pytest
pytestmark = pytest.mark.usefixtures("unstub")
But very often you just use context managers (aka with), and mockito will unstub on 'exit' automatically:
# E.g. test that `exists` gets never called
with expect(os.path, times=0).exists('.flake8'):
# within the block `os.path.exists` is patched
cached_dir_lookup('.flake8')
# at the end of the block `os.path` gets unpatched
# Which is btw roughly the same as doing
with when(os.path).exists('.flake8'):
cached_dir_lookup('.flake8')
verify(os.path, times=0).exists(...)
Now let's mix global module patching with mocks. We want to test the following function using the fab requests library:
import requests
def get_text(url):
res = requests.get(url)
if 200 <= res.status_code < 300:
return res.text
return None
How, dare, we did not inject our dependencies! Obviously we can get over that by patching at the module level like before:
when(requests).get('https://example.com/api').thenReturn(...)
But what should we return? We know it's a requests.Response object, (Actually I know this bc I typed this in the ipython REPL first.) But how to construct such a Response, its __init__ doesn't even take any arguments?
Should we actually use a 'real' response object? No, we fake it using :func:`mock`.
# setup
response = mock({
'status_code': 200,
'text': 'Ok'
}, spec=requests.Response)
when(requests).get('https://example.com/api').thenReturn(response)
# run
assert get_text('https://example.com/api') == 'Ok'
# done!
Say you want to mock the class Dog:
class Dog(object):
def bark(self):
return 'Wuff'
# either mock the class
when(Dog).bark().thenReturn('Miau!')
# now all instances have a different behavior
rex = Dog()
assert rex.bark() == 'Miau!'
# or mock a concrete instance
when(rex).bark().thenReturn('Grrrr')
assert rex.bark() == 'Grrrr'
# a different dog will still 'Miau!'
assert Dog().bark() == 'Miau!'
# be sure to call unstub() once in while
unstub()
Sure, you can verify your interactions:
from mockito import verify
# once again
rex = Dog()
when(rex).bark().thenReturn('Grrrr')
rex.bark()
rex.bark()
# `times` defaults to 1
verify(rex, times=2).bark()
In general mockito is very picky:
# this will fail because `Dog` has no method named `waggle`
when(rex).waggle().thenReturn('Nope')
# this will fail because `bark` does not take any arguments
when(rex).bark('Grrr').thenReturn('Nope')
# given this function
def bark(sound, post='!'):
return sound + post
from mockito import kwargs
when(main).bark('Grrr', **kwargs).thenReturn('Nope')
# now this one will fail
bark('Grrr') # because there are no keyword arguments used
# this one will fail because `then` does not match the function signature
bark('Grrr', then='!!')
# this one will go
bark('Grrr', post='?')
# there is also an args matcher
def add_tasks(*tasks, verbose=False):
pass
from mockito import args
# If you omit the `thenReturn` it will just return `None`
when(main).add_tasks(*args)
add_tasks('task1', 'task2') # will go
add_tasks() # will fail
add_tasks('task1', verbose=True) # will fail too
# On Python 3 you can also use `...`
when(main).add_tasks(...)
# when(main).add_tasks(Ellipsis) on Python 2
add_tasks('task1') # will go
add_tasks(verbose=True) # will go
add_tasks('task1', verbose=True) # will go
add_tasks() # will go
To start with an empty stub use :func:`mock`:
from mockito import mock
obj = mock()
# pass it around, eventually it will be used
obj.say('Hi')
# back in the tests, verify the interactions
verify(obj).say('Hi')
# by default all invoked methods take any arguments and return None
# you can configure your expected method calls with the usual `when`
when(obj).say('Hi').thenReturn('Ho')
# There is also a shortcut to set some attributes
obj = mock({
'hi': 'ho'
})
assert obj.hi == 'ho'
# This would work for methods as well; in this case
obj = mock({
'say': lambda _: 'Ho'
})
# But you don't have any argument and signature matching
assert obj.say('Anything') == 'Ho'
# At least you can verify your calls
verify(obj).say(...)
# Btw, you can make screaming strict mocks::
obj = mock(strict=True) # every unconfigured, unexpected call will raise
You can use an empty stub specced against a concrete class:
# Given the above `Dog`
rex = mock(Dog)
# Now you can stub out any known method on `Dog` but other will throw
when(rex).bark().thenReturn('Miau')
# this one will fail
when(rex).waggle()
# These mocks are in general very strict, so even this will fail
rex.health # unconfigured attribute
# Of course you can just set it in a setup routine
rex.health = 121
# Or again preconfigure
rex = mock({'health': 121}, spec=Dog)
# preconfigure stubbed method
rex = mock({'bark': lambda sound: 'Miau'}, spec=Dog)
# as you specced the mock, you get at least function signature matching
# `bark` does not take any arguments so
rex.bark('sound') # will throw TypeError
# Btw, you can make loose specced mocks::
rex = mock(Dog, strict=False)