| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| |
| <title>Mock - Mocking and Testing Library — Mock 1.0.0 documentation</title> |
| |
| <link rel="stylesheet" href="_static/nature.css" type="text/css" /> |
| <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> |
| |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT: '', |
| VERSION: '1.0.0', |
| COLLAPSE_INDEX: false, |
| FILE_SUFFIX: '.html', |
| HAS_SOURCE: true |
| }; |
| </script> |
| <script type="text/javascript" src="_static/jquery.js"></script> |
| <script type="text/javascript" src="_static/underscore.js"></script> |
| <script type="text/javascript" src="_static/doctools.js"></script> |
| <link rel="top" title="Mock 1.0.0 documentation" href="#" /> |
| <link rel="next" title="The Mock Class" href="mock.html" /> |
| </head> |
| <body> |
| <div class="related"> |
| <h3>Navigation</h3> |
| <ul> |
| <li class="right" style="margin-right: 10px"> |
| <a href="genindex.html" title="General Index" |
| accesskey="I">index</a></li> |
| <li class="right" > |
| <a href="mock.html" title="The Mock Class" |
| accesskey="N">next</a> |</li> |
| <li><a href="#">Mock 1.0.0 documentation</a> »</li> |
| </ul> |
| </div> |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| <div class="body"> |
| |
| <div class="section" id="mock-mocking-and-testing-library"> |
| <h1>Mock - Mocking and Testing Library<a class="headerlink" href="#mock-mocking-and-testing-library" title="Permalink to this headline">¶</a></h1> |
| <table class="docutils field-list" frame="void" rules="none"> |
| <col class="field-name" /> |
| <col class="field-body" /> |
| <tbody valign="top"> |
| <tr class="field-odd field"><th class="field-name">Author:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/weblog/index.shtml">Michael Foord</a></td> |
| </tr> |
| <tr class="field-even field"><th class="field-name">Version:</th><td class="field-body">1.0.0</td> |
| </tr> |
| <tr class="field-odd field"><th class="field-name">Date:</th><td class="field-body">2012/10/07</td> |
| </tr> |
| <tr class="field-even field"><th class="field-name">Homepage:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/mock/">Mock Homepage</a></td> |
| </tr> |
| <tr class="field-odd field"><th class="field-name">Download:</th><td class="field-body"><a class="reference external" href="http://pypi.python.org/pypi/mock">Mock on PyPI</a></td> |
| </tr> |
| <tr class="field-even field"><th class="field-name">Documentation:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/downloads/mock-1.0.0.pdf">PDF Documentation</a></td> |
| </tr> |
| <tr class="field-odd field"><th class="field-name">License:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/license.shtml">BSD License</a></td> |
| </tr> |
| <tr class="field-even field"><th class="field-name">Support:</th><td class="field-body"><a class="reference external" href="http://lists.idyll.org/listinfo/testing-in-python">Mailing list (testing-in-python@lists.idyll.org)</a></td> |
| </tr> |
| <tr class="field-odd field"><th class="field-name">Issue tracker:</th><td class="field-body"><a class="reference external" href="http://code.google.com/p/mock/issues/list">Google code project</a></td> |
| </tr> |
| </tbody> |
| </table> |
| <span class="target" id="module-mock"></span><p id="index-0">mock is a library for testing in Python. It allows you to replace parts of |
| your system under test with mock objects and make assertions about how they |
| have been used.</p> |
| <p>mock is now part of the Python standard library, available as <a class="reference external" href="http://docs.python.org/py3k/library/unittest.mock.html#module-unittest.mock">unittest.mock</a> |
| in Python 3.3 onwards.</p> |
| <p>mock provides a core <a class="reference internal" href="mock.html#mock.Mock" title="mock.Mock"><tt class="xref py py-class docutils literal"><span class="pre">Mock</span></tt></a> class removing the need to create a host |
| of stubs throughout your test suite. After performing an action, you can make |
| assertions about which methods / attributes were used and arguments they were |
| called with. You can also specify return values and set needed attributes in |
| the normal way.</p> |
| <p>Additionally, mock provides a <a class="reference internal" href="patch.html#mock.patch" title="mock.patch"><tt class="xref py py-func docutils literal"><span class="pre">patch()</span></tt></a> decorator that handles patching |
| module and class level attributes within the scope of a test, along with |
| <a class="reference internal" href="sentinel.html#mock.sentinel" title="mock.sentinel"><tt class="xref py py-const docutils literal"><span class="pre">sentinel</span></tt></a> for creating unique objects. See the <a class="reference internal" href="#quick-guide">quick guide</a> for |
| some examples of how to use <a class="reference internal" href="mock.html#mock.Mock" title="mock.Mock"><tt class="xref py py-class docutils literal"><span class="pre">Mock</span></tt></a>, <a class="reference internal" href="magicmock.html#mock.MagicMock" title="mock.MagicMock"><tt class="xref py py-class docutils literal"><span class="pre">MagicMock</span></tt></a> and |
| <a class="reference internal" href="patch.html#mock.patch" title="mock.patch"><tt class="xref py py-func docutils literal"><span class="pre">patch()</span></tt></a>.</p> |
| <p>Mock is very easy to use and is designed for use with |
| <a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest</a>. Mock is based on |
| the ‘action -> assertion’ pattern instead of <cite>‘record -> replay’</cite> used by many |
| mocking frameworks.</p> |
| <p>mock is tested on Python versions 2.4-2.7, Python 3 plus the latest versions of |
| Jython and PyPy.</p> |
| <div class="section" id="api-documentation"> |
| <h2>API Documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2> |
| <div class="toctree-wrapper compound"> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="mock.html">The Mock Class</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="mock.html#calling">Calling</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="mock.html#deleting-attributes">Deleting Attributes</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="mock.html#attaching-mocks-as-attributes">Attaching Mocks as Attributes</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="patch.html">Patch Decorators</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#patch">patch</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#patch-object">patch.object</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#patch-dict">patch.dict</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#patch-multiple">patch.multiple</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#patch-methods-start-and-stop">patch methods: start and stop</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#test-prefix">TEST_PREFIX</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#nesting-patch-decorators">Nesting Patch Decorators</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#where-to-patch">Where to patch</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="patch.html#patching-descriptors-and-proxy-objects">Patching Descriptors and Proxy Objects</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="helpers.html">Helpers</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="helpers.html#call">call</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="helpers.html#create-autospec">create_autospec</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="helpers.html#any">ANY</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="helpers.html#filter-dir">FILTER_DIR</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="helpers.html#mock-open">mock_open</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="helpers.html#autospeccing">Autospeccing</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="sentinel.html">Sentinel</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="sentinel.html#sentinel-example">Sentinel Example</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="magicmock.html">Mocking Magic Methods</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="magicmock.html#magic-mock">Magic Mock</a></li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="user-guide"> |
| <h2>User Guide<a class="headerlink" href="#user-guide" title="Permalink to this headline">¶</a></h2> |
| <div class="toctree-wrapper compound"> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started with Mock</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="getting-started.html#using-mock">Using Mock</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="getting-started.html#patch-decorators">Patch Decorators</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="examples.html">Further Examples</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-chained-calls">Mocking chained calls</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#partial-mocking">Partial mocking</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-a-generator-method">Mocking a Generator Method</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#applying-the-same-patch-to-every-test-method">Applying the same patch to every test method</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-unbound-methods">Mocking Unbound Methods</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#checking-multiple-calls-with-mock">Checking multiple calls with mock</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#coping-with-mutable-arguments">Coping with mutable arguments</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#raising-exceptions-on-attribute-access">Raising exceptions on attribute access</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#multiple-calls-with-different-effects">Multiple calls with different effects</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#nesting-patches">Nesting Patches</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-a-dictionary-with-magicmock">Mocking a dictionary with MagicMock</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mock-subclasses-and-their-attributes">Mock subclasses and their attributes</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-imports-with-patch-dict">Mocking imports with patch.dict</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#tracking-order-of-calls-and-less-verbose-call-assertions">Tracking order of calls and less verbose call assertions</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#more-complex-argument-matching">More complex argument matching</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#less-verbose-configuration-of-mock-objects">Less verbose configuration of mock objects</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#matching-any-argument-in-assertions">Matching any argument in assertions</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-properties">Mocking Properties</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-open">Mocking open</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="examples.html#mocks-without-some-attributes">Mocks without some attributes</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="compare.html">Mock Library Comparison</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#simple-fake-object">Simple fake object</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#simple-mock">Simple mock</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#creating-partial-mocks">Creating partial mocks</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#ensure-calls-are-made-in-specific-order">Ensure calls are made in specific order</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#raising-exceptions">Raising exceptions</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#override-new-instances-of-a-class">Override new instances of a class</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#call-the-same-method-multiple-times">Call the same method multiple times</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#mock-chained-methods">Mock chained methods</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#mocking-a-context-manager">Mocking a context manager</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="compare.html#mocking-the-builtin-open-used-as-a-context-manager">Mocking the builtin open used as a context manager</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="changelog.html">CHANGELOG</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-1-0-0">2012/10/07 Version 1.0.0</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-1-0-0-beta-1">2012/07/13 Version 1.0.0 beta 1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-1-0-0-alpha-2">2012/05/04 Version 1.0.0 alpha 2</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-1-0-0-alpha-1">2012/03/25 Version 1.0.0 alpha 1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0">2012/02/13 Version 0.8.0</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-release-candidate-2">2012/01/10 Version 0.8.0 release candidate 2</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-release-candidate-1">2011/12/29 Version 0.8.0 release candidate 1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-beta-4">2011/10/09 Version 0.8.0 beta 4</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-beta-3">2011/08/15 Version 0.8.0 beta 3</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-beta-2">2011/08/05 Version 0.8.0 beta 2</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-beta-1">2011/07/25 Version 0.8.0 beta 1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-alpha-2">2011/07/16 Version 0.8.0 alpha 2</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-alpha-1">2011/06/14 Version 0.8.0 alpha 1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-2">2011/05/30 Version 0.7.2</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-1">2011/05/06 Version 0.7.1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0">2011/03/05 Version 0.7.0</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-rc-1">2011/02/16 Version 0.7.0 RC 1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-beta-4">2010/11/12 Version 0.7.0 beta 4</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-beta-3">2010/09/18 Version 0.7.0 beta 3</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-beta-2">2010/06/23 Version 0.7.0 beta 2</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-beta-1">2010/06/22 Version 0.7.0 beta 1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-6-0">2009/08/22 Version 0.6.0</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-5-0">2009/04/17 Version 0.5.0</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-4-0">2008/10/12 Version 0.4.0</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-3-1">2007/12/03 Version 0.3.1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-3-0">2007/11/30 Version 0.3.0</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-2-1">2007/11/21 Version 0.2.1</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-2-0">2007/11/20 Version 0.2.0</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-1-0">2007/11/19 Version 0.1.0</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="changelog.html#todo-and-limitations">TODO and Limitations</a></li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="installing"> |
| <span id="index-1"></span><h2>Installing<a class="headerlink" href="#installing" title="Permalink to this headline">¶</a></h2> |
| <p>The current version is 1.0.0. Mock is stable and widely used. If you do |
| find any bugs, or have suggestions for improvements / extensions |
| then please contact us.</p> |
| <ul class="simple"> |
| <li><a class="reference external" href="http://pypi.python.org/pypi/mock">mock on PyPI</a></li> |
| <li><a class="reference external" href="http://www.voidspace.org.uk/downloads/mock-1.0.0.pdf">mock documentation as PDF</a></li> |
| <li><a class="reference external" href="http://code.google.com/p/mock/">Google Code Home & Mercurial Repository</a></li> |
| </ul> |
| <span class="target" id="index-2"></span><p id="index-3">You can checkout the latest development version from the Google Code Mercurial |
| repository with the following command:</p> |
| <blockquote> |
| <div><tt class="docutils literal"><span class="pre">hg</span> <span class="pre">clone</span> <span class="pre">https://mock.googlecode.com/hg/</span> <span class="pre">mock</span></tt></div></blockquote> |
| <span class="target" id="index-4"></span><span class="target" id="index-5"></span><p id="index-6">If you have pip, setuptools or distribute you can install mock with:</p> |
| <blockquote> |
| <div><div class="line-block"> |
| <div class="line"><tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">-U</span> <span class="pre">mock</span></tt></div> |
| <div class="line"><tt class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-U</span> <span class="pre">mock</span></tt></div> |
| </div> |
| </div></blockquote> |
| <p>Alternatively you can download the mock distribution from PyPI and after |
| unpacking run:</p> |
| <blockquote> |
| <div><tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></tt></div></blockquote> |
| </div> |
| <div class="section" id="quick-guide"> |
| <h2>Quick Guide<a class="headerlink" href="#quick-guide" title="Permalink to this headline">¶</a></h2> |
| <p><a class="reference internal" href="mock.html#mock.Mock" title="mock.Mock"><tt class="xref py py-class docutils literal"><span class="pre">Mock</span></tt></a> and <a class="reference internal" href="magicmock.html#mock.MagicMock" title="mock.MagicMock"><tt class="xref py py-class docutils literal"><span class="pre">MagicMock</span></tt></a> objects create all attributes and |
| methods as you access them and store details of how they have been used. You |
| can configure them, to specify return values or limit what attributes are |
| available, and then make assertions about how they have been used:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">MagicMock</span> |
| <span class="gp">>>> </span><span class="n">thing</span> <span class="o">=</span> <span class="n">ProductionClass</span><span class="p">()</span> |
| <span class="gp">>>> </span><span class="n">thing</span><span class="o">.</span><span class="n">method</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span> |
| <span class="gp">>>> </span><span class="n">thing</span><span class="o">.</span><span class="n">method</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s">'value'</span><span class="p">)</span> |
| <span class="go">3</span> |
| <span class="gp">>>> </span><span class="n">thing</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s">'value'</span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p><tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt> allows you to perform side effects, including raising an |
| exception when a mock is called:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="ne">KeyError</span><span class="p">(</span><span class="s">'foo'</span><span class="p">))</span> |
| <span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span> |
| <span class="gt">Traceback (most recent call last):</span> |
| <span class="c">...</span> |
| <span class="gr">KeyError</span>: <span class="n">'foo'</span> |
| |
| <span class="gp">>>> </span><span class="n">values</span> <span class="o">=</span> <span class="p">{</span><span class="s">'a'</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s">'b'</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="s">'c'</span><span class="p">:</span> <span class="mi">3</span><span class="p">}</span> |
| <span class="gp">>>> </span><span class="k">def</span> <span class="nf">side_effect</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span> |
| <span class="gp">... </span> <span class="k">return</span> <span class="n">values</span><span class="p">[</span><span class="n">arg</span><span class="p">]</span> |
| <span class="gp">...</span> |
| <span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">side_effect</span> |
| <span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'a'</span><span class="p">),</span> <span class="n">mock</span><span class="p">(</span><span class="s">'b'</span><span class="p">),</span> <span class="n">mock</span><span class="p">(</span><span class="s">'c'</span><span class="p">)</span> |
| <span class="go">(1, 2, 3)</span> |
| <span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="p">[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span> |
| <span class="gp">>>> </span><span class="n">mock</span><span class="p">(),</span> <span class="n">mock</span><span class="p">(),</span> <span class="n">mock</span><span class="p">()</span> |
| <span class="go">(5, 4, 3)</span> |
| </pre></div> |
| </div> |
| <p>Mock has many other ways you can configure it and control its behaviour. For |
| example the <cite>spec</cite> argument configures the mock to take its specification |
| from another object. Attempting to access attributes or methods on the mock |
| that don’t exist on the spec will fail with an <cite>AttributeError</cite>.</p> |
| <p>The <a class="reference internal" href="patch.html#mock.patch" title="mock.patch"><tt class="xref py py-func docutils literal"><span class="pre">patch()</span></tt></a> decorator / context manager makes it easy to mock classes or |
| objects in a module under test. The object you specify will be replaced with a |
| mock (or other object) during the test and restored when the test ends:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">patch</span> |
| <span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'module.ClassName2'</span><span class="p">)</span> |
| <span class="gp">... </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'module.ClassName1'</span><span class="p">)</span> |
| <span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">MockClass1</span><span class="p">,</span> <span class="n">MockClass2</span><span class="p">):</span> |
| <span class="gp">... </span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName1</span><span class="p">()</span> |
| <span class="gp">... </span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName2</span><span class="p">()</span> |
| |
| <span class="gp">... </span> <span class="k">assert</span> <span class="n">MockClass1</span> <span class="ow">is</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName1</span> |
| <span class="gp">... </span> <span class="k">assert</span> <span class="n">MockClass2</span> <span class="ow">is</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName2</span> |
| <span class="gp">... </span> <span class="k">assert</span> <span class="n">MockClass1</span><span class="o">.</span><span class="n">called</span> |
| <span class="gp">... </span> <span class="k">assert</span> <span class="n">MockClass2</span><span class="o">.</span><span class="n">called</span> |
| <span class="gp">...</span> |
| <span class="gp">>>> </span><span class="n">test</span><span class="p">()</span> |
| </pre></div> |
| </div> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <p>When you nest patch decorators the mocks are passed in to the decorated |
| function in the same order they applied (the normal <em>python</em> order that |
| decorators are applied). This means from the bottom up, so in the example |
| above the mock for <cite>module.ClassName1</cite> is passed in first.</p> |
| <p class="last">With <cite>patch</cite> it matters that you patch objects in the namespace where they |
| are looked up. This is normally straightforward, but for a quick guide |
| read <a class="reference internal" href="patch.html#where-to-patch"><em>where to patch</em></a>.</p> |
| </div> |
| <p>As well as a decorator <cite>patch</cite> can be used as a context manager in a with |
| statement:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">object</span><span class="p">(</span><span class="n">ProductionClass</span><span class="p">,</span> <span class="s">'method'</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_method</span><span class="p">:</span> |
| <span class="gp">... </span> <span class="n">thing</span> <span class="o">=</span> <span class="n">ProductionClass</span><span class="p">()</span> |
| <span class="gp">... </span> <span class="n">thing</span><span class="o">.</span><span class="n">method</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> |
| <span class="gp">...</span> |
| <span class="gp">>>> </span><span class="n">mock_method</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> |
| </pre></div> |
| </div> |
| <p>There is also <a class="reference internal" href="patch.html#mock.patch.dict" title="mock.patch.dict"><tt class="xref py py-func docutils literal"><span class="pre">patch.dict()</span></tt></a> for setting values in a dictionary just |
| during a scope and restoring the dictionary to its original state when the test |
| ends:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">foo</span> <span class="o">=</span> <span class="p">{</span><span class="s">'key'</span><span class="p">:</span> <span class="s">'value'</span><span class="p">}</span> |
| <span class="gp">>>> </span><span class="n">original</span> <span class="o">=</span> <span class="n">foo</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span> |
| <span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="n">foo</span><span class="p">,</span> <span class="p">{</span><span class="s">'newkey'</span><span class="p">:</span> <span class="s">'newvalue'</span><span class="p">},</span> <span class="n">clear</span><span class="o">=</span><span class="bp">True</span><span class="p">):</span> |
| <span class="gp">... </span> <span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{</span><span class="s">'newkey'</span><span class="p">:</span> <span class="s">'newvalue'</span><span class="p">}</span> |
| <span class="gp">...</span> |
| <span class="gp">>>> </span><span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="n">original</span> |
| </pre></div> |
| </div> |
| <p>Mock supports the mocking of Python <a class="reference internal" href="magicmock.html#magic-methods"><em>magic methods</em></a>. The |
| easiest way of using magic methods is with the <a class="reference internal" href="magicmock.html#mock.MagicMock" title="mock.MagicMock"><tt class="xref py py-class docutils literal"><span class="pre">MagicMock</span></tt></a> class. It |
| allows you to do things like:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span> |
| <span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__str__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s">'foobarbaz'</span> |
| <span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span> |
| <span class="go">'foobarbaz'</span> |
| <span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__str__</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">()</span> |
| </pre></div> |
| </div> |
| <p>Mock allows you to assign functions (or other Mock instances) to magic methods |
| and they will be called appropriately. The <cite>MagicMock</cite> class is just a Mock |
| variant that has all of the magic methods pre-created for you (well, all the |
| useful ones anyway).</p> |
| <p>The following is an example of using magic methods with the ordinary Mock |
| class:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">()</span> |
| <span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__str__</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="s">'wheeeeee'</span><span class="p">)</span> |
| <span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span> |
| <span class="go">'wheeeeee'</span> |
| </pre></div> |
| </div> |
| <p>For ensuring that the mock objects in your tests have the same api as the |
| objects they are replacing, you can use <a class="reference internal" href="helpers.html#auto-speccing"><em>auto-speccing</em></a>. |
| Auto-speccing can be done through the <cite>autospec</cite> argument to patch, or the |
| <a class="reference internal" href="helpers.html#mock.create_autospec" title="mock.create_autospec"><tt class="xref py py-func docutils literal"><span class="pre">create_autospec()</span></tt></a> function. Auto-speccing creates mock objects that |
| have the same attributes and methods as the objects they are replacing, and |
| any functions and methods (including constructors) have the same call |
| signature as the real object.</p> |
| <p>This ensures that your mocks will fail in the same way as your production |
| code if they are used incorrectly:</p> |
| <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">create_autospec</span> |
| <span class="gp">>>> </span><span class="k">def</span> <span class="nf">function</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">):</span> |
| <span class="gp">... </span> <span class="k">pass</span> |
| <span class="gp">...</span> |
| <span class="gp">>>> </span><span class="n">mock_function</span> <span class="o">=</span> <span class="n">create_autospec</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="s">'fishy'</span><span class="p">)</span> |
| <span class="gp">>>> </span><span class="n">mock_function</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> |
| <span class="go">'fishy'</span> |
| <span class="gp">>>> </span><span class="n">mock_function</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> |
| <span class="gp">>>> </span><span class="n">mock_function</span><span class="p">(</span><span class="s">'wrong arguments'</span><span class="p">)</span> |
| <span class="gt">Traceback (most recent call last):</span> |
| <span class="c">...</span> |
| <span class="gr">TypeError</span>: <span class="n"><lambda>() takes exactly 3 arguments (1 given)</span> |
| </pre></div> |
| </div> |
| <p><cite>create_autospec</cite> can also be used on classes, where it copies the signature of |
| the <cite>__init__</cite> method, and on callable objects where it copies the signature of |
| the <cite>__call__</cite> method.</p> |
| <span class="target" id="index-7"></span></div> |
| <div class="section" id="references"> |
| <span id="index-8"></span><h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2> |
| <p>Articles, blog entries and other stuff related to testing with Mock:</p> |
| <ul class="simple"> |
| <li><a class="reference external" href="https://github.com/carljm/django-testing-slides/blob/master/models/30_no_database.md">Imposing a No DB Discipline on Django unit tests</a></li> |
| <li><a class="reference external" href="https://github.com/dcramer/mock-django">mock-django: tools for mocking the Django ORM and models</a></li> |
| <li><a class="reference external" href="https://blip.tv/file/4881513">PyCon 2011 Video: Testing with mock</a></li> |
| <li><a class="reference external" href="http://noopenblockers.com/2012/01/06/mock-objects-in-python/">Mock objects in Python</a></li> |
| <li><a class="reference external" href="http://blueprintforge.com/blog/2012/01/08/python-injecting-mock-objects-for-powerful-testing/">Python: Injecting Mock Objects for Powerful Testing</a></li> |
| <li><a class="reference external" href="http://www.michaelpollmeier.com/python-mock-how-to-assert-a-substring-of-logger-output/">Python Mock: How to assert a substring of logger output</a></li> |
| <li><a class="reference external" href="http://www.mattjmorrison.com/2011/09/mocking-django.html">Mocking Django</a></li> |
| <li><a class="reference external" href="http://williamjohnbert.com/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/">Mocking dates and other classes that can’t be modified</a></li> |
| <li><a class="reference external" href="http://konryd.blogspot.com/2010/06/mock-recipies.html">Mock recipes</a></li> |
| <li><a class="reference external" href="http://konryd.blogspot.com/2010/05/mockity-mock-mock-some-love-for-mock.html">Mockity mock mock - some love for the mock module</a></li> |
| <li><a class="reference external" href="http://mattsnider.com/python/mock-and-coverage/">Coverage and Mock (with django)</a></li> |
| <li><a class="reference external" href="http://www.insomnihack.com/?p=194">Python Unit Testing with Mock</a></li> |
| <li><a class="reference external" href="http://myadventuresincoding.wordpress.com/2011/02/26/python-python-mock-cheat-sheet/">Getting started with Python Mock</a></li> |
| <li><a class="reference external" href="http://tobyho.com/2011/03/24/smart-parameter-checks-in/">Smart Parameter Checks with mock</a></li> |
| <li><a class="reference external" href="http://agiletesting.blogspot.com/2009/07/python-mock-testing-techniques-and.html">Python mock testing techniques and tools</a></li> |
| <li><a class="reference external" href="http://techblog.ironfroggy.com/2008/10/how-to-test.html">How To Test Django Template Tags</a></li> |
| <li><a class="reference external" href="http://pypap.blogspot.com/2008/10/newbie-nugget-unit-testing-with-mock.html">A presentation on Unit Testing with Mock</a></li> |
| <li><a class="reference external" href="http://michael-a-nelson.blogspot.com/2008/09/mocking-with-django-and-google-app.html">Mocking with Django and Google AppEngine</a></li> |
| </ul> |
| <span class="target" id="index-9"></span></div> |
| <div class="section" id="tests"> |
| <span id="index-10"></span><h2>Tests<a class="headerlink" href="#tests" title="Permalink to this headline">¶</a></h2> |
| <p>Mock uses <a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest2</a> for its own |
| test suite. In order to run it, use the <cite>unit2</cite> script that comes with |
| <cite>unittest2</cite> module on a checkout of the source repository:</p> |
| <blockquote> |
| <div><cite>unit2 discover</cite></div></blockquote> |
| <p>If you have <a class="reference external" href="http://pypi.python.org/pypi/distribute">setuptools</a> as well as |
| unittest2 you can run:</p> |
| <blockquote> |
| <div><tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">test</span></tt></div></blockquote> |
| <p>On Python 3.2 you can use <tt class="docutils literal"><span class="pre">unittest</span></tt> module from the standard library.</p> |
| <blockquote> |
| <div><tt class="docutils literal"><span class="pre">python3.2</span> <span class="pre">-m</span> <span class="pre">unittest</span> <span class="pre">discover</span></tt></div></blockquote> |
| <p id="index-11">On Python 3 the tests for unicode are skipped as they are not relevant. On |
| Python 2.4 tests that use the with statements are skipped as the with statement |
| is invalid syntax on Python 2.4.</p> |
| </div> |
| <div class="section" id="older-versions"> |
| <span id="index-12"></span><h2>Older Versions<a class="headerlink" href="#older-versions" title="Permalink to this headline">¶</a></h2> |
| <p>Documentation for older versions of mock:</p> |
| <ul class="simple"> |
| <li><a class="reference external" href="http://www.voidspace.org.uk/python/mock/0.8/">mock 0.8</a></li> |
| <li><a class="reference external" href="http://www.voidspace.org.uk/python/mock/0.7/">mock 0.7</a></li> |
| <li><a class="reference external" href="http://www.voidspace.org.uk/python/mock/0.6.0/">mock 0.6</a></li> |
| </ul> |
| <p>Docs from the in-development version of <cite>mock</cite> can be found at |
| <a class="reference external" href="http://mock.readthedocs.org">mock.readthedocs.org</a>.</p> |
| </div> |
| <div class="section" id="terminology"> |
| <h2>Terminology<a class="headerlink" href="#terminology" title="Permalink to this headline">¶</a></h2> |
| <p>Terminology for objects used to replace other ones can be confusing. Terms |
| like double, fake, mock, stub, and spy are all used with varying meanings.</p> |
| <p>In <a class="reference external" href="http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html">classic mock terminology</a> |
| <a class="reference internal" href="mock.html#mock.Mock" title="mock.Mock"><tt class="xref py py-class docutils literal"><span class="pre">mock.Mock</span></tt></a> is a <a class="reference external" href="http://xunitpatterns.com/Test%20Spy.html">spy</a> that |
| allows for <em>post-mortem</em> examination. This is what I call the “action -> |
| assertion” <a class="footnote-reference" href="#id2" id="id1">[1]</a> pattern of testing.</p> |
| <p>I’m not however a fan of this “statically typed mocking terminology” |
| promulgated by <a class="reference external" href="http://martinfowler.com/articles/mocksArentStubs.html">Martin Fowler</a>. It confuses usage |
| patterns with implementation and prevents you from using natural terminology |
| when discussing mocking.</p> |
| <p>I much prefer duck typing, if an object used in your test suite looks like a |
| mock object and quacks like a mock object then it’s fine to call it a mock, no |
| matter what the implementation looks like.</p> |
| <p>This terminology is perhaps more useful in less capable languages where |
| different usage patterns will <em>require</em> different implementations. |
| <cite>mock.Mock()</cite> is capable of being used in most of the different roles |
| described by Fowler, except (annoyingly / frustratingly / ironically) a Mock |
| itself!</p> |
| <p>How about a simpler definition: a “mock object” is an object used to replace a |
| real one in a system under test.</p> |
| <table class="docutils footnote" frame="void" id="id2" rules="none"> |
| <colgroup><col class="label" /><col /></colgroup> |
| <tbody valign="top"> |
| <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>This pattern is called “AAA” by some members of the testing community; |
| “Arrange - Act - Assert”.</td></tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar"> |
| <div class="sphinxsidebarwrapper"> |
| <h3><a href="#">Table Of Contents</a></h3> |
| <ul> |
| <li><a class="reference internal" href="#">Mock - Mocking and Testing Library</a><ul> |
| <li><a class="reference internal" href="#api-documentation">API Documentation</a><ul> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#user-guide">User Guide</a><ul> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#installing">Installing</a></li> |
| <li><a class="reference internal" href="#quick-guide">Quick Guide</a></li> |
| <li><a class="reference internal" href="#references">References</a></li> |
| <li><a class="reference internal" href="#tests">Tests</a></li> |
| <li><a class="reference internal" href="#older-versions">Older Versions</a></li> |
| <li><a class="reference internal" href="#terminology">Terminology</a></li> |
| </ul> |
| </li> |
| </ul> |
| |
| <h4>Next topic</h4> |
| <p class="topless"><a href="mock.html" |
| title="next chapter">The Mock Class</a></p> |
| <h3>This Page</h3> |
| <ul class="this-page-menu"> |
| <li><a href="_sources/index.txt" |
| rel="nofollow">Show Source</a></li> |
| </ul> |
| <div id="searchbox" style="display: none"> |
| <h3>Quick search</h3> |
| <form class="search" action="search.html" method="get"> |
| <input type="text" name="q" /> |
| <input type="submit" value="Go" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| <p class="searchtip" style="font-size: 90%"> |
| Enter search terms or a module, class or function name. |
| </p> |
| </div> |
| <script type="text/javascript">$('#searchbox').show(0);</script> |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="related"> |
| <h3>Navigation</h3> |
| <ul> |
| <li class="right" style="margin-right: 10px"> |
| <a href="genindex.html" title="General Index" |
| >index</a></li> |
| <li class="right" > |
| <a href="mock.html" title="The Mock Class" |
| >next</a> |</li> |
| <li><a href="#">Mock 1.0.0 documentation</a> »</li> |
| </ul> |
| </div> |
| <div class="footer"> |
| © Copyright 2007-2012, Michael Foord & the mock team. |
| Last updated on Oct 07, 2012. |
| Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3. |
| </div> |
| </body> |
| </html> |
