kgb

Utilities for spying on function calls in unit tests.

Description

===============================
kgb - Function spies for Python
===============================

Ever deal with a large test suite before, monkey patching functions to figure
out whether it was called as expected? It's a dirty job. If you're not careful,
you can make a mess of things. Leave behind evidence.

kgb's spies will take care of that little problem for you.


What are spies?
===============

Spies intercept and record calls to functions. They can report on how many times
a function was called and with what arguments. They can allow the function call
to go through as normal, to block it, or to reroute it to another function.

Spies are awesome.

(If you've used Jasmine_, you know this.)

Spies are like mocks, but better. You're not mocking the world. You're
replacing very specific function logic, or listening to functions without
altering them. (See the FAQ below.)


.. _Jasmine: https://jasmine.github.io/


What test platforms are supported?
==================================

Anything Python-based:

* unittest_
* pytest_
* nose_
* nose2_

You can even use it outside of unit tests as part of your application. If you
really want to. (Probably don't do that.)


.. _unittest: https://docs.python.org/3/library/unittest.html
.. _pytest: https://pytest.org
.. _nose: https://nose.readthedocs.io/en/latest/
.. _nose2: https://docs.nose2.io/en/latest/


Where is kgb used?
==================

* `liveswot-api <https://github.com/imranariffin/liveswot-api>`_ --
  REST API Backend for liveswot
* `phabricator-emails
  <https://github.com/mozilla-conduit/phabricator-emails>`_ --
  Mozilla's utilities for converting Phabricator feeds to e-mails
* `projector <https://github.com/brennie/projector>`_ --
  Takes the overhead out of managing repositories and development environments
* `ynab-sdk-python <https://github.com/andreroggeri/ynab-sdk-python>`_ --
  Python implementation of the YNAB API

Plus our own products:

* `Django Evolution <https://django-evolution.readthedocs.io/>`_ --
  An alternative approach to Django database migrations
* `Djblets <https://github.com/djblets/djblets/>`_ --
  An assortment of utilities and add-ons for managing large Django projects
* `Review Board <https://www.reviewboard.org/>`_ --
  Our open source, extensible code review product
* `RBCommons <https://rbcommons.com>`_ --
  Our hosted code review service
* `RBTools <https://www.reviewboard.org/downloads/rbtools/>`_ --
  Command line tools for Review Board
* `Power Pack <https://www.reviewboard.org/powerpack/>`_ --
  Document review, reports, and enterprise SCM integrations for Review Board
* `Review Bot <https://www.reviewboard.org/downloads/reviewbot/>`_ --
  Automated code review add-on for Review Board

If you use kgb, let us know and we'll add you!


Installing kgb
==============

Before you can use kgb, you need to install it. You can do this by typing::

    $ pip install kgb

kgb supports Python 2.7 and 3.6 through 3.11, both CPython and PyPy.


Spying for fun and profit
=========================

Spying is really easy. There are four main ways to initiate a spy.


1. Creating a SpyAgency
-----------------------

A SpyAgency manages all your spies. You can create as many or as few as you
want. Generally, you'll create one per unit test run. Then you'll call
``spy_on()``, passing in the function you want.

.. code-block:: python

    from kgb import SpyAgency


    def test_mind_control_device():
        mcd = MindControlDevice()
        agency = SpyAgency()
        agency.spy_on(mcd.assassinate, call_fake=give_hugs)


2. Mixing a SpyAgency into your tests
-------------------------------------

A ``SpyAgency`` can be mixed into your unittest_-based test suite, making
it super easy to spy all over the place, discretely, without resorting to a
separate agency. (We call this the "inside job.")

.. code-block:: python

    from kgb import SpyAgency


    # Using Python's unittest:
    class TopSecretTests(SpyAgency, unittest.TestCase):
        def test_weather_control(self):
            weather = WeatherControlDevice()
            self.spy_on(weather.start_raining)


    # Using pytest with the "spy_agency" fixture (kgb 7+):
    def test_weather_control(spy_agency):
        weather = WeatherControlDevice()
        spy_agency.spy_on(weather.start_raining)


3. Using a decorator
--------------------

If you're creating a spy that calls a fake function, you can simplify some
things by using the ``spy_for`` decorator:


.. code-block:: python

    from kgb import SpyAgency


    # Using Python's unittest:
    class TopSecretTests(SpyAgency, unittest.TestCase):
        def test_doomsday_device(self):
            dd = DoomsdayDevice()

            @self.spy_for(dd.kaboom)
            def _save_world(*args, **kwargs)
                print('Sprinkles and ponies!')

            # Give it your best shot, doomsday device.
            dd.kaboom()


    # Using pytest:
    def test_doomsday_device(spy_agency):
        dd = DoomsdayDevice()

        @spy_agency.spy_for(dd.kaboom)
        def _save_world(*args, **kwargs)
            print('Sprinkles and ponies!')

        # Give it your best shot, doomsday device.
        dd.kaboom()


4. Using a context manager
--------------------------

If you just want a spy for a quick job, without all that hassle of a full
agency, just use the ``spy_on`` context manager, like so:

.. code-block:: python

    from kgb import spy_on


    def test_the_bomb(self):
        bomb = Bomb()

        with spy_on(bomb.explode, call_original=False):
            # This won't explode. Phew.
            bomb.explode()


A spy's abilities
=================

A spy can do many things. The first thing you need to do is figure out how you
want to use the spy.


Creating a spy that calls the original function
-----------------------------------------------

.. code-block:: python

    spy_agency.spy_on(obj.function)


When your spy is called, the original function will be called as well.
It won't even know you were there.


Creating a spy that blocks the function call
--------------------------------------------

.. code-block:: python

    spy_agency.spy_on(obj.function, call_original=False)


Useful if you want to know that a function was called, but don't want the
original function to actually get the call.


Creating a spy that reroutes to a fake function
-----------------------------------------------

.. code-block:: python

    def _my_fake_function(some_param, *args, **kwargs):
        ...

    spy_agency.spy_on(obj.function, call_fake=my_fake_function)

    # Or, in kgb 6+
    @spy_agency.spy_for(obj.function)
    def _my_fake_function(some_param, *args, **kwargs):
        ...


Fake the return values or operations without anybody knowing.


Stopping a spy operation
------------------------

.. code-block:: python

    obj.function.unspy()


Do your job and get out.


Check the call history
----------------------

.. code-block:: python

    for call in obj.function.calls:
        print(calls.args, calls.kwargs)


See how many times your spy's intercepted a function call, and what was passed.


Check a specific call
---------------------

.. code-block:: python

    # Check the latest call...
    print(obj.function.last_call.args)
    print(obj.function.last_call.kwargs)
    print(obj.function.last_call.return_value)
    print(obj.function.last_call.exception)

    # For an older call...
    print(obj.function.calls[0].args)
    print(obj.function.calls[0].kwargs)
    print(obj.function.calls[0].return_value)
    print(obj.function.calls[0].exception)


Also a good way of knowing whether it's even been called. ``last_call`` will
be ``None`` if nobody's called yet.


Check if the function was ever called
-------------------------------------

Mixing in ``SpyAgency`` into a unittest_-based test suite:

.. code-block:: python

    # Either one of these is fine.
    self.assertSpyCalled(obj.function)
    self.assertTrue(obj.function.called)

    # Or the inverse:
    self.assertSpyNotCalled(obj.function)
    self.assertFalse(obj.function.called)


Or using the pytest_ ``spy_agency`` fixture on kgb 7+:

.. code-block:: python

    spy_agency.assert_spy_called(obj.function)
    spy_agency.assert_spy_not_called(obj.function)


Or using standalone assertion methods on kgb 7+:

.. code-block:: python

    from kgb.asserts import (assert_spy_called,
                             assert_spy_not_called)

    assert_spy_called(obj.function)
    assert_spy_not_called(obj.function)


If the function was ever called at all, this will let you know.


Check if the function was ever called with certain arguments
------------------------------------------------------------

Mixing in ``SpyAgency`` into a unittest_-based test suite:

.. code-block:: python

    # Check if it was ever called with these arguments...
    self.assertSpyCalledWith(obj.function, 'foo', bar='baz')
    self.assertTrue(obj.function.called_with('foo', bar='baz'))

    # Check a specific call...
    self.assertSpyCalledWith(obj.function.calls[0], 'foo', bar='baz')
    self.assertTrue(obj.function.calls[0].called_with('foo', bar='baz'))

    # Check the last call...
    self.assertSpyLastCalledWith(obj.function, 'foo', bar='baz')
    self.assertTrue(obj.function.last_called_with('foo', bar='baz'))

    # Or the inverse:
    self.assertSpyNotCalledWith(obj.function, 'foo', bar='baz')
    self.assertFalse(obj.function.called)


Or using the pytest_ ``spy_agency`` fixture on kgb 7+:

.. code-block:: python

    spy_agency.assert_spy_called_with(obj.function, 'foo', bar='baz')
    spy_agency.assert_spy_last_called_with(obj.function, 'foo', bar='baz')
    spy_agency.assert_spy_not_called_with(obj.function, 'foo', bar='baz')


Or using standalone assertion methods on kgb 7+:

.. code-block:: python

    from kgb.asserts import (assert_spy_called_with,
                             assert_spy_last_called_with,
                             assert_spy_not_called_with)

    asser