{"id":19642097,"url":"https://github.com/beanbaginc/kgb","last_synced_at":"2025-04-04T10:09:12.342Z","repository":{"id":8582992,"uuid":"10215090","full_name":"beanbaginc/kgb","owner":"beanbaginc","description":"Python function spy support for unit tests","archived":false,"fork":false,"pushed_at":"2024-11-04T03:21:33.000Z","size":310,"stargazers_count":51,"open_issues_count":2,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-28T09:09:21.654Z","etag":null,"topics":["python","python2","python3","unit-test","unit-testing"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beanbaginc.png","metadata":{"files":{"readme":"README.rst","changelog":"NEWS.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-05-22T08:15:40.000Z","updated_at":"2025-01-02T09:03:37.000Z","dependencies_parsed_at":"2024-11-11T14:11:41.374Z","dependency_job_id":"74e3c6d7-545f-44bf-9d70-d2510aa9671e","html_url":"https://github.com/beanbaginc/kgb","commit_stats":{"total_commits":119,"total_committers":6,"mean_commits":"19.833333333333332","dds":0.1512605042016807,"last_synced_commit":"9c18e19b87f60043a45a7461b25ed34a69b7b054"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beanbaginc%2Fkgb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beanbaginc%2Fkgb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beanbaginc%2Fkgb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beanbaginc%2Fkgb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beanbaginc","download_url":"https://codeload.github.com/beanbaginc/kgb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157283,"owners_count":20893220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","python2","python3","unit-test","unit-testing"],"created_at":"2024-11-11T14:11:33.161Z","updated_at":"2025-04-04T10:09:12.319Z","avatar_url":"https://github.com/beanbaginc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"===============================\nkgb - Function spies for Python\n===============================\n\nEver deal with a large test suite before, monkey patching functions to figure\nout whether it was called as expected? It's a dirty job. If you're not careful,\nyou can make a mess of things. Leave behind evidence.\n\nkgb's spies will take care of that little problem for you.\n\n\nWhat are spies?\n===============\n\nSpies intercept and record calls to functions. They can report on how many times\na function was called and with what arguments. They can allow the function call\nto go through as normal, to block it, or to reroute it to another function.\n\nSpies are awesome.\n\n(If you've used Jasmine_, you know this.)\n\nSpies are like mocks, but better. You're not mocking the world. You're\nreplacing very specific function logic, or listening to functions without\naltering them. (See the FAQ below.)\n\n\n.. _Jasmine: https://jasmine.github.io/\n\n\nWhat test platforms are supported?\n==================================\n\nAnything Python-based:\n\n* unittest_\n* pytest_\n* nose_\n* nose2_\n\nYou can even use it outside of unit tests as part of your application. If you\nreally want to. (Probably don't do that.)\n\n\n.. _unittest: https://docs.python.org/3/library/unittest.html\n.. _pytest: https://pytest.org\n.. _nose: https://nose.readthedocs.io/en/latest/\n.. _nose2: https://docs.nose2.io/en/latest/\n\n\nWhere is kgb used?\n==================\n\n* `liveswot-api \u003chttps://github.com/imranariffin/liveswot-api\u003e`_ --\n  REST API Backend for liveswot\n* `phabricator-emails\n  \u003chttps://github.com/mozilla-conduit/phabricator-emails\u003e`_ --\n  Mozilla's utilities for converting Phabricator feeds to e-mails\n* `projector \u003chttps://github.com/brennie/projector\u003e`_ --\n  Takes the overhead out of managing repositories and development environments\n* `ynab-sdk-python \u003chttps://github.com/andreroggeri/ynab-sdk-python\u003e`_ --\n  Python implementation of the YNAB API\n\nPlus our own products:\n\n* `Django Evolution \u003chttps://django-evolution.readthedocs.io/\u003e`_ --\n  An alternative approach to Django database migrations\n* `Djblets \u003chttps://github.com/djblets/djblets/\u003e`_ --\n  An assortment of utilities and add-ons for managing large Django projects\n* `Review Board \u003chttps://www.reviewboard.org/\u003e`_ --\n  Our open source, extensible code review product\n* `RBCommons \u003chttps://rbcommons.com\u003e`_ --\n  Our hosted code review service\n* `RBTools \u003chttps://www.reviewboard.org/downloads/rbtools/\u003e`_ --\n  Command line tools for Review Board\n* `Power Pack \u003chttps://www.reviewboard.org/powerpack/\u003e`_ --\n  Document review, reports, and enterprise SCM integrations for Review Board\n* `Review Bot \u003chttps://www.reviewboard.org/downloads/reviewbot/\u003e`_ --\n  Automated code review add-on for Review Board\n\nIf you use kgb, let us know and we'll add you!\n\n\nInstalling kgb\n==============\n\nBefore you can use kgb, you need to install it. You can do this by typing::\n\n    $ pip install kgb\n\nkgb supports Python 2.7 and 3.6 through 3.11, both CPython and PyPy.\n\n\nSpying for fun and profit\n=========================\n\nSpying is really easy. There are four main ways to initiate a spy.\n\n\n1. Creating a SpyAgency\n-----------------------\n\nA SpyAgency manages all your spies. You can create as many or as few as you\nwant. Generally, you'll create one per unit test run. Then you'll call\n``spy_on()``, passing in the function you want.\n\n.. code-block:: python\n\n    from kgb import SpyAgency\n\n\n    def test_mind_control_device():\n        mcd = MindControlDevice()\n        agency = SpyAgency()\n        agency.spy_on(mcd.assassinate, call_fake=give_hugs)\n\n\n2. Mixing a SpyAgency into your tests\n-------------------------------------\n\nA ``SpyAgency`` can be mixed into your unittest_-based test suite, making\nit super easy to spy all over the place, discretely, without resorting to a\nseparate agency. (We call this the \"inside job.\")\n\n.. code-block:: python\n\n    from kgb import SpyAgency\n\n\n    # Using Python's unittest:\n    class TopSecretTests(SpyAgency, unittest.TestCase):\n        def test_weather_control(self):\n            weather = WeatherControlDevice()\n            self.spy_on(weather.start_raining)\n\n\n    # Using pytest with the \"spy_agency\" fixture (kgb 7+):\n    def test_weather_control(spy_agency):\n        weather = WeatherControlDevice()\n        spy_agency.spy_on(weather.start_raining)\n\n\n3. Using a decorator\n--------------------\n\nIf you're creating a spy that calls a fake function, you can simplify some\nthings by using the ``spy_for`` decorator:\n\n\n.. code-block:: python\n\n    from kgb import SpyAgency\n\n\n    # Using Python's unittest:\n    class TopSecretTests(SpyAgency, unittest.TestCase):\n        def test_doomsday_device(self):\n            dd = DoomsdayDevice()\n\n            @self.spy_for(dd.kaboom)\n            def _save_world(*args, **kwargs)\n                print('Sprinkles and ponies!')\n\n            # Give it your best shot, doomsday device.\n            dd.kaboom()\n\n\n    # Using pytest:\n    def test_doomsday_device(spy_agency):\n        dd = DoomsdayDevice()\n\n        @spy_agency.spy_for(dd.kaboom)\n        def _save_world(*args, **kwargs)\n            print('Sprinkles and ponies!')\n\n        # Give it your best shot, doomsday device.\n        dd.kaboom()\n\n\n4. Using a context manager\n--------------------------\n\nIf you just want a spy for a quick job, without all that hassle of a full\nagency, just use the ``spy_on`` context manager, like so:\n\n.. code-block:: python\n\n    from kgb import spy_on\n\n\n    def test_the_bomb(self):\n        bomb = Bomb()\n\n        with spy_on(bomb.explode, call_original=False):\n            # This won't explode. Phew.\n            bomb.explode()\n\n\nA spy's abilities\n=================\n\nA spy can do many things. The first thing you need to do is figure out how you\nwant to use the spy.\n\n\nCreating a spy that calls the original function\n-----------------------------------------------\n\n.. code-block:: python\n\n    spy_agency.spy_on(obj.function)\n\n\nWhen your spy is called, the original function will be called as well.\nIt won't even know you were there.\n\n\nCreating a spy that blocks the function call\n--------------------------------------------\n\n.. code-block:: python\n\n    spy_agency.spy_on(obj.function, call_original=False)\n\n\nUseful if you want to know that a function was called, but don't want the\noriginal function to actually get the call.\n\n\nCreating a spy that reroutes to a fake function\n-----------------------------------------------\n\n.. code-block:: python\n\n    def _my_fake_function(some_param, *args, **kwargs):\n        ...\n\n    spy_agency.spy_on(obj.function, call_fake=my_fake_function)\n\n    # Or, in kgb 6+\n    @spy_agency.spy_for(obj.function)\n    def _my_fake_function(some_param, *args, **kwargs):\n        ...\n\n\nFake the return values or operations without anybody knowing.\n\n\nStopping a spy operation\n------------------------\n\n.. code-block:: python\n\n    obj.function.unspy()\n\n\nDo your job and get out.\n\n\nCheck the call history\n----------------------\n\n.. code-block:: python\n\n    for call in obj.function.calls:\n        print(calls.args, calls.kwargs)\n\n\nSee how many times your spy's intercepted a function call, and what was passed.\n\n\nCheck a specific call\n---------------------\n\n.. code-block:: python\n\n    # Check the latest call...\n    print(obj.function.last_call.args)\n    print(obj.function.last_call.kwargs)\n    print(obj.function.last_call.return_value)\n    print(obj.function.last_call.exception)\n\n    # For an older call...\n    print(obj.function.calls[0].args)\n    print(obj.function.calls[0].kwargs)\n    print(obj.function.calls[0].return_value)\n    print(obj.function.calls[0].exception)\n\n\nAlso a good way of knowing whether it's even been called. ``last_call`` will\nbe ``None`` if nobody's called yet.\n\n\nCheck if the function was ever called\n-------------------------------------\n\nMixing in ``SpyAgency`` into a unittest_-based test suite:\n\n.. code-block:: python\n\n    # Either one of these is fine.\n    self.assertSpyCalled(obj.function)\n    self.assertTrue(obj.function.called)\n\n    # Or the inverse:\n    self.assertSpyNotCalled(obj.function)\n    self.assertFalse(obj.function.called)\n\n\nOr using the pytest_ ``spy_agency`` fixture on kgb 7+:\n\n.. code-block:: python\n\n    spy_agency.assert_spy_called(obj.function)\n    spy_agency.assert_spy_not_called(obj.function)\n\n\nOr using standalone assertion methods on kgb 7+:\n\n.. code-block:: python\n\n    from kgb.asserts import (assert_spy_called,\n                             assert_spy_not_called)\n\n    assert_spy_called(obj.function)\n    assert_spy_not_called(obj.function)\n\n\nIf the function was ever called at all, this will let you know.\n\n\nCheck if the function was ever called with certain arguments\n------------------------------------------------------------\n\nMixing in ``SpyAgency`` into a unittest_-based test suite:\n\n.. code-block:: python\n\n    # Check if it was ever called with these arguments...\n    self.assertSpyCalledWith(obj.function, 'foo', bar='baz')\n    self.assertTrue(obj.function.called_with('foo', bar='baz'))\n\n    # Check a specific call...\n    self.assertSpyCalledWith(obj.function.calls[0], 'foo', bar='baz')\n    self.assertTrue(obj.function.calls[0].called_with('foo', bar='baz'))\n\n    # Check the last call...\n    self.assertSpyLastCalledWith(obj.function, 'foo', bar='baz')\n    self.assertTrue(obj.function.last_called_with('foo', bar='baz'))\n\n    # Or the inverse:\n    self.assertSpyNotCalledWith(obj.function, 'foo', bar='baz')\n    self.assertFalse(obj.function.called)\n\n\nOr using the pytest_ ``spy_agency`` fixture on kgb 7+:\n\n.. code-block:: python\n\n    spy_agency.assert_spy_called_with(obj.function, 'foo', bar='baz')\n    spy_agency.assert_spy_last_called_with(obj.function, 'foo', bar='baz')\n    spy_agency.assert_spy_not_called_with(obj.function, 'foo', bar='baz')\n\n\nOr using standalone assertion methods on kgb 7+:\n\n.. code-block:: python\n\n    from kgb.asserts import (assert_spy_called_with,\n                             assert_spy_last_called_with,\n                             assert_spy_not_called_with)\n\n    assert_spy_called_with(obj.function, 'foo', bar='baz')\n    assert_spy_last_called_with(obj.function, 'foo', bar='baz')\n    assert_spy_not_called_with(obj.function, 'foo', bar='baz')\n\n\nThe whole callkhistory will be searched. You can provide the entirety of the\narguments passed to the function, or you can provide a subset. You can pass\npositional arguments as-is, or pass them by name using keyword arguments.\n\nRecorded calls always follow the function's original signature, so even if a\nkeyword argument was passed a positional value, it will be recorded as a\nkeyword argument.\n\n\nCheck if the function ever returned a certain value\n---------------------------------------------------\n\nMixing in ``SpyAgency`` into a unittest_-based test suite:\n\n.. code-block:: python\n\n    # Check if the function ever returned a certain value...\n    self.assertSpyReturned(obj.function, 42)\n    self.assertTrue(obj.function.returned(42))\n\n    # Check a specific call...\n    self.assertSpyReturned(obj.function.calls[0], 42)\n    self.assertTrue(obj.function.calls[0].returned(42))\n\n    # Check the last call...\n    self.assertSpyLastReturned(obj.function, 42)\n    self.assertTrue(obj.function.last_returned(42))\n\n\nOr using the pytest_ ``spy_agency`` fixture on kgb 7+:\n\n.. code-block:: python\n\n    spy_agency.assert_spy_returned(obj.function, 42)\n    spy_agency.assert_spy_returned(obj.function.calls[0], 42)\n    spy_agency.assert_spy_last_returned(obj.function, 42)\n\n\nOr using standalone assertion methods on kgb 7+:\n\n.. code-block:: python\n\n    from kgb.asserts import (assert_spy_last_returned,\n                             assert_spy_returned)\n\n    assert_spy_returned(obj.function, 42)\n    assert_spy_returned(obj.function.calls[0], 42)\n    assert_spy_last_returned(obj.function, 42)\n\n\nHandy for checking if some function ever returned what you expected it to, when\nyou're not calling that function yourself.\n\n\nCheck if a function ever raised a certain type of exception\n-----------------------------------------------------------\n\nMixing in ``SpyAgency`` into a unittest_-based test suite:\n\n.. code-block:: python\n\n    # Check if the function ever raised a certain exception...\n    self.assertSpyRaised(obj.function, TypeError)\n    self.assertTrue(obj.function.raised(TypeError))\n\n    # Check a specific call...\n    self.assertSpyRaised(obj.function.calls[0], TypeError)\n    self.assertTrue(obj.function.calls[0].raised(TypeError))\n\n    # Check the last call...\n    self.assertSpyLastRaised(obj.function, TypeError)\n    self.assertTrue(obj.function.last_raised(TypeError))\n\n\nOr using the pytest_ ``spy_agency`` fixture on kgb 7+:\n\n.. code-block:: python\n\n    spy_agency.assert_spy_raised(obj.function, TypeError)\n    spy_agency.assert_spy_raised(obj.function.calls[0], TypeError)\n    spy_agency.assert_spy_last_raised(obj.function, TypeError)\n\n\nOr using standalone assertion methods on kgb 7+:\n\n.. code-block:: python\n\n    from kgb.asserts import (assert_spy_last_raised,\n                             assert_spy_raised)\n\n    assert_spy_raised(obj.function, TypeError)\n    assert_spy_raised(obj.function.calls[0], TypeError)\n    assert_spy_last_raised(obj.function, TypeError)\n\n\nYou can also go a step further by checking the exception's message.\n\n.. code-block:: python\n\n    # Check if the function ever raised an exception with a given message...\n    self.assertSpyRaisedWithMessage(\n        obj.function,\n        TypeError,\n        \"'type' object is not iterable\")\n    self.assertTrue(obj.function.raised_with_message(\n        TypeError,\n        \"'type' object is not iterable\"))\n\n    # Check a specific call...\n    self.assertSpyRaisedWithMessage(\n        obj.function.calls[0],\n        TypeError,\n        \"'type' object is not iterable\")\n    self.assertTrue(obj.function.calls[0].raised_with_message(\n        TypeError,\n        \"'type' object is not iterable\"))\n\n    # Check the last call...\n    self.assertSpyLastRaisedWithMessage(\n        obj.function,\n        TypeError,\n        \"'type' object is not iterable\")\n    self.assertTrue(obj.function.last_raised_with_message(\n        TypeError,\n        \"'type' object is not iterable\"))\n\n\nReset all the calls\n-------------------\n\n.. code-block:: python\n\n    obj.function.reset_calls()\n\n\nWipe away the call history. Nobody will know.\n\n\nCall the original function\n--------------------------\n\n.. code-block:: python\n\n    result = obj.function.call_original('foo', bar='baz')\n\n\nSuper, super useful if you want to use ``call_fake=`` or\n``@spy_agency.spy_for`` to wrap a function and track or influence some part of\nit, but still want the original function to do its thing. For instance:\n\n.. code-block:: python\n\n    stored_results = []\n\n    @spy_agency.spy_for(obj.function)\n    def my_fake_function(*args, **kwargs):\n        kwargs['bar'] = 'baz'\n        result = obj.function.call_original(*args, **kwargs)\n        stored_results.append(result)\n\n        return result\n\n\nPlan a spy operation\n====================\n\nWhy start from scratch when setting up a spy? Let's plan an operation.\n\n(Spy operations are only available in kgb 6 or higher.)\n\n\nRaise an exception when called\n------------------------------\n\n.. code-block:: python\n\n   spy_on(pen.emit_poison, op=kgb.SpyOpRaise(PoisonEmptyError()))\n\nOr go nuts, have a different exception for each call (in kgb 6.1+):\n\n.. code-block:: python\n\n   spy_on(pen.emit_poison, op=kgb.SpyOpRaiseInOrder([\n       PoisonEmptyError(),\n       Kaboom(),\n       MissingPenError(),\n   ]))\n\n\nOr return a value\n-----------------\n\n.. code-block:: python\n\n   spy_on(our_agent.get_identity, op=kgb.SpyOpReturn('nobody...'))\n\nMaybe a different value for each call (in kgb 6.1+)?\n\n.. code-block:: python\n\n   spy_on(our_agent.get_identity, op=kgb.SpyOpReturnInOrder([\n       'nobody...',\n       'who?',\n       'not telling...',\n   ]))\n\n\nNow for something more complicated.\n\n\nHandle a call based on the arguments used\n-----------------------------------------\n\nIf you're dealing with many calls to the same function, you may want to return\ndifferent values or only call the original function depending on which\narguments were passed in the call. That can be done with a ``SpyOpMatchAny``\noperation.\n\n.. code-block:: python\n\n   spy_on(traps.trigger, op=kgb.SpyOpMatchAny([\n       {\n           'args': ('hallway_lasers',),\n           'call_fake': _send_wolves,\n       },\n       {\n           'args': ('trap_tile',),\n           'op': SpyOpMatchInOrder([\n               {\n                   'call_fake': _spill_hot_oil,\n               },\n               {\n                   'call_fake': _drop_torch,\n               },\n           ]),\n       },\n       {\n           'args': ('infrared_camera',),\n           'kwargs': {\n               'sector': 'underground_passage',\n           },\n           'call_original': False,\n       },\n   ]))\n\nAny unexpected calls will automatically assert.\n\n\nOr require those calls in a specific order\n------------------------------------------\n\nYou can combine that with requiring the calls to be in the order you want\nusing ``SpyOpMatchInOrder``.\n\n.. code-block:: python\n\n   spy_on(lockbox.enter_code, op=kgb.SpyOpMatchInOrder([\n       {\n           'args': (1, 2, 3, 4, 5, 6),\n           'call_original': False,\n       },\n       {\n           'args': (9, 0, 2, 1, 0, 0),\n           'call_fake': _start_countdown,\n       },\n       {\n           'args': (42, 42, 42, 42, 42, 42),\n           'op': kgb.SpyOpRaise(Kaboom()),\n           'call_original': True,\n       },\n       {\n           'args': (4, 8, 15, 16, 23, 42),\n           'kwargs': {\n               'secret_button_pushed': True,\n           },\n           'call_original': True,\n       }\n   ]))\n\n\nFAQ\n===\n\nDoesn't this just do what mock does?\n------------------------------------\n\nkgb's spies and mock_'s patching are very different from each other. When\npatching using mock, you're simply replacing a method on a class with\nsomething that looks like a method, and that works great except you're limited\nto methods on classes. You can't override a top-level function, like\n``urllib2.urlopen``.\n\nkgb spies leave the function or method where it is. What it *does* do is\nreplace the *bytecode* of the function, intercepting calls on a very low\nlevel, recording everything about it, and then passing on the call to the\noriginal function or your replacement function. It's pretty powerful, and\nallows you to listen to or override calls you normally would have no control\nover.\n\n.. _mock: https://pypi.python.org/pypi/mock\n\n\nWhat?! There's no way that's stable.\n------------------------------------\n\nIt is! It really is! We've been using it for years across a wide variety of\ncodebases. It's pretty amazing.\n\nPython actually allows this. We're not scanning your RAM and doing terrible\nthings with it, or something like that. Every function or method in Python has\na ``func_code`` (Python 2) or ``__code__`` (Python 3) attribute, which is\nmutable. We can go in and replace the bytecode with something compatible with\nthe original function.\n\nHow we actually do that, well, that's complicated, and you may not want to\nknow.\n\n\nDoes this work with PyPy?\n-------------------------\n\nI'm going to level with you, I was going to say \"hell no!\", and then decided\nto give it a try.\n\nHell yes! (But only accidentally. YMMV... We'll try to officially support this\nlater.)\n\n\nWhat else do you build?\n-----------------------\n\nLots of things. Check out some of our other `open source projects`_.\n\n.. _open source projects: https://www.beanbaginc.com/opensource/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeanbaginc%2Fkgb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeanbaginc%2Fkgb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeanbaginc%2Fkgb/lists"}