1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/python/mock-1.0.0/html/mock.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,875 @@
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>The Mock Class — 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="Patch Decorators" href="patch.html" />
1.32 + <link rel="prev" title="Mock - Mocking and Testing Library" href="index.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="patch.html" title="Patch Decorators"
1.43 + accesskey="N">next</a> |</li>
1.44 + <li class="right" >
1.45 + <a href="index.html" title="Mock - Mocking and Testing Library"
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="the-mock-class">
1.57 +<h1>The Mock Class<a class="headerlink" href="#the-mock-class" title="Permalink to this headline">¶</a></h1>
1.58 +<p><cite>Mock</cite> is a flexible mock object intended to replace the use of stubs and
1.59 +test doubles throughout your code. Mocks are callable and create attributes as
1.60 +new mocks when you access them <a class="footnote-reference" href="#id3" id="id1">[1]</a>. Accessing the same attribute will always
1.61 +return the same mock. Mocks record how you use them, allowing you to make
1.62 +assertions about what your code has done to them.</p>
1.63 +<p><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> is a subclass of <cite>Mock</cite> with all the magic methods
1.64 +pre-created and ready to use. There are also non-callable variants, useful
1.65 +when you are mocking out objects that aren’t callable:
1.66 +<a class="reference internal" href="#mock.NonCallableMock" title="mock.NonCallableMock"><tt class="xref py py-class docutils literal"><span class="pre">NonCallableMock</span></tt></a> and <a class="reference internal" href="magicmock.html#mock.NonCallableMagicMock" title="mock.NonCallableMagicMock"><tt class="xref py py-class docutils literal"><span class="pre">NonCallableMagicMock</span></tt></a></p>
1.67 +<p>The <a class="reference internal" href="patch.html#mock.patch" title="mock.patch"><tt class="xref py py-func docutils literal"><span class="pre">patch()</span></tt></a> decorators makes it easy to temporarily replace classes
1.68 +in a particular module with a <cite>Mock</cite> object. By default <cite>patch</cite> will create
1.69 +a <cite>MagicMock</cite> for you. You can specify an alternative class of <cite>Mock</cite> using
1.70 +the <cite>new_callable</cite> argument to <cite>patch</cite>.</p>
1.71 +<span class="target" id="index-0"></span><span class="target" id="index-1"></span><span class="target" id="index-2"></span><span class="target" id="index-3"></span><span class="target" id="index-4"></span><dl class="class">
1.72 +<dt id="mock.Mock">
1.73 +<em class="property">class </em><tt class="descname">Mock</tt><big>(</big><em>spec=None</em>, <em>side_effect=None</em>, <em>return_value=DEFAULT</em>, <em>wraps=None</em>, <em>name=None</em>, <em>spec_set=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.Mock" title="Permalink to this definition">¶</a></dt>
1.74 +<dd><p>Create a new <cite>Mock</cite> object. <cite>Mock</cite> takes several optional arguments
1.75 +that specify the behaviour of the Mock object:</p>
1.76 +<ul>
1.77 +<li><p class="first"><cite>spec</cite>: This can be either a list of strings or an existing object (a
1.78 +class or instance) that acts as the specification for the mock object. If
1.79 +you pass in an object then a list of strings is formed by calling dir on
1.80 +the object (excluding unsupported magic attributes and methods).
1.81 +Accessing any attribute not in this list will raise an <cite>AttributeError</cite>.</p>
1.82 +<p>If <cite>spec</cite> is an object (rather than a list of strings) then
1.83 +<a class="reference internal" href="#mock.Mock.__class__" title="mock.Mock.__class__"><tt class="xref py py-attr docutils literal"><span class="pre">__class__</span></tt></a> returns the class of the spec object. This allows mocks
1.84 +to pass <cite>isinstance</cite> tests.</p>
1.85 +</li>
1.86 +<li><p class="first"><cite>spec_set</cite>: A stricter variant of <cite>spec</cite>. If used, attempting to <em>set</em>
1.87 +or get an attribute on the mock that isn’t on the object passed as
1.88 +<cite>spec_set</cite> will raise an <cite>AttributeError</cite>.</p>
1.89 +</li>
1.90 +<li><p class="first"><cite>side_effect</cite>: A function to be called whenever the Mock is called. See
1.91 +the <a class="reference internal" href="#mock.Mock.side_effect" title="mock.Mock.side_effect"><tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt></a> attribute. Useful for raising exceptions or
1.92 +dynamically changing return values. The function is called with the same
1.93 +arguments as the mock, and unless it returns <a class="reference internal" href="sentinel.html#mock.DEFAULT" title="mock.DEFAULT"><tt class="xref py py-data docutils literal"><span class="pre">DEFAULT</span></tt></a>, the return
1.94 +value of this function is used as the return value.</p>
1.95 +<p>Alternatively <cite>side_effect</cite> can be an exception class or instance. In
1.96 +this case the exception will be raised when the mock is called.</p>
1.97 +<p>If <cite>side_effect</cite> is an iterable then each call to the mock will return
1.98 +the next value from the iterable. If any of the members of the iterable
1.99 +are exceptions they will be raised instead of returned.</p>
1.100 +<p>A <cite>side_effect</cite> can be cleared by setting it to <cite>None</cite>.</p>
1.101 +</li>
1.102 +<li><p class="first"><cite>return_value</cite>: The value returned when the mock is called. By default
1.103 +this is a new Mock (created on first access). See the
1.104 +<a class="reference internal" href="#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.</p>
1.105 +</li>
1.106 +<li><p class="first"><cite>wraps</cite>: Item for the mock object to wrap. If <cite>wraps</cite> is not None then
1.107 +calling the Mock will pass the call through to the wrapped object
1.108 +(returning the real result and ignoring <cite>return_value</cite>). Attribute access
1.109 +on the mock will return a Mock object that wraps the corresponding
1.110 +attribute of the wrapped object (so attempting to access an attribute
1.111 +that doesn’t exist will raise an <cite>AttributeError</cite>).</p>
1.112 +<p>If the mock has an explicit <cite>return_value</cite> set then calls are not passed
1.113 +to the wrapped object and the <cite>return_value</cite> is returned instead.</p>
1.114 +</li>
1.115 +<li><p class="first"><cite>name</cite>: If the mock has a name then it will be used in the repr of the
1.116 +mock. This can be useful for debugging. The name is propagated to child
1.117 +mocks.</p>
1.118 +</li>
1.119 +</ul>
1.120 +<p>Mocks can also be called with arbitrary keyword arguments. These will be
1.121 +used to set attributes on the mock after it is created. See the
1.122 +<a class="reference internal" href="#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 for details.</p>
1.123 +<dl class="method">
1.124 +<dt id="mock.Mock.assert_called_with">
1.125 +<tt class="descname">assert_called_with</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.Mock.assert_called_with" title="Permalink to this definition">¶</a></dt>
1.126 +<dd><p>This method is a convenient way of asserting that calls are made in a
1.127 +particular way:</p>
1.128 +<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.129 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="n">test</span><span class="o">=</span><span class="s">'wow'</span><span class="p">)</span>
1.130 +<span class="go"><Mock name='mock.method()' id='...'></span>
1.131 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="mi">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">test</span><span class="o">=</span><span class="s">'wow'</span><span class="p">)</span>
1.132 +</pre></div>
1.133 +</div>
1.134 +</dd></dl>
1.135 +
1.136 +<dl class="method">
1.137 +<dt id="mock.Mock.assert_called_once_with">
1.138 +<tt class="descname">assert_called_once_with</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.Mock.assert_called_once_with" title="Permalink to this definition">¶</a></dt>
1.139 +<dd><p>Assert that the mock was called exactly once and with the specified
1.140 +arguments.</p>
1.141 +<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.142 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s">'baz'</span><span class="p">)</span>
1.143 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s">'baz'</span><span class="p">)</span>
1.144 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s">'baz'</span><span class="p">)</span>
1.145 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s">'baz'</span><span class="p">)</span>
1.146 +<span class="gt">Traceback (most recent call last):</span>
1.147 + <span class="c">...</span>
1.148 +<span class="gr">AssertionError</span>: <span class="n">Expected to be called once. Called 2 times.</span>
1.149 +</pre></div>
1.150 +</div>
1.151 +</dd></dl>
1.152 +
1.153 +<dl class="method">
1.154 +<dt id="mock.Mock.assert_any_call">
1.155 +<tt class="descname">assert_any_call</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.Mock.assert_any_call" title="Permalink to this definition">¶</a></dt>
1.156 +<dd><p>assert the mock has been called with the specified arguments.</p>
1.157 +<p>The assert passes if the mock has <em>ever</em> been called, unlike
1.158 +<a class="reference internal" href="#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> and <a class="reference internal" href="#mock.Mock.assert_called_once_with" title="mock.Mock.assert_called_once_with"><tt class="xref py py-meth docutils literal"><span class="pre">assert_called_once_with()</span></tt></a> that
1.159 +only pass if the call is the most recent one.</p>
1.160 +<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.161 +<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="n">arg</span><span class="o">=</span><span class="s">'thing'</span><span class="p">)</span>
1.162 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'some'</span><span class="p">,</span> <span class="s">'thing'</span><span class="p">,</span> <span class="s">'else'</span><span class="p">)</span>
1.163 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_any_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="n">arg</span><span class="o">=</span><span class="s">'thing'</span><span class="p">)</span>
1.164 +</pre></div>
1.165 +</div>
1.166 +</dd></dl>
1.167 +
1.168 +<dl class="method">
1.169 +<dt id="mock.Mock.assert_has_calls">
1.170 +<tt class="descname">assert_has_calls</tt><big>(</big><em>calls</em>, <em>any_order=False</em><big>)</big><a class="headerlink" href="#mock.Mock.assert_has_calls" title="Permalink to this definition">¶</a></dt>
1.171 +<dd><p>assert the mock has been called with the specified calls.
1.172 +The <cite>mock_calls</cite> list is checked for the calls.</p>
1.173 +<p>If <cite>any_order</cite> is False (the default) then the calls must be
1.174 +sequential. There can be extra calls before or after the
1.175 +specified calls.</p>
1.176 +<p>If <cite>any_order</cite> is True then the calls can be in any order, but
1.177 +they must all appear in <a class="reference internal" href="#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>.</p>
1.178 +<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.179 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
1.180 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
1.181 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
1.182 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>
1.183 +<span class="gp">>>> </span><span class="n">calls</span> <span class="o">=</span> <span class="p">[</span><span class="n">call</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="n">call</span><span class="p">(</span><span class="mi">3</span><span class="p">)]</span>
1.184 +<span class="gp">>>> </span><span class="n">mock</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.185 +<span class="gp">>>> </span><span class="n">calls</span> <span class="o">=</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="n">call</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="n">call</span><span class="p">(</span><span class="mi">3</span><span class="p">)]</span>
1.186 +<span class="gp">>>> </span><span class="n">mock</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.187 +</pre></div>
1.188 +</div>
1.189 +</dd></dl>
1.190 +
1.191 +<dl class="method">
1.192 +<dt id="mock.Mock.reset_mock">
1.193 +<tt class="descname">reset_mock</tt><big>(</big><big>)</big><a class="headerlink" href="#mock.Mock.reset_mock" title="Permalink to this definition">¶</a></dt>
1.194 +<dd><p>The reset_mock method resets all the call attributes on a mock object:</p>
1.195 +<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.196 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="s">'hello'</span><span class="p">)</span>
1.197 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>
1.198 +<span class="go">True</span>
1.199 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">reset_mock</span><span class="p">()</span>
1.200 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>
1.201 +<span class="go">False</span>
1.202 +</pre></div>
1.203 +</div>
1.204 +<p>This can be useful where you want to make a series of assertions that
1.205 +reuse the same object. Note that <cite>reset_mock</cite> <em>doesn’t</em> clear the
1.206 +return value, <a class="reference internal" href="#mock.Mock.side_effect" title="mock.Mock.side_effect"><tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt></a> or any child attributes you have
1.207 +set using normal assignment. Child mocks and the return value mock
1.208 +(if any) are reset as well.</p>
1.209 +</dd></dl>
1.210 +
1.211 +<dl class="method">
1.212 +<dt id="mock.Mock.mock_add_spec">
1.213 +<tt class="descname">mock_add_spec</tt><big>(</big><em>spec</em>, <em>spec_set=False</em><big>)</big><a class="headerlink" href="#mock.Mock.mock_add_spec" title="Permalink to this definition">¶</a></dt>
1.214 +<dd><p>Add a spec to a mock. <cite>spec</cite> can either be an object or a
1.215 +list of strings. Only attributes on the <cite>spec</cite> can be fetched as
1.216 +attributes from the mock.</p>
1.217 +<p>If <cite>spec_set</cite> is <cite>True</cite> then only attributes on the spec can be set.</p>
1.218 +</dd></dl>
1.219 +
1.220 +<dl class="method">
1.221 +<dt id="mock.Mock.attach_mock">
1.222 +<tt class="descname">attach_mock</tt><big>(</big><em>mock</em>, <em>attribute</em><big>)</big><a class="headerlink" href="#mock.Mock.attach_mock" title="Permalink to this definition">¶</a></dt>
1.223 +<dd><p>Attach a mock as an attribute of this one, replacing its name and
1.224 +parent. Calls to the attached mock will be recorded in the
1.225 +<a class="reference internal" href="#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> and <a class="reference internal" href="#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> attributes of this one.</p>
1.226 +</dd></dl>
1.227 +
1.228 +<dl class="method">
1.229 +<dt id="mock.Mock.configure_mock">
1.230 +<tt class="descname">configure_mock</tt><big>(</big><em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.Mock.configure_mock" title="Permalink to this definition">¶</a></dt>
1.231 +<dd><p>Set attributes on the mock through keyword arguments.</p>
1.232 +<p>Attributes plus return values and side effects can be set on child
1.233 +mocks using standard dot notation and unpacking a dictionary in the
1.234 +method call:</p>
1.235 +<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.236 +<span class="gp">>>> </span><span class="n">attrs</span> <span class="o">=</span> <span class="p">{</span><span class="s">'method.return_value'</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s">'other.side_effect'</span><span class="p">:</span> <span class="ne">KeyError</span><span class="p">}</span>
1.237 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">configure_mock</span><span class="p">(</span><span class="o">**</span><span class="n">attrs</span><span class="p">)</span>
1.238 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>
1.239 +<span class="go">3</span>
1.240 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">other</span><span class="p">()</span>
1.241 +<span class="gt">Traceback (most recent call last):</span>
1.242 + <span class="c">...</span>
1.243 +<span class="gr">KeyError</span>
1.244 +</pre></div>
1.245 +</div>
1.246 +<p>The same thing can be achieved in the constructor call to mocks:</p>
1.247 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">attrs</span> <span class="o">=</span> <span class="p">{</span><span class="s">'method.return_value'</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s">'other.side_effect'</span><span class="p">:</span> <span class="ne">KeyError</span><span class="p">}</span>
1.248 +<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">some_attribute</span><span class="o">=</span><span class="s">'eggs'</span><span class="p">,</span> <span class="o">**</span><span class="n">attrs</span><span class="p">)</span>
1.249 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">some_attribute</span>
1.250 +<span class="go">'eggs'</span>
1.251 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>
1.252 +<span class="go">3</span>
1.253 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">other</span><span class="p">()</span>
1.254 +<span class="gt">Traceback (most recent call last):</span>
1.255 + <span class="c">...</span>
1.256 +<span class="gr">KeyError</span>
1.257 +</pre></div>
1.258 +</div>
1.259 +<p><cite>configure_mock</cite> exists to make it easier to do configuration
1.260 +after the mock has been created.</p>
1.261 +</dd></dl>
1.262 +
1.263 +<dl class="method">
1.264 +<dt id="mock.Mock.__dir__">
1.265 +<tt class="descname">__dir__</tt><big>(</big><big>)</big><a class="headerlink" href="#mock.Mock.__dir__" title="Permalink to this definition">¶</a></dt>
1.266 +<dd><p><cite>Mock</cite> objects limit the results of <cite>dir(some_mock)</cite> to useful results.
1.267 +For mocks with a <cite>spec</cite> this includes all the permitted attributes
1.268 +for the mock.</p>
1.269 +<p>See <a class="reference internal" href="helpers.html#mock.FILTER_DIR" title="mock.FILTER_DIR"><tt class="xref py py-data docutils literal"><span class="pre">FILTER_DIR</span></tt></a> for what this filtering does, and how to
1.270 +switch it off.</p>
1.271 +</dd></dl>
1.272 +
1.273 +<dl class="method">
1.274 +<dt id="mock.Mock._get_child_mock">
1.275 +<tt class="descname">_get_child_mock</tt><big>(</big><em>**kw</em><big>)</big><a class="headerlink" href="#mock.Mock._get_child_mock" title="Permalink to this definition">¶</a></dt>
1.276 +<dd><p>Create the child mocks for attributes and return value.
1.277 +By default child mocks will be the same type as the parent.
1.278 +Subclasses of Mock may want to override this to customize the way
1.279 +child mocks are made.</p>
1.280 +<p>For non-callable mocks the callable variant will be used (rather than
1.281 +any custom subclass).</p>
1.282 +</dd></dl>
1.283 +
1.284 +<dl class="attribute">
1.285 +<dt id="mock.Mock.called">
1.286 +<tt class="descname">called</tt><a class="headerlink" href="#mock.Mock.called" title="Permalink to this definition">¶</a></dt>
1.287 +<dd><p>A boolean representing whether or not the mock object has been called:</p>
1.288 +<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.289 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>
1.290 +<span class="go">False</span>
1.291 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.292 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>
1.293 +<span class="go">True</span>
1.294 +</pre></div>
1.295 +</div>
1.296 +</dd></dl>
1.297 +
1.298 +<dl class="attribute">
1.299 +<dt id="mock.Mock.call_count">
1.300 +<tt class="descname">call_count</tt><a class="headerlink" href="#mock.Mock.call_count" title="Permalink to this definition">¶</a></dt>
1.301 +<dd><p>An integer telling you how many times the mock object has been called:</p>
1.302 +<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.303 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_count</span>
1.304 +<span class="go">0</span>
1.305 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.306 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.307 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_count</span>
1.308 +<span class="go">2</span>
1.309 +</pre></div>
1.310 +</div>
1.311 +</dd></dl>
1.312 +
1.313 +<dl class="attribute">
1.314 +<dt id="mock.Mock.return_value">
1.315 +<tt class="descname">return_value</tt><a class="headerlink" href="#mock.Mock.return_value" title="Permalink to this definition">¶</a></dt>
1.316 +<dd><p>Set this to configure the value returned by calling the mock:</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>
1.318 +<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="s">'fish'</span>
1.319 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.320 +<span class="go">'fish'</span>
1.321 +</pre></div>
1.322 +</div>
1.323 +<p>The default return value is a mock object and you can configure it in
1.324 +the normal way:</p>
1.325 +<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.326 +<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">attribute</span> <span class="o">=</span> <span class="n">sentinel</span><span class="o">.</span><span class="n">Attribute</span>
1.327 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">return_value</span><span class="p">()</span>
1.328 +<span class="go"><Mock name='mock()()' id='...'></span>
1.329 +<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">assert_called_with</span><span class="p">()</span>
1.330 +</pre></div>
1.331 +</div>
1.332 +<p><cite>return_value</cite> can also be set in the constructor:</p>
1.333 +<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="mi">3</span><span class="p">)</span>
1.334 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">return_value</span>
1.335 +<span class="go">3</span>
1.336 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.337 +<span class="go">3</span>
1.338 +</pre></div>
1.339 +</div>
1.340 +</dd></dl>
1.341 +
1.342 +<dl class="attribute">
1.343 +<dt id="mock.Mock.side_effect">
1.344 +<tt class="descname">side_effect</tt><a class="headerlink" href="#mock.Mock.side_effect" title="Permalink to this definition">¶</a></dt>
1.345 +<dd><p>This can either be a function to be called when the mock is called,
1.346 +or an exception (class or instance) to be raised.</p>
1.347 +<p>If you pass in a function it will be called with same arguments as the
1.348 +mock and unless the function returns the <a class="reference internal" href="sentinel.html#mock.DEFAULT" title="mock.DEFAULT"><tt class="xref py py-data docutils literal"><span class="pre">DEFAULT</span></tt></a> singleton the
1.349 +call to the mock will then return whatever the function returns. If the
1.350 +function returns <a class="reference internal" href="sentinel.html#mock.DEFAULT" title="mock.DEFAULT"><tt class="xref py py-data docutils literal"><span class="pre">DEFAULT</span></tt></a> then the mock will return its normal
1.351 +value (from the <a class="reference internal" href="#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>.</p>
1.352 +<p>An example of a mock that raises an exception (to test exception
1.353 +handling of an API):</p>
1.354 +<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.355 +<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="ne">Exception</span><span class="p">(</span><span class="s">'Boom!'</span><span class="p">)</span>
1.356 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.357 +<span class="gt">Traceback (most recent call last):</span>
1.358 + <span class="c">...</span>
1.359 +<span class="gr">Exception</span>: <span class="n">Boom!</span>
1.360 +</pre></div>
1.361 +</div>
1.362 +<p>Using <cite>side_effect</cite> to return a sequence of values:</p>
1.363 +<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.364 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span>
1.365 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(),</span> <span class="n">mock</span><span class="p">(),</span> <span class="n">mock</span><span class="p">()</span>
1.366 +<span class="go">(3, 2, 1)</span>
1.367 +</pre></div>
1.368 +</div>
1.369 +<p>The <cite>side_effect</cite> function is called with the same arguments as the
1.370 +mock (so it is wise for it to take arbitrary args and keyword
1.371 +arguments) and whatever it returns is used as the return value for
1.372 +the call. The exception is if <cite>side_effect</cite> returns <a class="reference internal" href="sentinel.html#mock.DEFAULT" title="mock.DEFAULT"><tt class="xref py py-data docutils literal"><span class="pre">DEFAULT</span></tt></a>,
1.373 +in which case the normal <a class="reference internal" href="#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> is used.</p>
1.374 +<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="mi">3</span><span class="p">)</span>
1.375 +<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.376 +<span class="gp">... </span> <span class="k">return</span> <span class="n">DEFAULT</span>
1.377 +<span class="gp">...</span>
1.378 +<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.379 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.380 +<span class="go">3</span>
1.381 +</pre></div>
1.382 +</div>
1.383 +<p><cite>side_effect</cite> can be set in the constructor. Here’s an example that
1.384 +adds one to the value the mock is called with and returns it:</p>
1.385 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">side_effect</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">value</span><span class="p">:</span> <span class="n">value</span> <span class="o">+</span> <span class="mi">1</span>
1.386 +<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.387 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
1.388 +<span class="go">4</span>
1.389 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="o">-</span><span class="mi">8</span><span class="p">)</span>
1.390 +<span class="go">-7</span>
1.391 +</pre></div>
1.392 +</div>
1.393 +<p>Setting <cite>side_effect</cite> to <cite>None</cite> clears it:</p>
1.394 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">Mock</span>
1.395 +<span class="gp">>>> </span><span class="n">m</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="ne">KeyError</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
1.396 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.397 +<span class="gt">Traceback (most recent call last):</span>
1.398 + <span class="c">...</span>
1.399 +<span class="gr">KeyError</span>
1.400 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="bp">None</span>
1.401 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.402 +<span class="go">3</span>
1.403 +</pre></div>
1.404 +</div>
1.405 +</dd></dl>
1.406 +
1.407 +<dl class="attribute">
1.408 +<dt id="mock.Mock.call_args">
1.409 +<tt class="descname">call_args</tt><a class="headerlink" href="#mock.Mock.call_args" title="Permalink to this definition">¶</a></dt>
1.410 +<dd><p>This is either <cite>None</cite> (if the mock hasn’t been called), or the
1.411 +arguments that the mock was last called with. This will be in the
1.412 +form of a tuple: the first member is any ordered arguments the mock
1.413 +was called with (or an empty tuple) and the second member is any
1.414 +keyword arguments (or an empty dictionary).</p>
1.415 +<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.416 +<span class="gp">>>> </span><span class="k">print</span> <span class="n">mock</span><span class="o">.</span><span class="n">call_args</span>
1.417 +<span class="go">None</span>
1.418 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.419 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span>
1.420 +<span class="go">call()</span>
1.421 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span> <span class="o">==</span> <span class="p">()</span>
1.422 +<span class="go">True</span>
1.423 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span>
1.424 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span>
1.425 +<span class="go">call(3, 4)</span>
1.426 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span> <span class="o">==</span> <span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">),)</span>
1.427 +<span class="go">True</span>
1.428 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s">'fish'</span><span class="p">,</span> <span class="nb">next</span><span class="o">=</span><span class="s">'w00t!'</span><span class="p">)</span>
1.429 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span>
1.430 +<span class="go">call(3, 4, 5, key='fish', next='w00t!')</span>
1.431 +</pre></div>
1.432 +</div>
1.433 +<p><cite>call_args</cite>, along with members of the lists <a class="reference internal" href="#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>,
1.434 +<a class="reference internal" href="#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> and <a class="reference internal" href="#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> are <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> objects.
1.435 +These are tuples, so they can be unpacked to get at the individual
1.436 +arguments and make more complex assertions. See
1.437 +<a class="reference internal" href="helpers.html#calls-as-tuples"><em>calls as tuples</em></a>.</p>
1.438 +</dd></dl>
1.439 +
1.440 +<dl class="attribute">
1.441 +<dt id="mock.Mock.call_args_list">
1.442 +<tt class="descname">call_args_list</tt><a class="headerlink" href="#mock.Mock.call_args_list" title="Permalink to this definition">¶</a></dt>
1.443 +<dd><p>This is a list of all the calls made to the mock object in sequence
1.444 +(so the length of the list is the number of times it has been
1.445 +called). Before any calls have been made it is an empty list. The
1.446 +<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 can be used for conveniently constructing lists of
1.447 +calls to compare with <cite>call_args_list</cite>.</p>
1.448 +<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.449 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">()</span>
1.450 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span>
1.451 +<span class="gp">>>> </span><span class="n">mock</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s">'fish'</span><span class="p">,</span> <span class="nb">next</span><span class="o">=</span><span class="s">'w00t!'</span><span class="p">)</span>
1.452 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args_list</span>
1.453 +<span class="go">[call(), call(3, 4), call(key='fish', next='w00t!')]</span>
1.454 +<span class="gp">>>> </span><span class="n">expected</span> <span class="o">=</span> <span class="p">[(),</span> <span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">),),</span> <span class="p">({</span><span class="s">'key'</span><span class="p">:</span> <span class="s">'fish'</span><span class="p">,</span> <span class="s">'next'</span><span class="p">:</span> <span class="s">'w00t!'</span><span class="p">},)]</span>
1.455 +<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.456 +<span class="go">True</span>
1.457 +</pre></div>
1.458 +</div>
1.459 +<p>Members of <cite>call_args_list</cite> are <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> objects. These can be
1.460 +unpacked as tuples to get at the individual arguments. See
1.461 +<a class="reference internal" href="helpers.html#calls-as-tuples"><em>calls as tuples</em></a>.</p>
1.462 +</dd></dl>
1.463 +
1.464 +<dl class="attribute">
1.465 +<dt id="mock.Mock.method_calls">
1.466 +<tt class="descname">method_calls</tt><a class="headerlink" href="#mock.Mock.method_calls" title="Permalink to this definition">¶</a></dt>
1.467 +<dd><p>As well as tracking calls to themselves, mocks also track calls to
1.468 +methods and attributes, and <em>their</em> methods and attributes:</p>
1.469 +<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.470 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>
1.471 +<span class="go"><Mock name='mock.method()' id='...'></span>
1.472 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">property</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">attribute</span><span class="p">()</span>
1.473 +<span class="go"><Mock name='mock.property.method.attribute()' id='...'></span>
1.474 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">method_calls</span>
1.475 +<span class="go">[call.method(), call.property.method.attribute()]</span>
1.476 +</pre></div>
1.477 +</div>
1.478 +<p>Members of <cite>method_calls</cite> are <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> objects. These can be
1.479 +unpacked as tuples to get at the individual arguments. See
1.480 +<a class="reference internal" href="helpers.html#calls-as-tuples"><em>calls as tuples</em></a>.</p>
1.481 +</dd></dl>
1.482 +
1.483 +<dl class="attribute">
1.484 +<dt id="mock.Mock.mock_calls">
1.485 +<tt class="descname">mock_calls</tt><a class="headerlink" href="#mock.Mock.mock_calls" title="Permalink to this definition">¶</a></dt>
1.486 +<dd><p><cite>mock_calls</cite> records <em>all</em> calls to the mock object, its methods, magic
1.487 +methods <em>and</em> return value mocks.</p>
1.488 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.489 +<span class="gp">>>> </span><span class="n">result</span> <span class="o">=</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.490 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">first</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
1.491 +<span class="go"><MagicMock name='mock.first()' id='...'></span>
1.492 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">second</span><span class="p">()</span>
1.493 +<span class="go"><MagicMock name='mock.second()' id='...'></span>
1.494 +<span class="gp">>>> </span><span class="nb">int</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>
1.495 +<span class="go">1</span>
1.496 +<span class="gp">>>> </span><span class="n">result</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
1.497 +<span class="go"><MagicMock name='mock()()' id='...'></span>
1.498 +<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="o">.</span><span class="n">first</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">3</span><span class="p">),</span> <span class="n">call</span><span class="o">.</span><span class="n">second</span><span class="p">(),</span>
1.499 +<span class="gp">... </span><span class="n">call</span><span class="o">.</span><span class="n">__int__</span><span class="p">(),</span> <span class="n">call</span><span class="p">()(</span><span class="mi">1</span><span class="p">)]</span>
1.500 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">mock_calls</span> <span class="o">==</span> <span class="n">expected</span>
1.501 +<span class="go">True</span>
1.502 +</pre></div>
1.503 +</div>
1.504 +<p>Members of <cite>mock_calls</cite> are <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> objects. These can be
1.505 +unpacked as tuples to get at the individual arguments. See
1.506 +<a class="reference internal" href="helpers.html#calls-as-tuples"><em>calls as tuples</em></a>.</p>
1.507 +</dd></dl>
1.508 +
1.509 +<dl class="attribute">
1.510 +<dt id="mock.Mock.__class__">
1.511 +<tt class="descname">__class__</tt><a class="headerlink" href="#mock.Mock.__class__" title="Permalink to this definition">¶</a></dt>
1.512 +<dd><p>Normally the <cite>__class__</cite> attribute of an object will return its type.
1.513 +For a mock object with a <cite>spec</cite> <cite>__class__</cite> returns the spec class
1.514 +instead. This allows mock objects to pass <cite>isinstance</cite> tests for the
1.515 +object they are replacing / masquerading as:</p>
1.516 +<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">spec</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
1.517 +<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
1.518 +<span class="go">True</span>
1.519 +</pre></div>
1.520 +</div>
1.521 +<p><cite>__class__</cite> is assignable to, this allows a mock to pass an
1.522 +<cite>isinstance</cite> check without forcing you to use a spec:</p>
1.523 +<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.524 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">__class__</span> <span class="o">=</span> <span class="nb">dict</span>
1.525 +<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="nb">dict</span><span class="p">)</span>
1.526 +<span class="go">True</span>
1.527 +</pre></div>
1.528 +</div>
1.529 +</dd></dl>
1.530 +
1.531 +</dd></dl>
1.532 +
1.533 +<dl class="class">
1.534 +<dt id="mock.NonCallableMock">
1.535 +<em class="property">class </em><tt class="descname">NonCallableMock</tt><big>(</big><em>spec=None</em>, <em>wraps=None</em>, <em>name=None</em>, <em>spec_set=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.NonCallableMock" title="Permalink to this definition">¶</a></dt>
1.536 +<dd><p>A non-callable version of <cite>Mock</cite>. The constructor parameters have the same
1.537 +meaning of <cite>Mock</cite>, with the exception of <cite>return_value</cite> and <cite>side_effect</cite>
1.538 +which have no meaning on a non-callable mock.</p>
1.539 +</dd></dl>
1.540 +
1.541 +<p>Mock objects that use a class or an instance as a <cite>spec</cite> or <cite>spec_set</cite> are able
1.542 +to pass <cite>isintance</cite> tests:</p>
1.543 +<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">spec</span><span class="o">=</span><span class="n">SomeClass</span><span class="p">)</span>
1.544 +<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="n">SomeClass</span><span class="p">)</span>
1.545 +<span class="go">True</span>
1.546 +<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">spec_set</span><span class="o">=</span><span class="n">SomeClass</span><span class="p">())</span>
1.547 +<span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="n">SomeClass</span><span class="p">)</span>
1.548 +<span class="go">True</span>
1.549 +</pre></div>
1.550 +</div>
1.551 +<p>The <cite>Mock</cite> classes have support for mocking magic methods. See <a class="reference internal" href="magicmock.html#magic-methods"><em>magic
1.552 +methods</em></a> for the full details.</p>
1.553 +<p>The mock classes and 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> decorators all take arbitrary keyword
1.554 +arguments for configuration. For the <cite>patch</cite> decorators the keywords are
1.555 +passed to the constructor of the mock being created. The keyword arguments
1.556 +are for configuring attributes of the mock:</p>
1.557 +<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><span class="n">attribute</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="s">'fish'</span><span class="p">)</span>
1.558 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">attribute</span>
1.559 +<span class="go">3</span>
1.560 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">other</span>
1.561 +<span class="go">'fish'</span>
1.562 +</pre></div>
1.563 +</div>
1.564 +<p>The return value and side effect of child mocks can be set in the same way,
1.565 +using dotted notation. As you can’t use dotted names directly in a call you
1.566 +have to create a dictionary and unpack it using <cite>**</cite>:</p>
1.567 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">attrs</span> <span class="o">=</span> <span class="p">{</span><span class="s">'method.return_value'</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s">'other.side_effect'</span><span class="p">:</span> <span class="ne">KeyError</span><span class="p">}</span>
1.568 +<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">some_attribute</span><span class="o">=</span><span class="s">'eggs'</span><span class="p">,</span> <span class="o">**</span><span class="n">attrs</span><span class="p">)</span>
1.569 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">some_attribute</span>
1.570 +<span class="go">'eggs'</span>
1.571 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>
1.572 +<span class="go">3</span>
1.573 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">other</span><span class="p">()</span>
1.574 +<span class="gt">Traceback (most recent call last):</span>
1.575 + <span class="c">...</span>
1.576 +<span class="gr">KeyError</span>
1.577 +</pre></div>
1.578 +</div>
1.579 +<dl class="class">
1.580 +<dt id="mock.PropertyMock">
1.581 +<em class="property">class </em><tt class="descname">PropertyMock</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.PropertyMock" title="Permalink to this definition">¶</a></dt>
1.582 +<dd><p>A mock intended to be used as a property, or other descriptor, on a class.
1.583 +<cite>PropertyMock</cite> provides <cite>__get__</cite> and <cite>__set__</cite> methods so you can specify
1.584 +a return value when it is fetched.</p>
1.585 +<p>Fetching a <cite>PropertyMock</cite> instance from an object calls the mock, with
1.586 +no args. Setting it calls the mock with the value being set.</p>
1.587 +<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.588 +<span class="gp">... </span> <span class="nd">@property</span>
1.589 +<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.590 +<span class="gp">... </span> <span class="k">return</span> <span class="s">'something'</span>
1.591 +<span class="gp">... </span> <span class="nd">@foo.setter</span>
1.592 +<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> <span class="n">value</span><span class="p">):</span>
1.593 +<span class="gp">... </span> <span class="k">pass</span>
1.594 +<span class="gp">...</span>
1.595 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.Foo.foo'</span><span class="p">,</span> <span class="n">new_callable</span><span class="o">=</span><span class="n">PropertyMock</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_foo</span><span class="p">:</span>
1.596 +<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">'mockity-mock'</span>
1.597 +<span class="gp">... </span> <span class="n">this_foo</span> <span class="o">=</span> <span class="n">Foo</span><span class="p">()</span>
1.598 +<span class="gp">... </span> <span class="k">print</span> <span class="n">this_foo</span><span class="o">.</span><span class="n">foo</span>
1.599 +<span class="gp">... </span> <span class="n">this_foo</span><span class="o">.</span><span class="n">foo</span> <span class="o">=</span> <span class="mi">6</span>
1.600 +<span class="gp">...</span>
1.601 +<span class="go">mockity-mock</span>
1.602 +<span class="gp">>>> </span><span class="n">mock_foo</span><span class="o">.</span><span class="n">mock_calls</span>
1.603 +<span class="go">[call(), call(6)]</span>
1.604 +</pre></div>
1.605 +</div>
1.606 +</dd></dl>
1.607 +
1.608 +<p>Because of the way mock attributes are stored you can’t directly attach a
1.609 +<cite>PropertyMock</cite> to a mock object. Instead you can attach it to the mock type
1.610 +object:</p>
1.611 +<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.612 +<span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">PropertyMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
1.613 +<span class="gp">>>> </span><span class="nb">type</span><span class="p">(</span><span class="n">m</span><span class="p">)</span><span class="o">.</span><span class="n">foo</span> <span class="o">=</span> <span class="n">p</span>
1.614 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">foo</span>
1.615 +<span class="go">3</span>
1.616 +<span class="gp">>>> </span><span class="n">p</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">()</span>
1.617 +</pre></div>
1.618 +</div>
1.619 +<span class="target" id="index-5"></span></div>
1.620 +<div class="section" id="calling">
1.621 +<span id="index-6"></span><h1>Calling<a class="headerlink" href="#calling" title="Permalink to this headline">¶</a></h1>
1.622 +<p>Mock objects are callable. The call will return the value set as the
1.623 +<a class="reference internal" href="#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. The default return value is a new Mock
1.624 +object; it is created the first time the return value is accessed (either
1.625 +explicitly or by calling the Mock) - but it is stored and the same one
1.626 +returned each time.</p>
1.627 +<p>Calls made to the object will be recorded in the attributes
1.628 +like <a class="reference internal" href="#mock.Mock.call_args" title="mock.Mock.call_args"><tt class="xref py py-attr docutils literal"><span class="pre">call_args</span></tt></a> and <a class="reference internal" href="#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.629 +<p>If <a class="reference internal" href="#mock.Mock.side_effect" title="mock.Mock.side_effect"><tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt></a> is set then it will be called after the call has
1.630 +been recorded, so if <cite>side_effect</cite> raises an exception the call is still
1.631 +recorded.</p>
1.632 +<p>The simplest way to make a mock raise an exception when called is to make
1.633 +<a class="reference internal" href="#mock.Mock.side_effect" title="mock.Mock.side_effect"><tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt></a> an exception class or instance:</p>
1.634 +<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><span class="n">side_effect</span><span class="o">=</span><span class="ne">IndexError</span><span class="p">)</span>
1.635 +<span class="gp">>>> </span><span class="n">m</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.636 +<span class="gt">Traceback (most recent call last):</span>
1.637 + <span class="c">...</span>
1.638 +<span class="gr">IndexError</span>
1.639 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span>
1.640 +<span class="go">[call(1, 2, 3)]</span>
1.641 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="ne">KeyError</span><span class="p">(</span><span class="s">'Bang!'</span><span class="p">)</span>
1.642 +<span class="gp">>>> </span><span class="n">m</span><span class="p">(</span><span class="s">'two'</span><span class="p">,</span> <span class="s">'three'</span><span class="p">,</span> <span class="s">'four'</span><span class="p">)</span>
1.643 +<span class="gt">Traceback (most recent call last):</span>
1.644 + <span class="c">...</span>
1.645 +<span class="gr">KeyError</span>: <span class="n">'Bang!'</span>
1.646 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span>
1.647 +<span class="go">[call(1, 2, 3), call('two', 'three', 'four')]</span>
1.648 +</pre></div>
1.649 +</div>
1.650 +<p>If <cite>side_effect</cite> is a function then whatever that function returns is what
1.651 +calls to the mock return. The <cite>side_effect</cite> function is called with the
1.652 +same arguments as the mock. This allows you to vary the return value of the
1.653 +call dynamically, based on the input:</p>
1.654 +<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="n">value</span><span class="p">):</span>
1.655 +<span class="gp">... </span> <span class="k">return</span> <span class="n">value</span> <span class="o">+</span> <span class="mi">1</span>
1.656 +<span class="gp">...</span>
1.657 +<span class="gp">>>> </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</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.658 +<span class="gp">>>> </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
1.659 +<span class="go">2</span>
1.660 +<span class="gp">>>> </span><span class="n">m</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
1.661 +<span class="go">3</span>
1.662 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span>
1.663 +<span class="go">[call(1), call(2)]</span>
1.664 +</pre></div>
1.665 +</div>
1.666 +<p>If you want the mock to still return the default return value (a new mock), or
1.667 +any set return value, then there are two ways of doing this. Either return
1.668 +<cite>mock.return_value</cite> from inside <cite>side_effect</cite>, or return <a class="reference internal" href="sentinel.html#mock.DEFAULT" title="mock.DEFAULT"><tt class="xref py py-data docutils literal"><span class="pre">DEFAULT</span></tt></a>:</p>
1.669 +<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.670 +<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.671 +<span class="gp">... </span> <span class="k">return</span> <span class="n">m</span><span class="o">.</span><span class="n">return_value</span>
1.672 +<span class="gp">...</span>
1.673 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">side_effect</span>
1.674 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="mi">3</span>
1.675 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.676 +<span class="go">3</span>
1.677 +<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.678 +<span class="gp">... </span> <span class="k">return</span> <span class="n">DEFAULT</span>
1.679 +<span class="gp">...</span>
1.680 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">side_effect</span>
1.681 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.682 +<span class="go">3</span>
1.683 +</pre></div>
1.684 +</div>
1.685 +<p>To remove a <cite>side_effect</cite>, and return to the default behaviour, set the
1.686 +<cite>side_effect</cite> to <cite>None</cite>:</p>
1.687 +<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><span class="n">return_value</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span>
1.688 +<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.689 +<span class="gp">... </span> <span class="k">return</span> <span class="mi">3</span>
1.690 +<span class="gp">...</span>
1.691 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">side_effect</span>
1.692 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.693 +<span class="go">3</span>
1.694 +<span class="gp">>>> </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="bp">None</span>
1.695 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.696 +<span class="go">6</span>
1.697 +</pre></div>
1.698 +</div>
1.699 +<p>The <cite>side_effect</cite> can also be any iterable object. Repeated calls to the mock
1.700 +will return values from the iterable (until the iterable is exhausted and
1.701 +a <cite>StopIteration</cite> is raised):</p>
1.702 +<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><span class="n">side_effect</span><span class="o">=</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.703 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.704 +<span class="go">1</span>
1.705 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.706 +<span class="go">2</span>
1.707 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.708 +<span class="go">3</span>
1.709 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.710 +<span class="gt">Traceback (most recent call last):</span>
1.711 + <span class="c">...</span>
1.712 +<span class="gr">StopIteration</span>
1.713 +</pre></div>
1.714 +</div>
1.715 +<p>If any members of the iterable are exceptions they will be raised instead of
1.716 +returned:</p>
1.717 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">iterable</span> <span class="o">=</span> <span class="p">(</span><span class="mi">33</span><span class="p">,</span> <span class="ne">ValueError</span><span class="p">,</span> <span class="mi">66</span><span class="p">)</span>
1.718 +<span class="gp">>>> </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="n">iterable</span><span class="p">)</span>
1.719 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.720 +<span class="go">33</span>
1.721 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.722 +<span class="gt">Traceback (most recent call last):</span>
1.723 + <span class="c">...</span>
1.724 +<span class="gr">ValueError</span>
1.725 +<span class="gp">>>> </span><span class="n">m</span><span class="p">()</span>
1.726 +<span class="go">66</span>
1.727 +</pre></div>
1.728 +</div>
1.729 +</div>
1.730 +<div class="section" id="deleting-attributes">
1.731 +<span id="id2"></span><h1>Deleting Attributes<a class="headerlink" href="#deleting-attributes" title="Permalink to this headline">¶</a></h1>
1.732 +<p>Mock objects create attributes on demand. This allows them to pretend to be
1.733 +objects of any type.</p>
1.734 +<p>You may want a mock object to return <cite>False</cite> to a <cite>hasattr</cite> call, or raise an
1.735 +<cite>AttributeError</cite> when an attribute is fetched. You can do this by providing
1.736 +an object as a <cite>spec</cite> for a mock, but that isn’t always convenient.</p>
1.737 +<p>You “block” attributes by deleting them. Once deleted, accessing an attribute
1.738 +will raise an <cite>AttributeError</cite>.</p>
1.739 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.740 +<span class="gp">>>> </span><span class="nb">hasattr</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="s">'m'</span><span class="p">)</span>
1.741 +<span class="go">True</span>
1.742 +<span class="gp">>>> </span><span class="k">del</span> <span class="n">mock</span><span class="o">.</span><span class="n">m</span>
1.743 +<span class="gp">>>> </span><span class="nb">hasattr</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="s">'m'</span><span class="p">)</span>
1.744 +<span class="go">False</span>
1.745 +<span class="gp">>>> </span><span class="k">del</span> <span class="n">mock</span><span class="o">.</span><span class="n">f</span>
1.746 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">f</span>
1.747 +<span class="gt">Traceback (most recent call last):</span>
1.748 + <span class="o">...</span>
1.749 +<span class="gr">AttributeError</span>: <span class="n">f</span>
1.750 +</pre></div>
1.751 +</div>
1.752 +</div>
1.753 +<div class="section" id="attaching-mocks-as-attributes">
1.754 +<h1>Attaching Mocks as Attributes<a class="headerlink" href="#attaching-mocks-as-attributes" title="Permalink to this headline">¶</a></h1>
1.755 +<p>When you attach a mock as an attribute of another mock (or as the return
1.756 +value) it becomes a “child” of that mock. Calls to the child are recorded in
1.757 +the <a class="reference internal" href="#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> and <a class="reference internal" href="#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> attributes of the
1.758 +parent. This is useful for configuring child mocks and then attaching them to
1.759 +the parent, or for attaching mocks to a parent that records all calls to the
1.760 +children and allows you to make assertions about the order of calls between
1.761 +mocks:</p>
1.762 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parent</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.763 +<span class="gp">>>> </span><span class="n">child1</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
1.764 +<span class="gp">>>> </span><span class="n">child2</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
1.765 +<span class="gp">>>> </span><span class="n">parent</span><span class="o">.</span><span class="n">child1</span> <span class="o">=</span> <span class="n">child1</span>
1.766 +<span class="gp">>>> </span><span class="n">parent</span><span class="o">.</span><span class="n">child2</span> <span class="o">=</span> <span class="n">child2</span>
1.767 +<span class="gp">>>> </span><span class="n">child1</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
1.768 +<span class="gp">>>> </span><span class="n">child2</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
1.769 +<span class="gp">>>> </span><span class="n">parent</span><span class="o">.</span><span class="n">mock_calls</span>
1.770 +<span class="go">[call.child1(1), call.child2(2)]</span>
1.771 +</pre></div>
1.772 +</div>
1.773 +<p>The exception to this is if the mock has a name. This allows you to prevent
1.774 +the “parenting” if for some reason you don’t want it to happen.</p>
1.775 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mock</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.776 +<span class="gp">>>> </span><span class="n">not_a_child</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">'not-a-child'</span><span class="p">)</span>
1.777 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">attribute</span> <span class="o">=</span> <span class="n">not_a_child</span>
1.778 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">attribute</span><span class="p">()</span>
1.779 +<span class="go"><MagicMock name='not-a-child()' id='...'></span>
1.780 +<span class="gp">>>> </span><span class="n">mock</span><span class="o">.</span><span class="n">mock_calls</span>
1.781 +<span class="go">[]</span>
1.782 +</pre></div>
1.783 +</div>
1.784 +<p>Mocks created for you by <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> are automatically given names. To
1.785 +attach mocks that have names to a parent you use the <a class="reference internal" href="#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>
1.786 +method:</p>
1.787 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">thing1</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>
1.788 +<span class="gp">>>> </span><span class="n">thing2</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>
1.789 +<span class="gp">>>> </span><span class="n">parent</span> <span class="o">=</span> <span class="n">MagicMock</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">'__main__.thing1'</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">child1</span><span class="p">:</span>
1.791 +<span class="gp">... </span> <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.thing2'</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">child2</span><span class="p">:</span>
1.792 +<span class="gp">... </span> <span class="n">parent</span><span class="o">.</span><span class="n">attach_mock</span><span class="p">(</span><span class="n">child1</span><span class="p">,</span> <span class="s">'child1'</span><span class="p">)</span>
1.793 +<span class="gp">... </span> <span class="n">parent</span><span class="o">.</span><span class="n">attach_mock</span><span class="p">(</span><span class="n">child2</span><span class="p">,</span> <span class="s">'child2'</span><span class="p">)</span>
1.794 +<span class="gp">... </span> <span class="n">child1</span><span class="p">(</span><span class="s">'one'</span><span class="p">)</span>
1.795 +<span class="gp">... </span> <span class="n">child2</span><span class="p">(</span><span class="s">'two'</span><span class="p">)</span>
1.796 +<span class="gp">...</span>
1.797 +<span class="gp">>>> </span><span class="n">parent</span><span class="o">.</span><span class="n">mock_calls</span>
1.798 +<span class="go">[call.child1('one'), call.child2('two')]</span>
1.799 +</pre></div>
1.800 +</div>
1.801 +<hr class="docutils" />
1.802 +<table class="docutils footnote" frame="void" id="id3" rules="none">
1.803 +<colgroup><col class="label" /><col /></colgroup>
1.804 +<tbody valign="top">
1.805 +<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>The only exceptions are magic methods and attributes (those that have
1.806 +leading and trailing double underscores). Mock doesn’t create these but
1.807 +instead of raises an <tt class="docutils literal"><span class="pre">AttributeError</span></tt>. This is because the interpreter
1.808 +will often implicitly request these methods, and gets <em>very</em> confused to
1.809 +get a new Mock object when it expects a magic method. If you need magic
1.810 +method support see <a class="reference internal" href="magicmock.html#magic-methods"><em>magic methods</em></a>.</td></tr>
1.811 +</tbody>
1.812 +</table>
1.813 +</div>
1.814 +
1.815 +
1.816 + </div>
1.817 + </div>
1.818 + </div>
1.819 + <div class="sphinxsidebar">
1.820 + <div class="sphinxsidebarwrapper">
1.821 + <h3><a href="index.html">Table Of Contents</a></h3>
1.822 + <ul>
1.823 +<li><a class="reference internal" href="#">The Mock Class</a></li>
1.824 +<li><a class="reference internal" href="#calling">Calling</a></li>
1.825 +<li><a class="reference internal" href="#deleting-attributes">Deleting Attributes</a></li>
1.826 +<li><a class="reference internal" href="#attaching-mocks-as-attributes">Attaching Mocks as Attributes</a></li>
1.827 +</ul>
1.828 +
1.829 + <h4>Previous topic</h4>
1.830 + <p class="topless"><a href="index.html"
1.831 + title="previous chapter">Mock - Mocking and Testing Library</a></p>
1.832 + <h4>Next topic</h4>
1.833 + <p class="topless"><a href="patch.html"
1.834 + title="next chapter">Patch Decorators</a></p>
1.835 + <h3>This Page</h3>
1.836 + <ul class="this-page-menu">
1.837 + <li><a href="_sources/mock.txt"
1.838 + rel="nofollow">Show Source</a></li>
1.839 + </ul>
1.840 +<div id="searchbox" style="display: none">
1.841 + <h3>Quick search</h3>
1.842 + <form class="search" action="search.html" method="get">
1.843 + <input type="text" name="q" />
1.844 + <input type="submit" value="Go" />
1.845 + <input type="hidden" name="check_keywords" value="yes" />
1.846 + <input type="hidden" name="area" value="default" />
1.847 + </form>
1.848 + <p class="searchtip" style="font-size: 90%">
1.849 + Enter search terms or a module, class or function name.
1.850 + </p>
1.851 +</div>
1.852 +<script type="text/javascript">$('#searchbox').show(0);</script>
1.853 + </div>
1.854 + </div>
1.855 + <div class="clearer"></div>
1.856 + </div>
1.857 + <div class="related">
1.858 + <h3>Navigation</h3>
1.859 + <ul>
1.860 + <li class="right" style="margin-right: 10px">
1.861 + <a href="genindex.html" title="General Index"
1.862 + >index</a></li>
1.863 + <li class="right" >
1.864 + <a href="patch.html" title="Patch Decorators"
1.865 + >next</a> |</li>
1.866 + <li class="right" >
1.867 + <a href="index.html" title="Mock - Mocking and Testing Library"
1.868 + >previous</a> |</li>
1.869 + <li><a href="index.html">Mock 1.0.0 documentation</a> »</li>
1.870 + </ul>
1.871 + </div>
1.872 + <div class="footer">
1.873 + © Copyright 2007-2012, Michael Foord & the mock team.
1.874 + Last updated on Oct 07, 2012.
1.875 + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
1.876 + </div>
1.877 + </body>
1.878 +</html>
1.879 \ No newline at end of file
