Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

A mocking framework for Python

Project description

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.

Installation

$ pip install funk

Example

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)
    ...

Usage

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")

Setting expectations

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:

allows(file_storage).names

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:

allows(file_storage).names(token="<token 1>")

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.

Actions

By default, a mocked method returns None. Use returns() to return a different value:

allows(file_storage).names().returns([])

Use raises() to raise an exception:

allows(file_storage).names().raises(Exception("Could not connect"))

Sequences

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)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for Funk, version 0.5.0
Filename, size File type Python version Upload date Hashes
Filename, size Funk-0.5.0-py2.py3-none-any.whl (10.8 kB) File type Wheel Python version 2.7 Upload date Hashes View
Filename, size Funk-0.5.0.tar.gz (22.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page