calleee
=======
Argument matchers for *unittest.mock*
|Version| |Development Status| |Python Versions| |License| |Build Status|
.. |Version| image:: https://img.shields.io/pypi/v/calleee.svg?style=flat
:target: https://pypi.python.org/pypi/calleee
:alt: Version
.. |Development Status| image:: https://img.shields.io/pypi/status/calleee.svg?style=flat
:target: https://pypi.python.org/pypi/calleee/
:alt: Development Status
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/calleee.svg?style=flat
:target: https://pypi.python.org/pypi/calleee
:alt: Python versions
.. |License| image:: https://img.shields.io/pypi/l/calleee.svg?style=flat
:target: https://github.com/untidy-hair/calleee/blob/master/LICENSE
:alt: License
.. |Build Status| image:: https://img.shields.io/travis/untidy-hair/calleee.svg?style=flat
:target: https://travis-ci.org/untidy-hair/calleee
:alt: Build Status
More robust tests
~~~~~~~~~~~~~~~~~
Python's `mocking library`_ (or its `backport`_ for Python <3.3) is simple, reliable, and easy to use.
But it is also a little lacking when it comes to asserting what calls a mock has received.
You can be either very specific::
my_mock.assert_called_once_with(42, some_foo_object, 'certain string')
or extremely general::
my_mock.assert_called_with(ANY, ANY, ANY)
# passes as long as argument count is the same
| The former can make your tests over-specified, and thus fragile.
| The latter could make them too broad, missing some erroneous cases and possibly letting your code fail in production.
----
*calleee* provides **argument matchers** that allow you to be exactly as precise as you want::
my_mock.assert_called_with(GreaterThan(0), InstanceOf(Foo), String())
without tedious, handcrafted, and poorly readable code that checks ``call_args`` or ``call_args_list``::
self.assertGreater(mock.call_args[0][0], 0)
self.assertIsInstance(mock.call_args[0][1], Foo)
self.assertIsInstance(mock.call_args[0][2], str)
It has plenty of matcher types to fit all common and uncommon needs, and you can easily write your own if necessary.
.. _mocking library: https://docs.python.org/3/library/unittest.mock.html
.. _backport: https://pypi.python.org/pypi/mock
Installation
~~~~~~~~~~~~
Installing *calleee* is easy with pip::
$ pip install calleee
| *calleee* supports Python 2.7, 3.6+.
API reference
~~~~~~~~~~~~~
See the `documentation`_ for complete reference on the library usage and all available matchers.
.. _documentation: http://calleee.readthedocs.org
Contributing
~~~~~~~~~~~~
Contributions are welcome!
If you need ideas, head to the issue tracker or search for the various ``TODO``\ s scattered around the codebase.
Or just think what matchers you'd like to add :)
After cloning the repository, this should get you up and running::
# ... create virtualenv as necessary ...
pip install -r requirements-dev.txt
tox
To regenerate documentation and display it in the browser, simply run::
inv docs
Happy hacking!
