ollipa / chainmock

Mocking library for Python

Chainmock - Mocking library for Python and Pytest.

---

Documentation

---

Chainmock is a mocking Library for Python and pytest. Under the hood it uses Python standard library mocks providing an alternative syntax to create mocks and assertions. Chainmock also comes with some additional features to make testing faster and more straightforward. The syntax works especially well with pytest fixtures.

Installation

Install with pip:

pip install chainmock

Features

Chainmock supports all the same features that Python standard library unittest mocks support and adds some convenient extra functionality.

• Mocking: Create mocks and assert call counts and arguments or replace return values.
• Spying: Spying proxies the calls to the original function or method. With spying you can assert call counts and arguments without mocking.
• Stubs: Easily create stub objects that can be used in tests as fake data or to replace real objects.
• Async support: Chainmock supports mocking and spying async functions and methods. Most of the time it also recognizes automatically when async mocking should be used so it is not any harder than mocking sync code.
• Fully type annotated: The whole codebase is fully type annotated so Chainmock works well with static analysis tools and editor autocomplete.
• Works with Python 3.8+ and PyPy3.
• Supports pytest, unittest, and doctest test runners.

Examples

The entrypoint to Chainmock is the mocker function. Import the mocker function as follows:

from chainmock import mocker

Mocking

To mock you just give the object that you want to mock to the mocker function. After this you can start mocking individual attributes and methods as follows:

# Assert that a certain method has been called exactly once
mocker(Teapot).mock("add_tea").called_once()

# Provide a return value and assert that method has been called twice
mocker(Teapot).mock("brew").return_value("mocked").called_twice()

# Assert that a method has been called with specific arguments at most twice
mocker(Teapot).mock("add_tea").all_calls_with("green").call_count_at_most(2)

Spying

Spying is not any harder than mocking. You just need to call the spy method instead of the mock method. After spying a callable, it works just like before spying and you can start making assertions on it.

# Assert that a certain method has been called at least once
mocker(Teapot).spy("add_tea").called()

# Check that a method has been called at most twice and has
# at least one call with the given argument
mocker(Teapot).spy("add_tea").any_call_with("green").call_count_at_most(2)

Stubs

To create a stub object, just call mocker function without any arguments.

# Create a stub with a method called "my_method"
stub = mocker().mock("my_method").return_value("it works!").self()
assert stub.my_method() == "it works!"

# You can give keyword arguments to the mocker function to quickly set properties
stub = mocker(my_property=10)
assert stub.my_property == 10

For more details and examples, see the API reference.

Similar projects

If chainmock is not what you need, check out also these cool projects:

• flexmock: Chainmock's API is heavily inspired by flexmock. Flexmock doesn't use standard library unittest and it has fully custom mocking implementation. Compared to flexmock, chainmock has more familiar API if you have been using standard library unittest and Chainmock also supports async mocking and partial argument matching.
• pytest-mock: Similar to chainmock, pytest-mock is a wrapper for standard library unittest. However, pytest-mock doesn't provide any extra functionality as it just exposes unittest mocks directly to the user.

Contributing

Do you like this project and want to help? If you need ideas, check out the open issues and feel free to open a new pull request. Bug reports and feature requests are also very welcome.

chainmock's Issues

Test spying properties

Test spying properties.

Test mocking instance attributes

Test mocking instance attributes.

Test `match_args_*` methods with a property

Test match_args_* methods with a property.

Unittest integration

Add unittest integration so that chainmock would also work without pytest.

Improve AnyMock typing

Better type hint for AnyMock. Because PropertyMock is typed as Any, AnyMock also becomes Any and the type hint is not really useful in catching bugs.

Handle calling `side_effect` and `return_value` with spies

Right now, nothing happens if side_effect or return_value is called when spying. Should a a warning or an exception be raised if those methods are called? Should a custom logic be implemented to match the return value of the spy so these methods could actually be useful with spies?

Stubs with spec should pass isinstance test with the spec object

Stubs with spec should pass isinstance test with the spec object.

This code should pass without errors:

from chainmock import mocker

class SomeClass:
    pass

stub = mocker(spec=SomeClass)
assert isinstance(stub, SomeClass)
# Raises AssertionError

Similar code with unittest Mock works:

from unittest import mock

class SomeClass:
    pass

stub = mock.MagicMock(spec=SomeClass)
assert isinstance(stub, SomeClass)

Test mocking & spying builtins

Test mocking & spying builtins. Everything should work since unittest supports mocking builtings but we should still have some tests.

Set name to unittest mocks for better error messages

Set name to unittest mocks for better error messages.

from chainmock import mocker

class SomeClass:
    def foo(self):
        pass

mocker(SomeClass).mock("foo").called_once()

This raises error:

AssertionError: Expected 'foo' to have been called once. Called 0 times.

Ideally the error would be:

AssertionError: Expected 'SomeClass.foo' to have been called once. Called 0 times.

Add contributing documentation

Add contributing documentation.

Make it easier to assert call arguments of multiple calls

Right now if a user wants to assert call arguments for multiple calls in specific order, the only option is to use has_calls method:

>>> from chainmock.mock import call
>>> mocker(Teapot).mock("add_tea").has_calls([call("oolong"), call("black")])
<chainmock._api.Assert object at ...>
>>> Teapot().add_tea("oolong")
>>> Teapot().add_tea("black")

I see these problems with this approach:

• Use caller needs to know all the calls beforehand and new calls can't be easily added afterwards.
• There is no way to use this with match_args_* methods.
• Using call type is a bit cumbersome.

Proposal

• Add new methods:
  • awaited_with
  • called_with
  • match_args_await
  • match_args_call
• Assert call args in the order the methods are called.

The above code could be rewritten as follows:

>>> mocker(Teapot).mock("add_tea").called_with("oolong").called_with("black")
<chainmock._api.Assert object at ...>
>>> Teapot().add_tea("oolong")
>>> Teapot().add_tea("black")

Create changelog

Create changelog.

Automatic tests for user guide examples

Describe the feature or improvement
Test user guide examples automatically. Now only API reference examples are tested automatically using doctest. User guide contains code examples that are not tested.

• Include example code from separate .py files?
• Use Sphinx with Furo theme and write examples using sphinx-doctest?

Test mocking class attributes

Test mocking class attributes.

Support mocking context managers

Support mocking context managers. Implement __enter__ and __aenter__ methods.

Add issue and PR templates

Add issue and PR templates.

Improve user guide

Create usage documentation in addition to API documentation:

Usage documentation

• Mocking async methods
• Mocking properties
• Mocking __call__ method
• Mocking module variables
• Mocking builtins
• Chained methods
• Mock new instances

Other documentation

• Comparison with unittest
• Example usage with pytest
• Document mock.ANY_* types
  • Mention how to use together with argument matching.

Test spying non-callables

Test spying non-callables. What happens when a non-callable like a module variable is spied?