1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/python/mock-1.0.0/html/examples.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1006 @@
1.4 +
1.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +
1.8 +
1.9 +<html xmlns="http://www.w3.org/1999/xhtml">
1.10 + <head>
1.11 + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1.12 +
1.13 + <title>Further Examples — Mock 1.0.0 documentation</title>
1.14 +
1.15 + <link rel="stylesheet" href="_static/nature.css" type="text/css" />
1.16 + <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
1.17 +
1.18 + <script type="text/javascript">
1.19 + var DOCUMENTATION_OPTIONS = {
1.20 + URL_ROOT: '',
1.21 + VERSION: '1.0.0',
1.22 + COLLAPSE_INDEX: false,
1.23 + FILE_SUFFIX: '.html',
1.24 + HAS_SOURCE: true
1.25 + };
1.26 + </script>
1.27 + <script type="text/javascript" src="_static/jquery.js"></script>
1.28 + <script type="text/javascript" src="_static/underscore.js"></script>
1.29 + <script type="text/javascript" src="_static/doctools.js"></script>
1.30 + <link rel="top" title="Mock 1.0.0 documentation" href="index.html" />
1.31 + <link rel="next" title="Mock Library Comparison" href="compare.html" />
1.32 + <link rel="prev" title="Getting Started with Mock" href="getting-started.html" />
1.33 + </head>
1.34 + <body>
1.35 + <div class="related">
1.36 + <h3>Navigation</h3>
1.37 + <ul>
1.38 + <li class="right" style="margin-right: 10px">
1.39 + <a href="genindex.html" title="General Index"
1.40 + accesskey="I">index</a></li>
1.41 + <li class="right" >
1.42 + <a href="compare.html" title="Mock Library Comparison"
1.43 + accesskey="N">next</a> |</li>
1.44 + <li class="right" >
1.45 + <a href="getting-started.html" title="Getting Started with Mock"
1.46 + accesskey="P">previous</a> |</li>
1.47 + <li><a href="index.html">Mock 1.0.0 documentation</a> »</li>
1.48 + </ul>
1.49 + </div>
1.50 +
1.51 + <div class="document">
1.52 + <div class="documentwrapper">
1.53 + <div class="bodywrapper">
1.54 + <div class="body">
1.55 +
1.56 + <div class="section" id="further-examples">
1.57 +<span id="id1"></span><h1>Further Examples<a class="headerlink" href="#further-examples" title="Permalink to this headline">¶</a></h1>
1.58 +<p>For comprehensive examples, see the unit tests included in the full source
1.59 +distribution.</p>
1.60 +<p>Here are some more examples for some slightly more advanced scenarios than in
1.61 +the <a class="reference internal" href="getting-started.html#getting-started"><em>getting started</em></a> guide.</p>
1.62 +<div class="section" id="mocking-chained-calls">
1.63 +<h2>Mocking chained calls<a class="headerlink" href="#mocking-chained-calls" title="Permalink to this headline">¶</a></h2>
1.64 +<p>Mocking chained calls is actually straightforward with mock once you
1.65 +understand the <a class="reference internal" href="mock.html#mock.Mock.return_value" title="mock.Mock.return_value"><tt class="xref py py-attr docutils literal"><span class="pre">return_value</span></tt></a> attribute. When a mock is called for
1.66 +the first time, or you fetch its <cite>return_value</cite> before it has been called, a
1.67 +new <cite>Mock</cite> is created.</p>
1.68 +<p>This means that you can see how the object returned from a call to a mocked
1.69 +object has been used by interrogating the <cite>return_value</cite> mock:</p>
1.70 +<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>
1.71 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span><span class="o">.</span><span class="n">foo</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
1.72 +<span class="go"><Mock name='mock().foo()' id='...'></span>
1.73 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">return_value</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
1.74 +</pre></div>
1.75 +</div>
1.76 +<p>From here it is a simple step to configure and then make assertions about
1.77 +chained calls. Of course another alternative is writing your code in a more
1.78 +testable way in the first place...</p>
1.79 +<p>So, suppose we have some code that looks a little bit like this:</p>
1.80 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Something</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
1.81 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.82 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">backend</span> <span class="o">=</span> <span class="n">BackendProvider</span><span class="p">()</span>
1.83 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">method</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.84 +<span class="gp">... </span> <span class="n">response</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">backend</span><span class="o">.</span><span class="n">get_endpoint</span><span class="p">(</span><span class="s">'foobar'</span><span class="p">)</span><span class="o">.</span><span class="n">create_call</span><span class="p">(</span><span class="s">'spam'</span><span class="p">,</span> <span class="s">'eggs'</span><span class="p">)</span><span class="o">.</span><span class="n">start_call</span><span class="p">()</span>
1.85 +<span class="gp">... </span> <span class="c"># more code</span>
1.86 +</pre></div>
1.87 +</div>
1.88 +<p>Assuming that <cite>BackendProvider</cite> is already well tested, how do we test
1.89 +<cite>method()</cite>? Specifically, we want to test that the code section <cite># more
1.90 +code</cite> uses the response object in the correct way.</p>
1.91 +<p>As this chain of calls is made from an instance attribute we can monkey patch
1.92 +the <cite>backend</cite> attribute on a <cite>Something</cite> instance. In this particular case
1.93 +we are only interested in the return value from the final call to
1.94 +<cite>start_call</cite> so we don’t have much configuration to do. Let’s assume the
1.95 +object it returns is ‘file-like’, so we’ll ensure that our response object
1.96 +uses the builtin <cite>file</cite> as its <cite>spec</cite>.</p>
1.97 +<p>To do this we create a mock instance as our mock backend and create a mock
1.98 +response object for it. To set the response as the return value for that final
1.99 +<cite>start_call</cite> we could do this:</p>
1.100 +<blockquote>
1.101 +<div><cite>mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response</cite>.</div></blockquote>
1.102 +<p>We can do that in a slightly nicer way using the <a class="reference internal" href="mock.html#mock.Mock.configure_mock" title="mock.Mock.configure_mock"><tt class="xref py py-meth docutils literal"><span class="pre">configure_mock()</span></tt></a>
1.103 +method to directly set the return value for us:</p>
1.104 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">something</span> <span class="o">=</span> <span class="n">Something</span><span class="p">()</span>
1.105 +<span class="gp">>>> </span><span class="n">mock_response</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">spec</span><span class="o">=</span><span class="nb">file</span><span class="p">)</span>
1.106 +<span class="gp">>>> </span><span class="n">mock_backend</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">()</span>
1.107 +<span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="p">{</span><span class="s">'get_endpoint.return_value.create_call.return_value.start_call.return_value'</span><span class="p">:</span> <span class="n">mock_response</span><span class="p">}</span>
1.108 +<span class="gp">>>> </span><span class="n">mock_backend</span><span class="o">.</span><span class="n">configure_mock</span><span class="p">(</span><span class="o">**</span><span class="n">config</span><span class="p">)</span>
1.109 +</pre></div>
1.110 +</div>
1.111 +<p>With these we monkey patch the “mock backend” in place and can make the real
1.112 +call:</p>
1.113 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">something</span><span class="o">.</span><span class="n">backend</span> <span class="o">=</span> <span class="n">mock_backend</span>
1.114 +<span class="gp">>>> </span><span class="n">something</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>
1.115 +</pre></div>
1.116 +</div>
1.117 +<p>Using <a class="reference internal" href="mock.html#mock.Mock.mock_calls" title="mock.Mock.mock_calls"><tt class="xref py py-attr docutils literal"><span class="pre">mock_calls</span></tt></a> we can check the chained call with a single
1.118 +assert. A chained call is several calls in one line of code, so there will be
1.119 +several entries in <cite>mock_calls</cite>. We can use <a class="reference internal" href="helpers.html#mock.call.call_list" title="mock.call.call_list"><tt class="xref py py-meth docutils literal"><span class="pre">call.call_list()</span></tt></a> to create
1.120 +this list of calls for us:</p>
1.121 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">chained</span> <span class="o">=</span> <span class="n">call</span><span class="o">.</span><span class="n">get_endpoint</span><span class="p">(</span><span class="s">'foobar'</span><span class="p">)</span><span class="o">.</span><span class="n">create_call</span><span class="p">(</span><span class="s">'spam'</span><span class="p">,</span> <span class="s">'eggs'</span><span class="p">)</span><span class="o">.</span><span class="n">start_call</span><span class="p">()</span>
1.122 +<span class="gp">>>> </span><span class="n">call_list</span> <span class="o">=</span> <span class="n">chained</span><span class="o">.</span><span class="n">call_list</span><span class="p">()</span>
1.123 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">mock_backend</span><span class="o">.</span><span class="n">mock_calls</span> <span class="o">==</span> <span class="n">call_list</span>
1.124 +</pre></div>
1.125 +</div>
1.126 +</div>
1.127 +<div class="section" id="partial-mocking">
1.128 +<h2>Partial mocking<a class="headerlink" href="#partial-mocking" title="Permalink to this headline">¶</a></h2>
1.129 +<p>In some tests I wanted to mock out a call to <a class="reference external" href="http://docs.python.org/library/datetime.html#datetime.date.today">datetime.date.today()</a> to return
1.130 +a known date, but I didn’t want to prevent the code under test from
1.131 +creating new date objects. Unfortunately <cite>datetime.date</cite> is written in C, and
1.132 +so I couldn’t just monkey-patch out the static <cite>date.today</cite> method.</p>
1.133 +<p>I found a simple way of doing this that involved effectively wrapping the date
1.134 +class with a mock, but passing through calls to the constructor to the real
1.135 +class (and returning real instances).</p>
1.136 +<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> <span class="pre">decorator</span></tt></a> is used here to
1.137 +mock out the <cite>date</cite> class in the module under test. The <tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt>
1.138 +attribute on the mock date class is then set to a lambda function that returns
1.139 +a real date. When the mock date class is called a real date will be
1.140 +constructed and returned by <cite>side_effect</cite>.</p>
1.141 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">date</span>
1.142 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.date'</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_date</span><span class="p">:</span>
1.143 +<span class="gp">... </span> <span class="n">mock_date</span><span class="o">.</span><span class="n">today</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">date</span><span class="p">(</span><span class="mi">2010</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">8</span><span class="p">)</span>
1.144 +<span class="gp">... </span> <span class="n">mock_date</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="k">lambda</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">:</span> <span class="n">date</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
1.145 +<span class="gp">...</span>
1.146 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">date</span><span class="o">.</span><span class="n">today</span><span class="p">()</span> <span class="o">==</span> <span class="n">date</span><span class="p">(</span><span class="mi">2010</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">8</span><span class="p">)</span>
1.147 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">date</span><span class="p">(</span><span class="mi">2009</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">8</span><span class="p">)</span> <span class="o">==</span> <span class="n">date</span><span class="p">(</span><span class="mi">2009</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">8</span><span class="p">)</span>
1.148 +<span class="gp">...</span>
1.149 +</pre></div>
1.150 +</div>
1.151 +<p>Note that we don’t patch <cite>datetime.date</cite> globally, we patch <cite>date</cite> in the
1.152 +module that <em>uses</em> it. See <a class="reference internal" href="patch.html#where-to-patch"><em>where to patch</em></a>.</p>
1.153 +<p>When <cite>date.today()</cite> is called a known date is returned, but calls to the
1.154 +<cite>date(...)</cite> constructor still return normal dates. Without this you can find
1.155 +yourself having to calculate an expected result using exactly the same
1.156 +algorithm as the code under test, which is a classic testing anti-pattern.</p>
1.157 +<p>Calls to the date constructor are recorded in the <cite>mock_date</cite> attributes
1.158 +(<cite>call_count</cite> and friends) which may also be useful for your tests.</p>
1.159 +<p>An alternative way of dealing with mocking dates, or other builtin classes,
1.160 +is discussed in <a class="reference external" href="http://williamjohnbert.com/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/">this blog entry</a>.</p>
1.161 +</div>
1.162 +<div class="section" id="mocking-a-generator-method">
1.163 +<h2>Mocking a Generator Method<a class="headerlink" href="#mocking-a-generator-method" title="Permalink to this headline">¶</a></h2>
1.164 +<p>A Python generator is a function or method that uses the <a class="reference external" href="http://docs.python.org/reference/simple_stmts.html#the-yield-statement">yield statement</a> to
1.165 +return a series of values when iterated over <a class="footnote-reference" href="#id3" id="id2">[1]</a>.</p>
1.166 +<p>A generator method / function is called to return the generator object. It is
1.167 +the generator object that is then iterated over. The protocol method for
1.168 +iteration is <a class="reference external" href="http://docs.python.org/library/stdtypes.html#container.__iter__">__iter__</a>, so we can
1.169 +mock this using a <cite>MagicMock</cite>.</p>
1.170 +<p>Here’s an example class with an “iter” method implemented as a generator:</p>
1.171 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
1.172 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">iter</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.173 +<span class="gp">... </span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</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>
1.174 +<span class="gp">... </span> <span class="k">yield</span> <span class="n">i</span>
1.175 +<span class="gp">...</span>
1.176 +<span class="gp">>>> </span><span class="n">foo</span> <span class="o">=</span> <span class="n">Foo</span><span class="p">()</span>
1.177 +<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">foo</span><span class="o">.</span><span class="n">iter</span><span class="p">())</span>
1.178 +<span class="go">[1, 2, 3]</span>
1.179 +</pre></div>
1.180 +</div>
1.181 +<p>How would we mock this class, and in particular its “iter” method?</p>
1.182 +<p>To configure the values returned from the iteration (implicit in the call to
1.183 +<cite>list</cite>), we need to configure the object returned by the call to <cite>foo.iter()</cite>.</p>
1.184 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock_foo</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.185 +<span class="gp">>>> </span><span class="n">mock_foo</span><span class="o">.</span><span class="n">iter</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="nb">iter</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>
1.186 +<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">mock_foo</span><span class="o">.</span><span class="n">iter</span><span class="p">())</span>
1.187 +<span class="go">[1, 2, 3]</span>
1.188 +</pre></div>
1.189 +</div>
1.190 +<table class="docutils footnote" frame="void" id="id3" rules="none">
1.191 +<colgroup><col class="label" /><col /></colgroup>
1.192 +<tbody valign="top">
1.193 +<tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>There are also generator expressions and more <a class="reference external" href="http://www.dabeaz.com/coroutines/index.html">advanced uses</a> of generators, but we aren’t
1.194 +concerned about them here. A very good introduction to generators and how
1.195 +powerful they are is: <a class="reference external" href="http://www.dabeaz.com/generators/">Generator Tricks for Systems Programmers</a>.</td></tr>
1.196 +</tbody>
1.197 +</table>
1.198 +</div>
1.199 +<div class="section" id="applying-the-same-patch-to-every-test-method">
1.200 +<h2>Applying the same patch to every test method<a class="headerlink" href="#applying-the-same-patch-to-every-test-method" title="Permalink to this headline">¶</a></h2>
1.201 +<p>If you want several patches in place for multiple test methods the obvious way
1.202 +is to apply the patch decorators to every method. This can feel like unnecessary
1.203 +repetition. For Python 2.6 or more recent you can use <cite>patch</cite> (in all its
1.204 +various forms) as a class decorator. This applies the patches to all test
1.205 +methods on the class. A test method is identified by methods whose names start
1.206 +with <cite>test</cite>:</p>
1.207 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'mymodule.SomeClass'</span><span class="p">)</span>
1.208 +<span class="gp">... </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
1.209 +<span class="gp">...</span>
1.210 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">test_one</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">MockSomeClass</span><span class="p">):</span>
1.211 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">assertTrue</span><span class="p">(</span><span class="n">mymodule</span><span class="o">.</span><span class="n">SomeClass</span> <span class="ow">is</span> <span class="n">MockSomeClass</span><span class="p">)</span>
1.212 +<span class="gp">...</span>
1.213 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">test_two</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">MockSomeClass</span><span class="p">):</span>
1.214 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">assertTrue</span><span class="p">(</span><span class="n">mymodule</span><span class="o">.</span><span class="n">SomeClass</span> <span class="ow">is</span> <span class="n">MockSomeClass</span><span class="p">)</span>
1.215 +<span class="gp">...</span>
1.216 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">not_a_test</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.217 +<span class="gp">... </span> <span class="k">return</span> <span class="s">'something'</span>
1.218 +<span class="gp">...</span>
1.219 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_one'</span><span class="p">)</span><span class="o">.</span><span class="n">test_one</span><span class="p">()</span>
1.220 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_two'</span><span class="p">)</span><span class="o">.</span><span class="n">test_two</span><span class="p">()</span>
1.221 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_two'</span><span class="p">)</span><span class="o">.</span><span class="n">not_a_test</span><span class="p">()</span>
1.222 +<span class="go">'something'</span>
1.223 +</pre></div>
1.224 +</div>
1.225 +<p>An alternative way of managing patches is to use the <a class="reference internal" href="patch.html#start-and-stop"><em>patch methods: start and stop</em></a>.
1.226 +These allow you to move the patching into your <cite>setUp</cite> and <cite>tearDown</cite> methods.</p>
1.227 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
1.228 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.229 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.foo'</span><span class="p">)</span>
1.230 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">mock_foo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.231 +<span class="gp">...</span>
1.232 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">test_foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.233 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">assertTrue</span><span class="p">(</span><span class="n">mymodule</span><span class="o">.</span><span class="n">foo</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">mock_foo</span><span class="p">)</span>
1.234 +<span class="gp">...</span>
1.235 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">tearDown</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.236 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>
1.237 +<span class="gp">...</span>
1.238 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_foo'</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
1.239 +</pre></div>
1.240 +</div>
1.241 +<p>If you use this technique you must ensure that the patching is “undone” by
1.242 +calling <cite>stop</cite>. This can be fiddlier than you might think, because if an
1.243 +exception is raised in the setUp then tearDown is not called. <a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest2</a> cleanup functions make this simpler:</p>
1.244 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
1.245 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.246 +<span class="gp">... </span> <span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.foo'</span><span class="p">)</span>
1.247 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">addCleanup</span><span class="p">(</span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">)</span>
1.248 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">mock_foo</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.249 +<span class="gp">...</span>
1.250 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">test_foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.251 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">assertTrue</span><span class="p">(</span><span class="n">mymodule</span><span class="o">.</span><span class="n">foo</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">mock_foo</span><span class="p">)</span>
1.252 +<span class="gp">...</span>
1.253 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_foo'</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
1.254 +</pre></div>
1.255 +</div>
1.256 +</div>
1.257 +<div class="section" id="mocking-unbound-methods">
1.258 +<h2>Mocking Unbound Methods<a class="headerlink" href="#mocking-unbound-methods" title="Permalink to this headline">¶</a></h2>
1.259 +<p>Whilst writing tests today I needed to patch an <em>unbound method</em> (patching the
1.260 +method on the class rather than on the instance). I needed self to be passed
1.261 +in as the first argument because I want to make asserts about which objects
1.262 +were calling this particular method. The issue is that you can’t patch with a
1.263 +mock for this, because if you replace an unbound method with a mock it doesn’t
1.264 +become a bound method when fetched from the instance, and so it doesn’t get
1.265 +self passed in. The workaround is to patch the unbound method with a real
1.266 +function instead. 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 makes it so simple to
1.267 +patch out methods with a mock that having to create a real function becomes a
1.268 +nuisance.</p>
1.269 +<p>If you pass <cite>autospec=True</cite> to patch then it does the patching with a
1.270 +<em>real</em> function object. This function object has the same signature as the one
1.271 +it is replacing, but delegates to a mock under the hood. You still get your
1.272 +mock auto-created in exactly the same way as before. What it means though, is
1.273 +that if you use it to patch out an unbound method on a class the mocked
1.274 +function will be turned into a bound method if it is fetched from an instance.
1.275 +It will have <cite>self</cite> passed in as the first argument, which is exactly what I
1.276 +wanted:</p>
1.277 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
1.278 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.279 +<span class="gp">... </span> <span class="k">pass</span>
1.280 +<span class="gp">...</span>
1.281 +<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">Foo</span><span class="p">,</span> <span class="s">'foo'</span><span class="p">,</span> <span class="n">autospec</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_foo</span><span class="p">:</span>
1.282 +<span class="gp">... </span> <span class="n">mock_foo</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s">'foo'</span>
1.283 +<span class="gp">... </span> <span class="n">foo</span> <span class="o">=</span> <span class="n">Foo</span><span class="p">()</span>
1.284 +<span class="gp">... </span> <span class="n">foo</span><span class="o">.</span><span class="n">foo</span><span class="p">()</span>
1.285 +<span class="gp">...</span>
1.286 +<span class="go">'foo'</span>
1.287 +<span class="gp">>>> </span><span class="n">mock_foo</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="n">foo</span><span class="p">)</span>
1.288 +</pre></div>
1.289 +</div>
1.290 +<p>If we don’t use <cite>autospec=True</cite> then the unbound method is patched out
1.291 +with a Mock instance instead, and isn’t called with <cite>self</cite>.</p>
1.292 +</div>
1.293 +<div class="section" id="checking-multiple-calls-with-mock">
1.294 +<h2>Checking multiple calls with mock<a class="headerlink" href="#checking-multiple-calls-with-mock" title="Permalink to this headline">¶</a></h2>
1.295 +<p>mock has a nice API for making assertions about how your mock objects are used.</p>
1.296 +<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>
1.297 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">foo_bar</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="bp">None</span>
1.298 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">foo_bar</span><span class="p">(</span><span class="s">'baz'</span><span class="p">,</span> <span class="n">spam</span><span class="o">=</span><span class="s">'eggs'</span><span class="p">)</span>
1.299 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">foo_bar</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="s">'baz'</span><span class="p">,</span> <span class="n">spam</span><span class="o">=</span><span class="s">'eggs'</span><span class="p">)</span>
1.300 +</pre></div>
1.301 +</div>
1.302 +<p>If your mock is only being called once you can use the
1.303 +<tt class="xref py py-meth docutils literal"><span class="pre">assert_called_once_with()</span></tt> method that also asserts that the
1.304 +<tt class="xref py py-attr docutils literal"><span class="pre">call_count</span></tt> is one.</p>
1.305 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">foo_bar</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s">'baz'</span><span class="p">,</span> <span class="n">spam</span><span class="o">=</span><span class="s">'eggs'</span><span class="p">)</span>
1.306 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">foo_bar</span><span class="p">()</span>
1.307 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">foo_bar</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s">'baz'</span><span class="p">,</span> <span class="n">spam</span><span class="o">=</span><span class="s">'eggs'</span><span class="p">)</span>
1.308 +<span class="gt">Traceback (most recent call last):</span>
1.309 + <span class="o">...</span>
1.310 +<span class="gr">AssertionError</span>: <span class="n">Expected to be called once. Called 2 times.</span>
1.311 +</pre></div>
1.312 +</div>
1.313 +<p>Both <cite>assert_called_with</cite> and <cite>assert_called_once_with</cite> make assertions about
1.314 +the <em>most recent</em> call. If your mock is going to be called several times, and
1.315 +you want to make assertions about <em>all</em> those calls you can use
1.316 +<a class="reference internal" href="mock.html#mock.Mock.call_args_list" title="mock.Mock.call_args_list"><tt class="xref py py-attr docutils literal"><span class="pre">call_args_list</span></tt></a>:</p>
1.317 +<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">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
1.318 +<span class="gp">>>> </span><span class="n">mock</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>
1.319 +<span class="gp">>>> </span><span class="n">mock</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="mi">6</span><span class="p">)</span>
1.320 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.321 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args_list</span>
1.322 +<span class="go">[call(1, 2, 3), call(4, 5, 6), call()]</span>
1.323 +</pre></div>
1.324 +</div>
1.325 +<p>The <a class="reference internal" href="helpers.html#mock.call" title="mock.call"><tt class="xref py py-data docutils literal"><span class="pre">call</span></tt></a> helper makes it easy to make assertions about these calls. You
1.326 +can build up a list of expected calls and compare it to <cite>call_args_list</cite>. This
1.327 +looks remarkably similar to the repr of the <cite>call_args_list</cite>:</p>
1.328 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">expected</span> <span class="o">=</span> <span class="p">[</span><span class="n">call</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="n">call</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="mi">6</span><span class="p">),</span> <span class="n">call</span><span class="p">()]</span>
1.329 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args_list</span> <span class="o">==</span> <span class="n">expected</span>
1.330 +<span class="go">True</span>
1.331 +</pre></div>
1.332 +</div>
1.333 +</div>
1.334 +<div class="section" id="coping-with-mutable-arguments">
1.335 +<h2>Coping with mutable arguments<a class="headerlink" href="#coping-with-mutable-arguments" title="Permalink to this headline">¶</a></h2>
1.336 +<p>Another situation is rare, but can bite you, is when your mock is called with
1.337 +mutable arguments. <cite>call_args</cite> and <cite>call_args_list</cite> store <em>references</em> to the
1.338 +arguments. If the arguments are mutated by the code under test then you can no
1.339 +longer make assertions about what the values were when the mock was called.</p>
1.340 +<p>Here’s some example code that shows the problem. Imagine the following functions
1.341 +defined in ‘mymodule’:</p>
1.342 +<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">frob</span><span class="p">(</span><span class="n">val</span><span class="p">):</span>
1.343 + <span class="k">pass</span>
1.344 +
1.345 +<span class="k">def</span> <span class="nf">grob</span><span class="p">(</span><span class="n">val</span><span class="p">):</span>
1.346 + <span class="s">"First frob and then clear val"</span>
1.347 + <span class="n">frob</span><span class="p">(</span><span class="n">val</span><span class="p">)</span>
1.348 + <span class="n">val</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span>
1.349 +</pre></div>
1.350 +</div>
1.351 +<p>When we try to test that <cite>grob</cite> calls <cite>frob</cite> with the correct argument look
1.352 +what happens:</p>
1.353 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.frob'</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_frob</span><span class="p">:</span>
1.354 +<span class="gp">... </span> <span class="n">val</span> <span class="o">=</span> <span class="nb">set</span><span class="p">([</span><span class="mi">6</span><span class="p">])</span>
1.355 +<span class="gp">... </span> <span class="n">mymodule</span><span class="o">.</span><span class="n">grob</span><span class="p">(</span><span class="n">val</span><span class="p">)</span>
1.356 +<span class="gp">...</span>
1.357 +<span class="gp">>>> </span><span class="n">val</span>
1.358 +<span class="go">set([])</span>
1.359 +<span class="gp">>>> </span><span class="n">mock_frob</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="nb">set</span><span class="p">([</span><span class="mi">6</span><span class="p">]))</span>
1.360 +<span class="gt">Traceback (most recent call last):</span>
1.361 + <span class="o">...</span>
1.362 +<span class="gr">AssertionError: Expected</span>: <span class="n">((set([6]),), {})</span>
1.363 +<span class="go">Called with: ((set([]),), {})</span>
1.364 +</pre></div>
1.365 +</div>
1.366 +<p>One possibility would be for mock to copy the arguments you pass in. This
1.367 +could then cause problems if you do assertions that rely on object identity
1.368 +for equality.</p>
1.369 +<p>Here’s one solution that uses the <tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt>
1.370 +functionality. If you provide a <cite>side_effect</cite> function for a mock then
1.371 +<cite>side_effect</cite> will be called with the same args as the mock. This gives us an
1.372 +opportunity to copy the arguments and store them for later assertions. In this
1.373 +example I’m using <em>another</em> mock to store the arguments so that I can use the
1.374 +mock methods for doing the assertion. Again a helper function sets this up for
1.375 +me.</p>
1.376 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">copy</span> <span class="kn">import</span> <span class="n">deepcopy</span>
1.377 +<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">Mock</span><span class="p">,</span> <span class="n">patch</span><span class="p">,</span> <span class="n">DEFAULT</span>
1.378 +<span class="gp">>>> </span><span class="k">def</span> <span class="nf">copy_call_args</span><span class="p">(</span><span class="n">mock</span><span class="p">):</span>
1.379 +<span class="gp">... </span> <span class="n">new_mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">()</span>
1.380 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">side_effect</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
1.381 +<span class="gp">... </span> <span class="n">args</span> <span class="o">=</span> <span class="n">deepcopy</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
1.382 +<span class="gp">... </span> <span class="n">kwargs</span> <span class="o">=</span> <span class="n">deepcopy</span><span class="p">(</span><span class="n">kwargs</span><span class="p">)</span>
1.383 +<span class="gp">... </span> <span class="n">new_mock</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
1.384 +<span class="gp">... </span> <span class="k">return</span> <span class="n">DEFAULT</span>
1.385 +<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>
1.386 +<span class="gp">... </span> <span class="k">return</span> <span class="n">new_mock</span>
1.387 +<span class="gp">...</span>
1.388 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.frob'</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_frob</span><span class="p">:</span>
1.389 +<span class="gp">... </span> <span class="n">new_mock</span> <span class="o">=</span> <span class="n">copy_call_args</span><span class="p">(</span><span class="n">mock_frob</span><span class="p">)</span>
1.390 +<span class="gp">... </span> <span class="n">val</span> <span class="o">=</span> <span class="nb">set</span><span class="p">([</span><span class="mi">6</span><span class="p">])</span>
1.391 +<span class="gp">... </span> <span class="n">mymodule</span><span class="o">.</span><span class="n">grob</span><span class="p">(</span><span class="n">val</span><span class="p">)</span>
1.392 +<span class="gp">...</span>
1.393 +<span class="gp">>>> </span><span class="n">new_mock</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="nb">set</span><span class="p">([</span><span class="mi">6</span><span class="p">]))</span>
1.394 +<span class="gp">>>> </span><span class="n">new_mock</span><span class="o">.</span><span class="n">call_args</span>
1.395 +<span class="go">call(set([6]))</span>
1.396 +</pre></div>
1.397 +</div>
1.398 +<p><cite>copy_call_args</cite> is called with the mock that will be called. It returns a new
1.399 +mock that we do the assertion on. The <cite>side_effect</cite> function makes a copy of
1.400 +the args and calls our <cite>new_mock</cite> with the copy.</p>
1.401 +<div class="admonition note">
1.402 +<p class="first admonition-title">Note</p>
1.403 +<p>If your mock is only going to be used once there is an easier way of
1.404 +checking arguments at the point they are called. You can simply do the
1.405 +checking inside a <cite>side_effect</cite> function.</p>
1.406 +<div class="last highlight-python"><div class="highlight"><pre><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>
1.407 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">arg</span> <span class="o">==</span> <span class="nb">set</span><span class="p">([</span><span class="mi">6</span><span class="p">])</span>
1.408 +<span class="gp">...</span>
1.409 +<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="n">side_effect</span><span class="p">)</span>
1.410 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="nb">set</span><span class="p">([</span><span class="mi">6</span><span class="p">]))</span>
1.411 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="nb">set</span><span class="p">())</span>
1.412 +<span class="gt">Traceback (most recent call last):</span>
1.413 + <span class="o">...</span>
1.414 +<span class="gr">AssertionError</span>
1.415 +</pre></div>
1.416 +</div>
1.417 +</div>
1.418 +<p>An alternative approach is to create a subclass of <cite>Mock</cite> or <cite>MagicMock</cite> that
1.419 +copies (using <a class="reference external" href="http://docs.python.org/library/copy.html#copy.deepcopy">copy.deepcopy</a>) the arguments.
1.420 +Here’s an example implementation:</p>
1.421 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">copy</span> <span class="kn">import</span> <span class="n">deepcopy</span>
1.422 +<span class="gp">>>> </span><span class="k">class</span> <span class="nc">CopyingMock</span><span class="p">(</span><span class="n">MagicMock</span><span class="p">):</span>
1.423 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
1.424 +<span class="gp">... </span> <span class="n">args</span> <span class="o">=</span> <span class="n">deepcopy</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
1.425 +<span class="gp">... </span> <span class="n">kwargs</span> <span class="o">=</span> <span class="n">deepcopy</span><span class="p">(</span><span class="n">kwargs</span><span class="p">)</span>
1.426 +<span class="gp">... </span> <span class="k">return</span> <span class="nb">super</span><span class="p">(</span><span class="n">CopyingMock</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__call__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
1.427 +<span class="gp">...</span>
1.428 +<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">CopyingMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
1.429 +<span class="gp">>>> </span><span class="n">arg</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>
1.430 +<span class="gp">>>> </span><span class="n">c</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>
1.431 +<span class="gp">>>> </span><span class="n">arg</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
1.432 +<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="nb">set</span><span class="p">())</span>
1.433 +<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>
1.434 +<span class="gt">Traceback (most recent call last):</span>
1.435 + <span class="o">...</span>
1.436 +<span class="gr">AssertionError: Expected call</span>: <span class="n">mock(set([1]))</span>
1.437 +<span class="go">Actual call: mock(set([]))</span>
1.438 +<span class="gp">>>> </span><span class="n">c</span><span class="o">.</span><span class="n">foo</span>
1.439 +<span class="go"><CopyingMock name='mock.foo' id='...'></span>
1.440 +</pre></div>
1.441 +</div>
1.442 +<p>When you subclass <cite>Mock</cite> or <cite>MagicMock</cite> all dynamically created attributes,
1.443 +and the <cite>return_value</cite> will use your subclass automatically. That means all
1.444 +children of a <cite>CopyingMock</cite> will also have the type <cite>CopyingMock</cite>.</p>
1.445 +</div>
1.446 +<div class="section" id="raising-exceptions-on-attribute-access">
1.447 +<h2>Raising exceptions on attribute access<a class="headerlink" href="#raising-exceptions-on-attribute-access" title="Permalink to this headline">¶</a></h2>
1.448 +<p>You can use <a class="reference internal" href="mock.html#mock.PropertyMock" title="mock.PropertyMock"><tt class="xref py py-class docutils literal"><span class="pre">PropertyMock</span></tt></a> to mimic the behaviour of properties. This
1.449 +includes raising exceptions when an attribute is accessed.</p>
1.450 +<p>Here’s an example raising a <cite>ValueError</cite> when the ‘foo’ attribute is accessed:</p>
1.451 +<div class="highlight-python"><pre>>>> m = MagicMock()
1.452 +>>> p = PropertyMock(side_effect=ValueError)
1.453 +>>> type(m).foo = p
1.454 +>>> m.foo
1.455 +Traceback (most recent call last):
1.456 +....
1.457 +ValueError</pre>
1.458 +</div>
1.459 +<p>Because every mock object has its own type, a new subclass of whichever mock
1.460 +class you’re using, all mock objects are isolated from each other. You can
1.461 +safely attach properties (or other descriptors or whatever you want in fact)
1.462 +to <cite>type(mock)</cite> without affecting other mock objects.</p>
1.463 +</div>
1.464 +<div class="section" id="multiple-calls-with-different-effects">
1.465 +<h2>Multiple calls with different effects<a class="headerlink" href="#multiple-calls-with-different-effects" title="Permalink to this headline">¶</a></h2>
1.466 +<div class="admonition note">
1.467 +<p class="first admonition-title">Note</p>
1.468 +<p class="last">In mock 1.0 the handling of iterable <cite>side_effect</cite> was changed. Any
1.469 +exceptions in the iterable will be raised instead of returned.</p>
1.470 +</div>
1.471 +<p>Handling code that needs to behave differently on subsequent calls during the
1.472 +test can be tricky. For example you may have a function that needs to raise
1.473 +an exception the first time it is called but returns a response on the second
1.474 +call (testing retry behaviour).</p>
1.475 +<p>One approach is to use a <tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt> function that replaces itself. The
1.476 +first time it is called the <cite>side_effect</cite> sets a new <cite>side_effect</cite> that will
1.477 +be used for the second call. It then raises an exception:</p>
1.478 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">side_effect</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>
1.479 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">second_call</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>
1.480 +<span class="gp">... </span> <span class="k">return</span> <span class="s">'response'</span>
1.481 +<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">second_call</span>
1.482 +<span class="gp">... </span> <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s">'boom'</span><span class="p">)</span>
1.483 +<span class="gp">...</span>
1.484 +<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="n">side_effect</span><span class="p">)</span>
1.485 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'first'</span><span class="p">)</span>
1.486 +<span class="gt">Traceback (most recent call last):</span>
1.487 + <span class="o">...</span>
1.488 +<span class="gr">Exception</span>: <span class="n">boom</span>
1.489 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'second'</span><span class="p">)</span>
1.490 +<span class="go">'response'</span>
1.491 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="s">'second'</span><span class="p">)</span>
1.492 +</pre></div>
1.493 +</div>
1.494 +<p>Another perfectly valid way would be to pop return values from a list. If the
1.495 +return value is an exception, raise it instead of returning it:</p>
1.496 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">returns</span> <span class="o">=</span> <span class="p">[</span><span class="ne">Exception</span><span class="p">(</span><span class="s">'boom'</span><span class="p">),</span> <span class="s">'response'</span><span class="p">]</span>
1.497 +<span class="gp">>>> </span><span class="k">def</span> <span class="nf">side_effect</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>
1.498 +<span class="gp">... </span> <span class="n">result</span> <span class="o">=</span> <span class="n">returns</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
1.499 +<span class="gp">... </span> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">result</span><span class="p">,</span> <span class="ne">Exception</span><span class="p">):</span>
1.500 +<span class="gp">... </span> <span class="k">raise</span> <span class="n">result</span>
1.501 +<span class="gp">... </span> <span class="k">return</span> <span class="n">result</span>
1.502 +<span class="gp">...</span>
1.503 +<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="n">side_effect</span><span class="p">)</span>
1.504 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'first'</span><span class="p">)</span>
1.505 +<span class="gt">Traceback (most recent call last):</span>
1.506 + <span class="o">...</span>
1.507 +<span class="gr">Exception</span>: <span class="n">boom</span>
1.508 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'second'</span><span class="p">)</span>
1.509 +<span class="go">'response'</span>
1.510 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="s">'second'</span><span class="p">)</span>
1.511 +</pre></div>
1.512 +</div>
1.513 +<p>Which approach you prefer is a matter of taste. The first approach is actually
1.514 +a line shorter but maybe the second approach is more readable.</p>
1.515 +</div>
1.516 +<div class="section" id="nesting-patches">
1.517 +<h2>Nesting Patches<a class="headerlink" href="#nesting-patches" title="Permalink to this headline">¶</a></h2>
1.518 +<p>Using patch as a context manager is nice, but if you do multiple patches you
1.519 +can end up with nested with statements indenting further and further to the
1.520 +right:</p>
1.521 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
1.522 +<span class="gp">...</span>
1.523 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">test_foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.524 +<span class="gp">... </span> <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.Foo'</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_foo</span><span class="p">:</span>
1.525 +<span class="gp">... </span> <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.Bar'</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_bar</span><span class="p">:</span>
1.526 +<span class="gp">... </span> <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.Spam'</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_spam</span><span class="p">:</span>
1.527 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Foo</span> <span class="ow">is</span> <span class="n">mock_foo</span>
1.528 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Bar</span> <span class="ow">is</span> <span class="n">mock_bar</span>
1.529 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Spam</span> <span class="ow">is</span> <span class="n">mock_spam</span>
1.530 +<span class="gp">...</span>
1.531 +<span class="gp">>>> </span><span class="n">original</span> <span class="o">=</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Foo</span>
1.532 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_foo'</span><span class="p">)</span><span class="o">.</span><span class="n">test_foo</span><span class="p">()</span>
1.533 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Foo</span> <span class="ow">is</span> <span class="n">original</span>
1.534 +</pre></div>
1.535 +</div>
1.536 +<p>With <a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest2</a> <cite>cleanup</cite> functions and the <a class="reference internal" href="patch.html#start-and-stop"><em>patch methods: start and stop</em></a> we can
1.537 +achieve the same effect without the nested indentation. A simple helper
1.538 +method, <cite>create_patch</cite>, puts the patch in place and returns the created mock
1.539 +for us:</p>
1.540 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
1.541 +<span class="gp">...</span>
1.542 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">create_patch</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
1.543 +<span class="gp">... </span> <span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
1.544 +<span class="gp">... </span> <span class="n">thing</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.545 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">addCleanup</span><span class="p">(</span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">)</span>
1.546 +<span class="gp">... </span> <span class="k">return</span> <span class="n">thing</span>
1.547 +<span class="gp">...</span>
1.548 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">test_foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.549 +<span class="gp">... </span> <span class="n">mock_foo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">create_patch</span><span class="p">(</span><span class="s">'mymodule.Foo'</span><span class="p">)</span>
1.550 +<span class="gp">... </span> <span class="n">mock_bar</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">create_patch</span><span class="p">(</span><span class="s">'mymodule.Bar'</span><span class="p">)</span>
1.551 +<span class="gp">... </span> <span class="n">mock_spam</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">create_patch</span><span class="p">(</span><span class="s">'mymodule.Spam'</span><span class="p">)</span>
1.552 +<span class="gp">...</span>
1.553 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Foo</span> <span class="ow">is</span> <span class="n">mock_foo</span>
1.554 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Bar</span> <span class="ow">is</span> <span class="n">mock_bar</span>
1.555 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Spam</span> <span class="ow">is</span> <span class="n">mock_spam</span>
1.556 +<span class="gp">...</span>
1.557 +<span class="gp">>>> </span><span class="n">original</span> <span class="o">=</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Foo</span>
1.558 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_foo'</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
1.559 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">mymodule</span><span class="o">.</span><span class="n">Foo</span> <span class="ow">is</span> <span class="n">original</span>
1.560 +</pre></div>
1.561 +</div>
1.562 +</div>
1.563 +<div class="section" id="mocking-a-dictionary-with-magicmock">
1.564 +<h2>Mocking a dictionary with MagicMock<a class="headerlink" href="#mocking-a-dictionary-with-magicmock" title="Permalink to this headline">¶</a></h2>
1.565 +<p>You may want to mock a dictionary, or other container object, recording all
1.566 +access to it whilst having it still behave like a dictionary.</p>
1.567 +<p>We can do this with <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>, which will behave like a dictionary,
1.568 +and using <a class="reference internal" href="mock.html#mock.Mock.side_effect" title="mock.Mock.side_effect"><tt class="xref py py-data docutils literal"><span class="pre">side_effect</span></tt></a> to delegate dictionary access to a real
1.569 +underlying dictionary that is under our control.</p>
1.570 +<p>When the <cite>__getitem__</cite> and <cite>__setitem__</cite> methods of our <cite>MagicMock</cite> are called
1.571 +(normal dictionary access) then <cite>side_effect</cite> is called with the key (and in
1.572 +the case of <cite>__setitem__</cite> the value too). We can also control what is returned.</p>
1.573 +<p>After the <cite>MagicMock</cite> has been used we can use attributes like
1.574 +<a class="reference internal" href="mock.html#mock.Mock.call_args_list" title="mock.Mock.call_args_list"><tt class="xref py py-data docutils literal"><span class="pre">call_args_list</span></tt></a> to assert about how the dictionary was used:</p>
1.575 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">my_dict</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>
1.576 +<span class="gp">>>> </span><span class="k">def</span> <span class="nf">getitem</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
1.577 +<span class="gp">... </span> <span class="k">return</span> <span class="n">my_dict</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>
1.578 +<span class="gp">...</span>
1.579 +<span class="gp">>>> </span><span class="k">def</span> <span class="nf">setitem</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">val</span><span class="p">):</span>
1.580 +<span class="gp">... </span> <span class="n">my_dict</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">val</span>
1.581 +<span class="gp">...</span>
1.582 +<span class="gp">>>> </span><span class="n">mock</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.583 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__getitem__</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">getitem</span>
1.584 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__setitem__</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">setitem</span>
1.585 +</pre></div>
1.586 +</div>
1.587 +<div class="admonition note">
1.588 +<p class="first admonition-title">Note</p>
1.589 +<p>An alternative to using <cite>MagicMock</cite> is to use <cite>Mock</cite> and <em>only</em> provide
1.590 +the magic methods you specifically want:</p>
1.591 +<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>
1.592 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__setitem__</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="n">getitem</span><span class="p">)</span>
1.593 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__getitem__</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="n">setitem</span><span class="p">)</span>
1.594 +</pre></div>
1.595 +</div>
1.596 +<p>A <em>third</em> option is to use <cite>MagicMock</cite> but passing in <cite>dict</cite> as the <cite>spec</cite>
1.597 +(or <cite>spec_set</cite>) argument so that the <cite>MagicMock</cite> created only has
1.598 +dictionary magic methods available:</p>
1.599 +<div class="last 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="n">spec_set</span><span class="o">=</span><span class="nb">dict</span><span class="p">)</span>
1.600 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__getitem__</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">getitem</span>
1.601 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__setitem__</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">setitem</span>
1.602 +</pre></div>
1.603 +</div>
1.604 +</div>
1.605 +<p>With these side effect functions in place, the <cite>mock</cite> will behave like a normal
1.606 +dictionary but recording the access. It even raises a <cite>KeyError</cite> if you try
1.607 +to access a key that doesn’t exist.</p>
1.608 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span><span class="p">[</span><span class="s">'a'</span><span class="p">]</span>
1.609 +<span class="go">1</span>
1.610 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">[</span><span class="s">'c'</span><span class="p">]</span>
1.611 +<span class="go">3</span>
1.612 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">[</span><span class="s">'d'</span><span class="p">]</span>
1.613 +<span class="gt">Traceback (most recent call last):</span>
1.614 + <span class="o">...</span>
1.615 +<span class="gr">KeyError</span>: <span class="n">'d'</span>
1.616 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">[</span><span class="s">'b'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'fish'</span>
1.617 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">[</span><span class="s">'d'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'eggs'</span>
1.618 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">[</span><span class="s">'b'</span><span class="p">]</span>
1.619 +<span class="go">'fish'</span>
1.620 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">[</span><span class="s">'d'</span><span class="p">]</span>
1.621 +<span class="go">'eggs'</span>
1.622 +</pre></div>
1.623 +</div>
1.624 +<p>After it has been used you can make assertions about the access using the normal
1.625 +mock methods and attributes:</p>
1.626 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__getitem__</span><span class="o">.</span><span class="n">call_args_list</span>
1.627 +<span class="go">[call('a'), call('c'), call('d'), call('b'), call('d')]</span>
1.628 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__setitem__</span><span class="o">.</span><span class="n">call_args_list</span>
1.629 +<span class="go">[call('b', 'fish'), call('d', 'eggs')]</span>
1.630 +<span class="gp">>>> </span><span class="n">my_dict</span>
1.631 +<span class="go">{'a': 1, 'c': 3, 'b': 'fish', 'd': 'eggs'}</span>
1.632 +</pre></div>
1.633 +</div>
1.634 +</div>
1.635 +<div class="section" id="mock-subclasses-and-their-attributes">
1.636 +<h2>Mock subclasses and their attributes<a class="headerlink" href="#mock-subclasses-and-their-attributes" title="Permalink to this headline">¶</a></h2>
1.637 +<p>There are various reasons why you might want to subclass <cite>Mock</cite>. One reason
1.638 +might be to add helper methods. Here’s a silly example:</p>
1.639 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyMock</span><span class="p">(</span><span class="n">MagicMock</span><span class="p">):</span>
1.640 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">has_been_called</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.641 +<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">called</span>
1.642 +<span class="gp">...</span>
1.643 +<span class="gp">>>> </span><span class="n">mymock</span> <span class="o">=</span> <span class="n">MyMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
1.644 +<span class="gp">>>> </span><span class="n">mymock</span>
1.645 +<span class="go"><MyMock id='...'></span>
1.646 +<span class="gp">>>> </span><span class="n">mymock</span><span class="o">.</span><span class="n">has_been_called</span><span class="p">()</span>
1.647 +<span class="go">False</span>
1.648 +<span class="gp">>>> </span><span class="n">mymock</span><span class="p">()</span>
1.649 +<span class="gp">>>> </span><span class="n">mymock</span><span class="o">.</span><span class="n">has_been_called</span><span class="p">()</span>
1.650 +<span class="go">True</span>
1.651 +</pre></div>
1.652 +</div>
1.653 +<p>The standard behaviour for <cite>Mock</cite> instances is that attributes and the return
1.654 +value mocks are of the same type as the mock they are accessed on. This ensures
1.655 +that <cite>Mock</cite> attributes are <cite>Mocks</cite> and <cite>MagicMock</cite> attributes are <cite>MagicMocks</cite>
1.656 +<a class="footnote-reference" href="#id5" id="id4">[2]</a>. So if you’re subclassing to add helper methods then they’ll also be
1.657 +available on the attributes and return value mock of instances of your
1.658 +subclass.</p>
1.659 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mymock</span><span class="o">.</span><span class="n">foo</span>
1.660 +<span class="go"><MyMock name='mock.foo' id='...'></span>
1.661 +<span class="gp">>>> </span><span class="n">mymock</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">has_been_called</span><span class="p">()</span>
1.662 +<span class="go">False</span>
1.663 +<span class="gp">>>> </span><span class="n">mymock</span><span class="o">.</span><span class="n">foo</span><span class="p">()</span>
1.664 +<span class="go"><MyMock name='mock.foo()' id='...'></span>
1.665 +<span class="gp">>>> </span><span class="n">mymock</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">has_been_called</span><span class="p">()</span>
1.666 +<span class="go">True</span>
1.667 +</pre></div>
1.668 +</div>
1.669 +<p>Sometimes this is inconvenient. For example, <a class="reference external" href="https://code.google.com/p/mock/issues/detail?id=105">one user</a> is subclassing mock to
1.670 +created a <a class="reference external" href="http://twistedmatrix.com/documents/11.0.0/api/twisted.python.components.html">Twisted adaptor</a>.
1.671 +Having this applied to attributes too actually causes errors.</p>
1.672 +<p><cite>Mock</cite> (in all its flavours) uses a method called <cite>_get_child_mock</cite> to create
1.673 +these “sub-mocks” for attributes and return values. You can prevent your
1.674 +subclass being used for attributes by overriding this method. The signature is
1.675 +that it takes arbitrary keyword arguments (<cite>**kwargs</cite>) which are then passed
1.676 +onto the mock constructor:</p>
1.677 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Subclass</span><span class="p">(</span><span class="n">MagicMock</span><span class="p">):</span>
1.678 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">_get_child_mock</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
1.679 +<span class="gp">... </span> <span class="k">return</span> <span class="n">MagicMock</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
1.680 +<span class="gp">...</span>
1.681 +<span class="gp">>>> </span><span class="n">mymock</span> <span class="o">=</span> <span class="n">Subclass</span><span class="p">()</span>
1.682 +<span class="gp">>>> </span><span class="n">mymock</span><span class="o">.</span><span class="n">foo</span>
1.683 +<span class="go"><MagicMock name='mock.foo' id='...'></span>
1.684 +<span class="gp">>>> </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">mymock</span><span class="p">,</span> <span class="n">Subclass</span><span class="p">)</span>
1.685 +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">mymock</span><span class="o">.</span><span class="n">foo</span><span class="p">,</span> <span class="n">Subclass</span><span class="p">)</span>
1.686 +<span class="gp">>>> </span><span class="k">assert</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">mymock</span><span class="p">(),</span> <span class="n">Subclass</span><span class="p">)</span>
1.687 +</pre></div>
1.688 +</div>
1.689 +<table class="docutils footnote" frame="void" id="id5" rules="none">
1.690 +<colgroup><col class="label" /><col /></colgroup>
1.691 +<tbody valign="top">
1.692 +<tr><td class="label"><a class="fn-backref" href="#id4">[2]</a></td><td>An exception to this rule are the non-callable mocks. Attributes use the
1.693 +callable variant because otherwise non-callable mocks couldn’t have callable
1.694 +methods.</td></tr>
1.695 +</tbody>
1.696 +</table>
1.697 +</div>
1.698 +<div class="section" id="mocking-imports-with-patch-dict">
1.699 +<h2>Mocking imports with patch.dict<a class="headerlink" href="#mocking-imports-with-patch-dict" title="Permalink to this headline">¶</a></h2>
1.700 +<p>One situation where mocking can be hard is where you have a local import inside
1.701 +a function. These are harder to mock because they aren’t using an object from
1.702 +the module namespace that we can patch out.</p>
1.703 +<p>Generally local imports are to be avoided. They are sometimes done to prevent
1.704 +circular dependencies, for which there is <em>usually</em> a much better way to solve
1.705 +the problem (refactor the code) or to prevent “up front costs” by delaying the
1.706 +import. This can also be solved in better ways than an unconditional local
1.707 +import (store the module as a class or module attribute and only do the import
1.708 +on first use).</p>
1.709 +<p>That aside there is a way to use <cite>mock</cite> to affect the results of an import.
1.710 +Importing fetches an <em>object</em> from the <cite>sys.modules</cite> dictionary. Note that it
1.711 +fetches an <em>object</em>, which need not be a module. Importing a module for the
1.712 +first time results in a module object being put in <cite>sys.modules</cite>, so usually
1.713 +when you import something you get a module back. This need not be the case
1.714 +however.</p>
1.715 +<p>This means you can use <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> to <em>temporarily</em> put a mock in place
1.716 +in <cite>sys.modules</cite>. Any imports whilst this patch is active will fetch the mock.
1.717 +When the patch is complete (the decorated function exits, the with statement
1.718 +body is complete or <cite>patcher.stop()</cite> is called) then whatever was there
1.719 +previously will be restored safely.</p>
1.720 +<p>Here’s an example that mocks out the ‘fooble’ module.</p>
1.721 +<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>
1.722 +<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="s">'sys.modules'</span><span class="p">,</span> <span class="p">{</span><span class="s">'fooble'</span><span class="p">:</span> <span class="n">mock</span><span class="p">}):</span>
1.723 +<span class="gp">... </span> <span class="kn">import</span> <span class="nn">fooble</span>
1.724 +<span class="gp">... </span> <span class="n">fooble</span><span class="o">.</span><span class="n">blob</span><span class="p">()</span>
1.725 +<span class="gp">...</span>
1.726 +<span class="go"><Mock name='mock.blob()' id='...'></span>
1.727 +<span class="gp">>>> </span><span class="k">assert</span> <span class="s">'fooble'</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">sys</span><span class="o">.</span><span class="n">modules</span>
1.728 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">blob</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">()</span>
1.729 +</pre></div>
1.730 +</div>
1.731 +<p>As you can see the <cite>import fooble</cite> succeeds, but on exit there is no ‘fooble’
1.732 +left in <cite>sys.modules</cite>.</p>
1.733 +<p>This also works for the <cite>from module import name</cite> form:</p>
1.734 +<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>
1.735 +<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="s">'sys.modules'</span><span class="p">,</span> <span class="p">{</span><span class="s">'fooble'</span><span class="p">:</span> <span class="n">mock</span><span class="p">}):</span>
1.736 +<span class="gp">... </span> <span class="kn">from</span> <span class="nn">fooble</span> <span class="kn">import</span> <span class="n">blob</span>
1.737 +<span class="gp">... </span> <span class="n">blob</span><span class="o">.</span><span class="n">blip</span><span class="p">()</span>
1.738 +<span class="gp">...</span>
1.739 +<span class="go"><Mock name='mock.blob.blip()' id='...'></span>
1.740 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">blob</span><span class="o">.</span><span class="n">blip</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">()</span>
1.741 +</pre></div>
1.742 +</div>
1.743 +<p>With slightly more work you can also mock package imports:</p>
1.744 +<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>
1.745 +<span class="gp">>>> </span><span class="n">modules</span> <span class="o">=</span> <span class="p">{</span><span class="s">'package'</span><span class="p">:</span> <span class="n">mock</span><span class="p">,</span> <span class="s">'package.module'</span><span class="p">:</span> <span class="n">mock</span><span class="o">.</span><span class="n">module</span><span class="p">}</span>
1.746 +<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="s">'sys.modules'</span><span class="p">,</span> <span class="n">modules</span><span class="p">):</span>
1.747 +<span class="gp">... </span> <span class="kn">from</span> <span class="nn">package.module</span> <span class="kn">import</span> <span class="n">fooble</span>
1.748 +<span class="gp">... </span> <span class="n">fooble</span><span class="p">()</span>
1.749 +<span class="gp">...</span>
1.750 +<span class="go"><Mock name='mock.module.fooble()' id='...'></span>
1.751 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">fooble</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">()</span>
1.752 +</pre></div>
1.753 +</div>
1.754 +</div>
1.755 +<div class="section" id="tracking-order-of-calls-and-less-verbose-call-assertions">
1.756 +<h2>Tracking order of calls and less verbose call assertions<a class="headerlink" href="#tracking-order-of-calls-and-less-verbose-call-assertions" title="Permalink to this headline">¶</a></h2>
1.757 +<p>The <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 allows you to track the <em>order</em> of method calls on
1.758 +your mock objects through the <a class="reference internal" href="mock.html#mock.Mock.method_calls" title="mock.Mock.method_calls"><tt class="xref py py-attr docutils literal"><span class="pre">method_calls</span></tt></a> attribute. This
1.759 +doesn’t allow you to track the order of calls between separate mock objects,
1.760 +however we can use <a class="reference internal" href="mock.html#mock.Mock.mock_calls" title="mock.Mock.mock_calls"><tt class="xref py py-attr docutils literal"><span class="pre">mock_calls</span></tt></a> to achieve the same effect.</p>
1.761 +<p>Because mocks track calls to child mocks in <cite>mock_calls</cite>, and accessing an
1.762 +arbitrary attribute of a mock creates a child mock, we can create our separate
1.763 +mocks from a parent one. Calls to those child mock will then all be recorded,
1.764 +in order, in the <cite>mock_calls</cite> of the parent:</p>
1.765 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">manager</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">()</span>
1.766 +<span class="gp">>>> </span><span class="n">mock_foo</span> <span class="o">=</span> <span class="n">manager</span><span class="o">.</span><span class="n">foo</span>
1.767 +<span class="gp">>>> </span><span class="n">mock_bar</span> <span class="o">=</span> <span class="n">manager</span><span class="o">.</span><span class="n">bar</span>
1.768 +
1.769 +<span class="gp">>>> </span><span class="n">mock_foo</span><span class="o">.</span><span class="n">something</span><span class="p">()</span>
1.770 +<span class="go"><Mock name='mock.foo.something()' id='...'></span>
1.771 +<span class="gp">>>> </span><span class="n">mock_bar</span><span class="o">.</span><span class="n">other</span><span class="o">.</span><span class="n">thing</span><span class="p">()</span>
1.772 +<span class="go"><Mock name='mock.bar.other.thing()' id='...'></span>
1.773 +
1.774 +<span class="gp">>>> </span><span class="n">manager</span><span class="o">.</span><span class="n">mock_calls</span>
1.775 +<span class="go">[call.foo.something(), call.bar.other.thing()]</span>
1.776 +</pre></div>
1.777 +</div>
1.778 +<p>We can then assert about the calls, including the order, by comparing with
1.779 +the <cite>mock_calls</cite> attribute on the manager mock:</p>
1.780 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">expected_calls</span> <span class="o">=</span> <span class="p">[</span><span class="n">call</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">something</span><span class="p">(),</span> <span class="n">call</span><span class="o">.</span><span class="n">bar</span><span class="o">.</span><span class="n">other</span><span class="o">.</span><span class="n">thing</span><span class="p">()]</span>
1.781 +<span class="gp">>>> </span><span class="n">manager</span><span class="o">.</span><span class="n">mock_calls</span> <span class="o">==</span> <span class="n">expected_calls</span>
1.782 +<span class="go">True</span>
1.783 +</pre></div>
1.784 +</div>
1.785 +<p>If <cite>patch</cite> is creating, and putting in place, your mocks then you can attach
1.786 +them to a manager mock using the <a class="reference internal" href="mock.html#mock.Mock.attach_mock" title="mock.Mock.attach_mock"><tt class="xref py py-meth docutils literal"><span class="pre">attach_mock()</span></tt></a> method. After
1.787 +attaching calls will be recorded in <cite>mock_calls</cite> of the manager.</p>
1.788 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">manager</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.789 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.Class1'</span><span class="p">)</span> <span class="k">as</span> <span class="n">MockClass1</span><span class="p">:</span>
1.790 +<span class="gp">... </span> <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'mymodule.Class2'</span><span class="p">)</span> <span class="k">as</span> <span class="n">MockClass2</span><span class="p">:</span>
1.791 +<span class="gp">... </span> <span class="n">manager</span><span class="o">.</span><span class="n">attach_mock</span><span class="p">(</span><span class="n">MockClass1</span><span class="p">,</span> <span class="s">'MockClass1'</span><span class="p">)</span>
1.792 +<span class="gp">... </span> <span class="n">manager</span><span class="o">.</span><span class="n">attach_mock</span><span class="p">(</span><span class="n">MockClass2</span><span class="p">,</span> <span class="s">'MockClass2'</span><span class="p">)</span>
1.793 +<span class="gp">... </span> <span class="n">MockClass1</span><span class="p">()</span><span class="o">.</span><span class="n">foo</span><span class="p">()</span>
1.794 +<span class="gp">... </span> <span class="n">MockClass2</span><span class="p">()</span><span class="o">.</span><span class="n">bar</span><span class="p">()</span>
1.795 +<span class="gp">...</span>
1.796 +<span class="go"><MagicMock name='mock.MockClass1().foo()' id='...'></span>
1.797 +<span class="go"><MagicMock name='mock.MockClass2().bar()' id='...'></span>
1.798 +<span class="gp">>>> </span><span class="n">manager</span><span class="o">.</span><span class="n">mock_calls</span>
1.799 +<span class="go">[call.MockClass1(),</span>
1.800 +<span class="go"> call.MockClass1().foo(),</span>
1.801 +<span class="go"> call.MockClass2(),</span>
1.802 +<span class="go"> call.MockClass2().bar()]</span>
1.803 +</pre></div>
1.804 +</div>
1.805 +<p>If many calls have been made, but you’re only interested in a particular
1.806 +sequence of them then an alternative is to use the
1.807 +<a class="reference internal" href="mock.html#mock.Mock.assert_has_calls" title="mock.Mock.assert_has_calls"><tt class="xref py py-meth docutils literal"><span class="pre">assert_has_calls()</span></tt></a> method. This takes a list of calls (constructed
1.808 +with the <a class="reference internal" href="helpers.html#mock.call" title="mock.call"><tt class="xref py py-data docutils literal"><span class="pre">call</span></tt></a> object). If that sequence of calls are in
1.809 +<a class="reference internal" href="mock.html#mock.Mock.mock_calls" title="mock.Mock.mock_calls"><tt class="xref py py-attr docutils literal"><span class="pre">mock_calls</span></tt></a> then the assert succeeds.</p>
1.810 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.811 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span><span class="o">.</span><span class="n">foo</span><span class="p">()</span><span class="o">.</span><span class="n">bar</span><span class="p">()</span><span class="o">.</span><span class="n">baz</span><span class="p">()</span>
1.812 +<span class="go"><MagicMock name='mock().foo().bar().baz()' id='...'></span>
1.813 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">one</span><span class="p">()</span><span class="o">.</span><span class="n">two</span><span class="p">()</span><span class="o">.</span><span class="n">three</span><span class="p">()</span>
1.814 +<span class="go"><MagicMock name='mock.one().two().three()' id='...'></span>
1.815 +<span class="gp">>>> </span><span class="n">calls</span> <span class="o">=</span> <span class="n">call</span><span class="o">.</span><span class="n">one</span><span class="p">()</span><span class="o">.</span><span class="n">two</span><span class="p">()</span><span class="o">.</span><span class="n">three</span><span class="p">()</span><span class="o">.</span><span class="n">call_list</span><span class="p">()</span>
1.816 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">assert_has_calls</span><span class="p">(</span><span class="n">calls</span><span class="p">)</span>
1.817 +</pre></div>
1.818 +</div>
1.819 +<p>Even though the chained call <cite>m.one().two().three()</cite> aren’t the only calls that
1.820 +have been made to the mock, the assert still succeeds.</p>
1.821 +<p>Sometimes a mock may have several calls made to it, and you are only interested
1.822 +in asserting about <em>some</em> of those calls. You may not even care about the
1.823 +order. In this case you can pass <cite>any_order=True</cite> to <cite>assert_has_calls</cite>:</p>
1.824 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.825 +<span class="gp">>>> </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">),</span> <span class="n">m</span><span class="o">.</span><span class="n">two</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="n">m</span><span class="o">.</span><span class="n">seven</span><span class="p">(</span><span class="mi">7</span><span class="p">),</span> <span class="n">m</span><span class="o">.</span><span class="n">fifty</span><span class="p">(</span><span class="s">'50'</span><span class="p">)</span>
1.826 +<span class="go">(...)</span>
1.827 +<span class="gp">>>> </span><span class="n">calls</span> <span class="o">=</span> <span class="p">[</span><span class="n">call</span><span class="o">.</span><span class="n">fifty</span><span class="p">(</span><span class="s">'50'</span><span class="p">),</span> <span class="n">call</span><span class="p">(</span><span class="mi">1</span><span class="p">),</span> <span class="n">call</span><span class="o">.</span><span class="n">seven</span><span class="p">(</span><span class="mi">7</span><span class="p">)]</span>
1.828 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">assert_has_calls</span><span class="p">(</span><span class="n">calls</span><span class="p">,</span> <span class="n">any_order</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
1.829 +</pre></div>
1.830 +</div>
1.831 +</div>
1.832 +<div class="section" id="more-complex-argument-matching">
1.833 +<h2>More complex argument matching<a class="headerlink" href="#more-complex-argument-matching" title="Permalink to this headline">¶</a></h2>
1.834 +<p>Using the same basic concept as <cite>ANY</cite> we can implement matchers to do more
1.835 +complex assertions on objects used as arguments to mocks.</p>
1.836 +<p>Suppose we expect some object to be passed to a mock that by default
1.837 +compares equal based on object identity (which is the Python default for user
1.838 +defined classes). To use <a class="reference internal" href="mock.html#mock.Mock.assert_called_with" title="mock.Mock.assert_called_with"><tt class="xref py py-meth docutils literal"><span class="pre">assert_called_with()</span></tt></a> we would need to pass
1.839 +in the exact same object. If we are only interested in some of the attributes
1.840 +of this object then we can create a matcher that will check these attributes
1.841 +for us.</p>
1.842 +<p>You can see in this example how a ‘standard’ call to <cite>assert_called_with</cite> isn’t
1.843 +sufficient:</p>
1.844 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
1.845 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
1.846 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">a</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">b</span> <span class="o">=</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span>
1.847 +<span class="gp">...</span>
1.848 +<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">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
1.849 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="n">Foo</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
1.850 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="n">Foo</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
1.851 +<span class="gt">Traceback (most recent call last):</span>
1.852 + <span class="o">...</span>
1.853 +<span class="gr">AssertionError: Expected</span>: <span class="n">call(<__main__.Foo object at 0x...>)</span>
1.854 +<span class="go">Actual call: call(<__main__.Foo object at 0x...>)</span>
1.855 +</pre></div>
1.856 +</div>
1.857 +<p>A comparison function for our <cite>Foo</cite> class might look something like this:</p>
1.858 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">compare</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
1.859 +<span class="gp">... </span> <span class="k">if</span> <span class="ow">not</span> <span class="nb">type</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">==</span> <span class="nb">type</span><span class="p">(</span><span class="n">other</span><span class="p">):</span>
1.860 +<span class="gp">... </span> <span class="k">return</span> <span class="bp">False</span>
1.861 +<span class="gp">... </span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">a</span> <span class="o">!=</span> <span class="n">other</span><span class="o">.</span><span class="n">a</span><span class="p">:</span>
1.862 +<span class="gp">... </span> <span class="k">return</span> <span class="bp">False</span>
1.863 +<span class="gp">... </span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">b</span> <span class="o">!=</span> <span class="n">other</span><span class="o">.</span><span class="n">b</span><span class="p">:</span>
1.864 +<span class="gp">... </span> <span class="k">return</span> <span class="bp">False</span>
1.865 +<span class="gp">... </span> <span class="k">return</span> <span class="bp">True</span>
1.866 +<span class="gp">...</span>
1.867 +</pre></div>
1.868 +</div>
1.869 +<p>And a matcher object that can use comparison functions like this for its
1.870 +equality operation would look something like this:</p>
1.871 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Matcher</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
1.872 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">compare</span><span class="p">,</span> <span class="n">some_obj</span><span class="p">):</span>
1.873 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">compare</span> <span class="o">=</span> <span class="n">compare</span>
1.874 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">some_obj</span> <span class="o">=</span> <span class="n">some_obj</span>
1.875 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
1.876 +<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">compare</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">some_obj</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
1.877 +<span class="gp">...</span>
1.878 +</pre></div>
1.879 +</div>
1.880 +<p>Putting all this together:</p>
1.881 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">match_foo</span> <span class="o">=</span> <span class="n">Matcher</span><span class="p">(</span><span class="n">compare</span><span class="p">,</span> <span class="n">Foo</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
1.882 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="n">match_foo</span><span class="p">)</span>
1.883 +</pre></div>
1.884 +</div>
1.885 +<p>The <cite>Matcher</cite> is instantiated with our compare function and the <cite>Foo</cite> object
1.886 +we want to compare against. In <cite>assert_called_with</cite> the <cite>Matcher</cite> equality
1.887 +method will be called, which compares the object the mock was called with
1.888 +against the one we created our matcher with. If they match then
1.889 +<cite>assert_called_with</cite> passes, and if they don’t an <cite>AssertionError</cite> is raised:</p>
1.890 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">match_wrong</span> <span class="o">=</span> <span class="n">Matcher</span><span class="p">(</span><span class="n">compare</span><span class="p">,</span> <span class="n">Foo</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">))</span>
1.891 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="n">match_wrong</span><span class="p">)</span>
1.892 +<span class="gt">Traceback (most recent call last):</span>
1.893 + <span class="o">...</span>
1.894 +<span class="gr">AssertionError: Expected</span>: <span class="n">((<Matcher object at 0x...>,), {})</span>
1.895 +<span class="go">Called with: ((<Foo object at 0x...>,), {})</span>
1.896 +</pre></div>
1.897 +</div>
1.898 +<p>With a bit of tweaking you could have the comparison function raise the
1.899 +<cite>AssertionError</cite> directly and provide a more useful failure message.</p>
1.900 +<p>As of version 1.5, the Python testing library <a class="reference external" href="http://pypi.python.org/pypi/PyHamcrest">PyHamcrest</a> provides similar functionality,
1.901 +that may be useful here, in the form of its equality matcher
1.902 +(<a class="reference external" href="http://packages.python.org/PyHamcrest/integration.html#hamcrest.library.integration.match_equality">hamcrest.library.integration.match_equality</a>).</p>
1.903 +</div>
1.904 +<div class="section" id="less-verbose-configuration-of-mock-objects">
1.905 +<h2>Less verbose configuration of mock objects<a class="headerlink" href="#less-verbose-configuration-of-mock-objects" title="Permalink to this headline">¶</a></h2>
1.906 +<p>This recipe, for easier configuration of mock objects, is now part of <cite>Mock</cite>.
1.907 +See the <a class="reference internal" href="mock.html#mock.Mock.configure_mock" title="mock.Mock.configure_mock"><tt class="xref py py-meth docutils literal"><span class="pre">configure_mock()</span></tt></a> method.</p>
1.908 +</div>
1.909 +<div class="section" id="matching-any-argument-in-assertions">
1.910 +<h2>Matching any argument in assertions<a class="headerlink" href="#matching-any-argument-in-assertions" title="Permalink to this headline">¶</a></h2>
1.911 +<p>This example is now built in to mock. See <a class="reference internal" href="helpers.html#mock.ANY" title="mock.ANY"><tt class="xref py py-data docutils literal"><span class="pre">ANY</span></tt></a>.</p>
1.912 +</div>
1.913 +<div class="section" id="mocking-properties">
1.914 +<h2>Mocking Properties<a class="headerlink" href="#mocking-properties" title="Permalink to this headline">¶</a></h2>
1.915 +<p>This example is now built in to mock. See <a class="reference internal" href="mock.html#mock.PropertyMock" title="mock.PropertyMock"><tt class="xref py py-class docutils literal"><span class="pre">PropertyMock</span></tt></a>.</p>
1.916 +</div>
1.917 +<div class="section" id="mocking-open">
1.918 +<h2>Mocking open<a class="headerlink" href="#mocking-open" title="Permalink to this headline">¶</a></h2>
1.919 +<p>This example is now built in to mock. See <a class="reference internal" href="helpers.html#mock.mock_open" title="mock.mock_open"><tt class="xref py py-func docutils literal"><span class="pre">mock_open()</span></tt></a>.</p>
1.920 +</div>
1.921 +<div class="section" id="mocks-without-some-attributes">
1.922 +<h2>Mocks without some attributes<a class="headerlink" href="#mocks-without-some-attributes" title="Permalink to this headline">¶</a></h2>
1.923 +<p>This example is now built in to mock. See <a class="reference internal" href="mock.html#deleting-attributes"><em>Deleting Attributes</em></a>.</p>
1.924 +</div>
1.925 +</div>
1.926 +
1.927 +
1.928 + </div>
1.929 + </div>
1.930 + </div>
1.931 + <div class="sphinxsidebar">
1.932 + <div class="sphinxsidebarwrapper">
1.933 + <h3><a href="index.html">Table Of Contents</a></h3>
1.934 + <ul>
1.935 +<li><a class="reference internal" href="#">Further Examples</a><ul>
1.936 +<li><a class="reference internal" href="#mocking-chained-calls">Mocking chained calls</a></li>
1.937 +<li><a class="reference internal" href="#partial-mocking">Partial mocking</a></li>
1.938 +<li><a class="reference internal" href="#mocking-a-generator-method">Mocking a Generator Method</a></li>
1.939 +<li><a class="reference internal" href="#applying-the-same-patch-to-every-test-method">Applying the same patch to every test method</a></li>
1.940 +<li><a class="reference internal" href="#mocking-unbound-methods">Mocking Unbound Methods</a></li>
1.941 +<li><a class="reference internal" href="#checking-multiple-calls-with-mock">Checking multiple calls with mock</a></li>
1.942 +<li><a class="reference internal" href="#coping-with-mutable-arguments">Coping with mutable arguments</a></li>
1.943 +<li><a class="reference internal" href="#raising-exceptions-on-attribute-access">Raising exceptions on attribute access</a></li>
1.944 +<li><a class="reference internal" href="#multiple-calls-with-different-effects">Multiple calls with different effects</a></li>
1.945 +<li><a class="reference internal" href="#nesting-patches">Nesting Patches</a></li>
1.946 +<li><a class="reference internal" href="#mocking-a-dictionary-with-magicmock">Mocking a dictionary with MagicMock</a></li>
1.947 +<li><a class="reference internal" href="#mock-subclasses-and-their-attributes">Mock subclasses and their attributes</a></li>
1.948 +<li><a class="reference internal" href="#mocking-imports-with-patch-dict">Mocking imports with patch.dict</a></li>
1.949 +<li><a class="reference internal" href="#tracking-order-of-calls-and-less-verbose-call-assertions">Tracking order of calls and less verbose call assertions</a></li>
1.950 +<li><a class="reference internal" href="#more-complex-argument-matching">More complex argument matching</a></li>
1.951 +<li><a class="reference internal" href="#less-verbose-configuration-of-mock-objects">Less verbose configuration of mock objects</a></li>
1.952 +<li><a class="reference internal" href="#matching-any-argument-in-assertions">Matching any argument in assertions</a></li>
1.953 +<li><a class="reference internal" href="#mocking-properties">Mocking Properties</a></li>
1.954 +<li><a class="reference internal" href="#mocking-open">Mocking open</a></li>
1.955 +<li><a class="reference internal" href="#mocks-without-some-attributes">Mocks without some attributes</a></li>
1.956 +</ul>
1.957 +</li>
1.958 +</ul>
1.959 +
1.960 + <h4>Previous topic</h4>
1.961 + <p class="topless"><a href="getting-started.html"
1.962 + title="previous chapter">Getting Started with Mock</a></p>
1.963 + <h4>Next topic</h4>
1.964 + <p class="topless"><a href="compare.html"
1.965 + title="next chapter">Mock Library Comparison</a></p>
1.966 + <h3>This Page</h3>
1.967 + <ul class="this-page-menu">
1.968 + <li><a href="_sources/examples.txt"
1.969 + rel="nofollow">Show Source</a></li>
1.970 + </ul>
1.971 +<div id="searchbox" style="display: none">
1.972 + <h3>Quick search</h3>
1.973 + <form class="search" action="search.html" method="get">
1.974 + <input type="text" name="q" />
1.975 + <input type="submit" value="Go" />
1.976 + <input type="hidden" name="check_keywords" value="yes" />
1.977 + <input type="hidden" name="area" value="default" />
1.978 + </form>
1.979 + <p class="searchtip" style="font-size: 90%">
1.980 + Enter search terms or a module, class or function name.
1.981 + </p>
1.982 +</div>
1.983 +<script type="text/javascript">$('#searchbox').show(0);</script>
1.984 + </div>
1.985 + </div>
1.986 + <div class="clearer"></div>
1.987 + </div>
1.988 + <div class="related">
1.989 + <h3>Navigation</h3>
1.990 + <ul>
1.991 + <li class="right" style="margin-right: 10px">
1.992 + <a href="genindex.html" title="General Index"
1.993 + >index</a></li>
1.994 + <li class="right" >
1.995 + <a href="compare.html" title="Mock Library Comparison"
1.996 + >next</a> |</li>
1.997 + <li class="right" >
1.998 + <a href="getting-started.html" title="Getting Started with Mock"
1.999 + >previous</a> |</li>
1.1000 + <li><a href="index.html">Mock 1.0.0 documentation</a> »</li>
1.1001 + </ul>
1.1002 + </div>
1.1003 + <div class="footer">
1.1004 + © Copyright 2007-2012, Michael Foord & the mock team.
1.1005 + Last updated on Oct 07, 2012.
1.1006 + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
1.1007 + </div>
1.1008 + </body>
1.1009 +</html>
1.1010 \ No newline at end of file
