A mocking framework for Python
Funk is a mocking framework for Python, influenced heavily by JMock. Funk helps to test modules in isolation by allowing mock objects to be used in place of “real” objects. Funk is licensed under the 2-clause BSD licence.
$ pip install funk
Suppose we have an API for a file storage service. We want to list the names of all files, but the API limits the number of names it will return at a time. Therefore, we need to write some code that will keep making requests to the API until all names have been retrieved.
def fetch_names(file_storage): has_more = True token = None names =  while has_more: response = file_storage.names(token=token) names += response.names token = response.next_token has_more = token is not None return names import funk @funk.with_mocks def test_request_for_names_until_all_names_are_fetched(mocks): file_storage = mocks.mock(FileStorage) mocks.allows(file_storage).names(token=None).returns(mocks.data( next_token="<token 1>", names=["a", "b"], )) mocks.allows(file_storage).names(token="<token 1>").returns(mocks.data( next_token="<token 2>", names=["c", "d"], )) mocks.allows(file_storage).names(token="<token 2>").returns(mocks.data( next_token=None, names=["e"], )) assert fetch_names(file_storage) == ["a", "b", "c", "d", "e"]
By using a mock object instead of a real instance of FileStorage, we can run our tests without a running instance of the file storage system. We also avoid relying on the implementation of FileStorage, making our tests more focused and less brittle.
If you’re using pytest, the easiest way to use Funk is as a fixture:
import funk import pytest @pytest.yield_fixture def mocks(): mocks = funk.Mocks() yield mocks mocks.verify() def test_request_for_names_until_all_names_are_fetched(mocks): file_storage = mocks.mock(FileStorage) ...
Creating a mock context
Create an instance of Mocks to allow mock objects to be created. Call Mocks.verify() to assert that all expectations have been met.
import funk def test_case(): mocks = funk.Mocks() ... mocks.verify()
Use the decorator funk.with_mocks to inject a mocks argument to a function. verify() will be automatically invoked at the end of the function.
import funk @funk.with_mocks def test_case(mocks): ...
If using pytest, a fixture is the simplest way to use Funk:
import funk import pytest @pytest.yield_fixture def mocks(): mocks = funk.Mocks() yield mocks mocks.verify() def test_case(mocks): ...
Creating mock objects
Call Mocks.mock() to create a mock object.
file_storage = mocks.mock()
If the base argument is passed, only methods on that type can be mocked:
file_storage = mocks.mock(FileStorage)
This can be useful to ensure that only existing methods are mocked, but should be avoided if generating methods dynamically, such as by using __getattr__.
Set the name argument to set the name that should be used in assertion failure messages for the mock:
file_storage = mocks.mock(name="file_storage")
To set up an expectation, use funk.allows() or funk.expects(). For convenience, these functions are also available on Mocks. funk.allows() will let the method be called any number of times, including none. funk.expects() will ensure that the method is called exactly once. For instance:
This allows the method file_storage.names to be called with any arguments any number of times. To only allow calls with specific arguments, you can invoke .names as a method:
This will only allow calls with a matching token keyword argument, and no other arguments.
You can also use matchers from Precisely to match arguments:
from precisely import instance_of allows(file_storage).names(token=instance_of(str))
If more than one expectation is set up on the same method, the first matching expectation is used. If you need to enforce methods being called in a particular order, use sequences.
By default, a mocked method returns None. Use returns() to return a different value:
Use raises() to raise an exception:
allows(file_storage).names().raises(Exception("Could not connect"))
A sequence object can be created using Mocks.sequence. The sequencing on objects can then be defined using in_sequence(sequence) when setting expectations. For instance:
file_storage = mocks.mock(FileStorage) file_ordering = mocks.sequence() expects(file_storage).save(NAME_1, CONTENTS_1).in_sequence(file_ordering) expects(file_storage).save(NAME_2, CONTENTS_2).in_sequence(file_ordering)
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.