The Tor Browser / file comparison

comparison: python/mock-1.0.0/html/index.html

python/mock-1.0.0/html/index.html

branch
TOR_BUG_3246
changeset 6
8bccb770b82d
equal deleted inserted replaced
-1:000000000000 0:2c0f9257b148
1
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5
6 <html xmlns="http://www.w3.org/1999/xhtml">
7 <head>
8 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9
10 <title>Mock - Mocking and Testing Library &mdash; Mock 1.0.0 documentation</title>
11
12 <link rel="stylesheet" href="_static/nature.css" type="text/css" />
13 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
14
15 <script type="text/javascript">
16 var DOCUMENTATION_OPTIONS = {
17 URL_ROOT: '',
18 VERSION: '1.0.0',
19 COLLAPSE_INDEX: false,
20 FILE_SUFFIX: '.html',
21 HAS_SOURCE: true
22 };
23 </script>
24 <script type="text/javascript" src="_static/jquery.js"></script>
25 <script type="text/javascript" src="_static/underscore.js"></script>
26 <script type="text/javascript" src="_static/doctools.js"></script>
27 <link rel="top" title="Mock 1.0.0 documentation" href="#" />
28 <link rel="next" title="The Mock Class" href="mock.html" />
29 </head>
30 <body>
31 <div class="related">
32 <h3>Navigation</h3>
33 <ul>
34 <li class="right" style="margin-right: 10px">
35 <a href="genindex.html" title="General Index"
36 accesskey="I">index</a></li>
37 <li class="right" >
38 <a href="mock.html" title="The Mock Class"
39 accesskey="N">next</a> |</li>
40 <li><a href="#">Mock 1.0.0 documentation</a> &raquo;</li>
41 </ul>
42 </div>
43
44 <div class="document">
45 <div class="documentwrapper">
46 <div class="bodywrapper">
47 <div class="body">
48
49 <div class="section" id="mock-mocking-and-testing-library">
50 <h1>Mock - Mocking and Testing Library<a class="headerlink" href="#mock-mocking-and-testing-library" title="Permalink to this headline">¶</a></h1>
51 <table class="docutils field-list" frame="void" rules="none">
52 <col class="field-name" />
53 <col class="field-body" />
54 <tbody valign="top">
55 <tr class="field-odd field"><th class="field-name">Author:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/weblog/index.shtml">Michael Foord</a></td>
56 </tr>
57 <tr class="field-even field"><th class="field-name">Version:</th><td class="field-body">1.0.0</td>
58 </tr>
59 <tr class="field-odd field"><th class="field-name">Date:</th><td class="field-body">2012/10/07</td>
60 </tr>
61 <tr class="field-even field"><th class="field-name">Homepage:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/mock/">Mock Homepage</a></td>
62 </tr>
63 <tr class="field-odd field"><th class="field-name">Download:</th><td class="field-body"><a class="reference external" href="http://pypi.python.org/pypi/mock">Mock on PyPI</a></td>
64 </tr>
65 <tr class="field-even field"><th class="field-name">Documentation:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/downloads/mock-1.0.0.pdf">PDF Documentation</a></td>
66 </tr>
67 <tr class="field-odd field"><th class="field-name">License:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/license.shtml">BSD License</a></td>
68 </tr>
69 <tr class="field-even field"><th class="field-name">Support:</th><td class="field-body"><a class="reference external" href="http://lists.idyll.org/listinfo/testing-in-python">Mailing list (testing-in-python&#64;lists.idyll.org)</a></td>
70 </tr>
71 <tr class="field-odd field"><th class="field-name">Issue tracker:</th><td class="field-body"><a class="reference external" href="http://code.google.com/p/mock/issues/list">Google code project</a></td>
72 </tr>
73 </tbody>
74 </table>
75 <span class="target" id="module-mock"></span><p id="index-0">mock is a library for testing in Python. It allows you to replace parts of
76 your system under test with mock objects and make assertions about how they
77 have been used.</p>
78 <p>mock is now part of the Python standard library, available as <a class="reference external" href="http://docs.python.org/py3k/library/unittest.mock.html#module-unittest.mock">unittest.mock</a>
79 in Python 3.3 onwards.</p>
80 <p>mock provides a core <a class="reference internal" href="mock.html#mock.Mock" title="mock.Mock"><tt class="xref py py-class docutils literal"><span class="pre">Mock</span></tt></a> class removing the need to create a host
81 of stubs throughout your test suite. After performing an action, you can make
82 assertions about which methods / attributes were used and arguments they were
83 called with. You can also specify return values and set needed attributes in
84 the normal way.</p>
85 <p>Additionally, mock provides a <a class="reference internal" href="patch.html#mock.patch" title="mock.patch"><tt class="xref py py-func docutils literal"><span class="pre">patch()</span></tt></a> decorator that handles patching
86 module and class level attributes within the scope of a test, along with
87 <a class="reference internal" href="sentinel.html#mock.sentinel" title="mock.sentinel"><tt class="xref py py-const docutils literal"><span class="pre">sentinel</span></tt></a> for creating unique objects. See the <a class="reference internal" href="#quick-guide">quick guide</a> for
88 some examples of how to use <a class="reference internal" href="mock.html#mock.Mock" title="mock.Mock"><tt class="xref py py-class docutils literal"><span class="pre">Mock</span></tt></a>, <a class="reference internal" href="magicmock.html#mock.MagicMock" title="mock.MagicMock"><tt class="xref py py-class docutils literal"><span class="pre">MagicMock</span></tt></a> and
89 <a class="reference internal" href="patch.html#mock.patch" title="mock.patch"><tt class="xref py py-func docutils literal"><span class="pre">patch()</span></tt></a>.</p>
90 <p>Mock is very easy to use and is designed for use with
91 <a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest</a>. Mock is based on
92 the &#8216;action -&gt; assertion&#8217; pattern instead of <cite>&#8216;record -&gt; replay&#8217;</cite> used by many
93 mocking frameworks.</p>
94 <p>mock is tested on Python versions 2.4-2.7, Python 3 plus the latest versions of
95 Jython and PyPy.</p>
96 <div class="section" id="api-documentation">
97 <h2>API Documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2>
98 <div class="toctree-wrapper compound">
99 <ul>
100 <li class="toctree-l1"><a class="reference internal" href="mock.html">The Mock Class</a></li>
101 <li class="toctree-l1"><a class="reference internal" href="mock.html#calling">Calling</a></li>
102 <li class="toctree-l1"><a class="reference internal" href="mock.html#deleting-attributes">Deleting Attributes</a></li>
103 <li class="toctree-l1"><a class="reference internal" href="mock.html#attaching-mocks-as-attributes">Attaching Mocks as Attributes</a></li>
104 <li class="toctree-l1"><a class="reference internal" href="patch.html">Patch Decorators</a><ul>
105 <li class="toctree-l2"><a class="reference internal" href="patch.html#patch">patch</a></li>
106 <li class="toctree-l2"><a class="reference internal" href="patch.html#patch-object">patch.object</a></li>
107 <li class="toctree-l2"><a class="reference internal" href="patch.html#patch-dict">patch.dict</a></li>
108 <li class="toctree-l2"><a class="reference internal" href="patch.html#patch-multiple">patch.multiple</a></li>
109 <li class="toctree-l2"><a class="reference internal" href="patch.html#patch-methods-start-and-stop">patch methods: start and stop</a></li>
110 <li class="toctree-l2"><a class="reference internal" href="patch.html#test-prefix">TEST_PREFIX</a></li>
111 <li class="toctree-l2"><a class="reference internal" href="patch.html#nesting-patch-decorators">Nesting Patch Decorators</a></li>
112 <li class="toctree-l2"><a class="reference internal" href="patch.html#where-to-patch">Where to patch</a></li>
113 <li class="toctree-l2"><a class="reference internal" href="patch.html#patching-descriptors-and-proxy-objects">Patching Descriptors and Proxy Objects</a></li>
114 </ul>
115 </li>
116 <li class="toctree-l1"><a class="reference internal" href="helpers.html">Helpers</a><ul>
117 <li class="toctree-l2"><a class="reference internal" href="helpers.html#call">call</a></li>
118 <li class="toctree-l2"><a class="reference internal" href="helpers.html#create-autospec">create_autospec</a></li>
119 <li class="toctree-l2"><a class="reference internal" href="helpers.html#any">ANY</a></li>
120 <li class="toctree-l2"><a class="reference internal" href="helpers.html#filter-dir">FILTER_DIR</a></li>
121 <li class="toctree-l2"><a class="reference internal" href="helpers.html#mock-open">mock_open</a></li>
122 <li class="toctree-l2"><a class="reference internal" href="helpers.html#autospeccing">Autospeccing</a></li>
123 </ul>
124 </li>
125 <li class="toctree-l1"><a class="reference internal" href="sentinel.html">Sentinel</a><ul>
126 <li class="toctree-l2"><a class="reference internal" href="sentinel.html#sentinel-example">Sentinel Example</a></li>
127 </ul>
128 </li>
129 <li class="toctree-l1"><a class="reference internal" href="magicmock.html">Mocking Magic Methods</a></li>
130 <li class="toctree-l1"><a class="reference internal" href="magicmock.html#magic-mock">Magic Mock</a></li>
131 </ul>
132 </div>
133 </div>
134 <div class="section" id="user-guide">
135 <h2>User Guide<a class="headerlink" href="#user-guide" title="Permalink to this headline">¶</a></h2>
136 <div class="toctree-wrapper compound">
137 <ul>
138 <li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started with Mock</a><ul>
139 <li class="toctree-l2"><a class="reference internal" href="getting-started.html#using-mock">Using Mock</a></li>
140 <li class="toctree-l2"><a class="reference internal" href="getting-started.html#patch-decorators">Patch Decorators</a></li>
141 </ul>
142 </li>
143 <li class="toctree-l1"><a class="reference internal" href="examples.html">Further Examples</a><ul>
144 <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-chained-calls">Mocking chained calls</a></li>
145 <li class="toctree-l2"><a class="reference internal" href="examples.html#partial-mocking">Partial mocking</a></li>
146 <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-a-generator-method">Mocking a Generator Method</a></li>
147 <li class="toctree-l2"><a class="reference internal" href="examples.html#applying-the-same-patch-to-every-test-method">Applying the same patch to every test method</a></li>
148 <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-unbound-methods">Mocking Unbound Methods</a></li>
149 <li class="toctree-l2"><a class="reference internal" href="examples.html#checking-multiple-calls-with-mock">Checking multiple calls with mock</a></li>
150 <li class="toctree-l2"><a class="reference internal" href="examples.html#coping-with-mutable-arguments">Coping with mutable arguments</a></li>
151 <li class="toctree-l2"><a class="reference internal" href="examples.html#raising-exceptions-on-attribute-access">Raising exceptions on attribute access</a></li>
152 <li class="toctree-l2"><a class="reference internal" href="examples.html#multiple-calls-with-different-effects">Multiple calls with different effects</a></li>
153 <li class="toctree-l2"><a class="reference internal" href="examples.html#nesting-patches">Nesting Patches</a></li>
154 <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-a-dictionary-with-magicmock">Mocking a dictionary with MagicMock</a></li>
155 <li class="toctree-l2"><a class="reference internal" href="examples.html#mock-subclasses-and-their-attributes">Mock subclasses and their attributes</a></li>
156 <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-imports-with-patch-dict">Mocking imports with patch.dict</a></li>
157 <li class="toctree-l2"><a class="reference internal" href="examples.html#tracking-order-of-calls-and-less-verbose-call-assertions">Tracking order of calls and less verbose call assertions</a></li>
158 <li class="toctree-l2"><a class="reference internal" href="examples.html#more-complex-argument-matching">More complex argument matching</a></li>
159 <li class="toctree-l2"><a class="reference internal" href="examples.html#less-verbose-configuration-of-mock-objects">Less verbose configuration of mock objects</a></li>
160 <li class="toctree-l2"><a class="reference internal" href="examples.html#matching-any-argument-in-assertions">Matching any argument in assertions</a></li>
161 <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-properties">Mocking Properties</a></li>
162 <li class="toctree-l2"><a class="reference internal" href="examples.html#mocking-open">Mocking open</a></li>
163 <li class="toctree-l2"><a class="reference internal" href="examples.html#mocks-without-some-attributes">Mocks without some attributes</a></li>
164 </ul>
165 </li>
166 <li class="toctree-l1"><a class="reference internal" href="compare.html">Mock Library Comparison</a><ul>
167 <li class="toctree-l2"><a class="reference internal" href="compare.html#simple-fake-object">Simple fake object</a></li>
168 <li class="toctree-l2"><a class="reference internal" href="compare.html#simple-mock">Simple mock</a></li>
169 <li class="toctree-l2"><a class="reference internal" href="compare.html#creating-partial-mocks">Creating partial mocks</a></li>
170 <li class="toctree-l2"><a class="reference internal" href="compare.html#ensure-calls-are-made-in-specific-order">Ensure calls are made in specific order</a></li>
171 <li class="toctree-l2"><a class="reference internal" href="compare.html#raising-exceptions">Raising exceptions</a></li>
172 <li class="toctree-l2"><a class="reference internal" href="compare.html#override-new-instances-of-a-class">Override new instances of a class</a></li>
173 <li class="toctree-l2"><a class="reference internal" href="compare.html#call-the-same-method-multiple-times">Call the same method multiple times</a></li>
174 <li class="toctree-l2"><a class="reference internal" href="compare.html#mock-chained-methods">Mock chained methods</a></li>
175 <li class="toctree-l2"><a class="reference internal" href="compare.html#mocking-a-context-manager">Mocking a context manager</a></li>
176 <li class="toctree-l2"><a class="reference internal" href="compare.html#mocking-the-builtin-open-used-as-a-context-manager">Mocking the builtin open used as a context manager</a></li>
177 </ul>
178 </li>
179 <li class="toctree-l1"><a class="reference internal" href="changelog.html">CHANGELOG</a><ul>
180 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-1-0-0">2012/10/07 Version 1.0.0</a></li>
181 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-1-0-0-beta-1">2012/07/13 Version 1.0.0 beta 1</a></li>
182 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-1-0-0-alpha-2">2012/05/04 Version 1.0.0 alpha 2</a></li>
183 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-1-0-0-alpha-1">2012/03/25 Version 1.0.0 alpha 1</a></li>
184 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0">2012/02/13 Version 0.8.0</a></li>
185 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-release-candidate-2">2012/01/10 Version 0.8.0 release candidate 2</a></li>
186 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-release-candidate-1">2011/12/29 Version 0.8.0 release candidate 1</a></li>
187 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-beta-4">2011/10/09 Version 0.8.0 beta 4</a></li>
188 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-beta-3">2011/08/15 Version 0.8.0 beta 3</a></li>
189 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-beta-2">2011/08/05 Version 0.8.0 beta 2</a></li>
190 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-beta-1">2011/07/25 Version 0.8.0 beta 1</a></li>
191 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-alpha-2">2011/07/16 Version 0.8.0 alpha 2</a></li>
192 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-8-0-alpha-1">2011/06/14 Version 0.8.0 alpha 1</a></li>
193 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-2">2011/05/30 Version 0.7.2</a></li>
194 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-1">2011/05/06 Version 0.7.1</a></li>
195 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0">2011/03/05 Version 0.7.0</a></li>
196 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-rc-1">2011/02/16 Version 0.7.0 RC 1</a></li>
197 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-beta-4">2010/11/12 Version 0.7.0 beta 4</a></li>
198 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-beta-3">2010/09/18 Version 0.7.0 beta 3</a></li>
199 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-beta-2">2010/06/23 Version 0.7.0 beta 2</a></li>
200 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-7-0-beta-1">2010/06/22 Version 0.7.0 beta 1</a></li>
201 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-6-0">2009/08/22 Version 0.6.0</a></li>
202 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-5-0">2009/04/17 Version 0.5.0</a></li>
203 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-4-0">2008/10/12 Version 0.4.0</a></li>
204 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-3-1">2007/12/03 Version 0.3.1</a></li>
205 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-3-0">2007/11/30 Version 0.3.0</a></li>
206 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-2-1">2007/11/21 Version 0.2.1</a></li>
207 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-2-0">2007/11/20 Version 0.2.0</a></li>
208 <li class="toctree-l2"><a class="reference internal" href="changelog.html#version-0-1-0">2007/11/19 Version 0.1.0</a></li>
209 </ul>
210 </li>
211 <li class="toctree-l1"><a class="reference internal" href="changelog.html#todo-and-limitations">TODO and Limitations</a></li>
212 </ul>
213 </div>
214 </div>
215 <div class="section" id="installing">
216 <span id="index-1"></span><h2>Installing<a class="headerlink" href="#installing" title="Permalink to this headline">¶</a></h2>
217 <p>The current version is 1.0.0. Mock is stable and widely used. If you do
218 find any bugs, or have suggestions for improvements / extensions
219 then please contact us.</p>
220 <ul class="simple">
221 <li><a class="reference external" href="http://pypi.python.org/pypi/mock">mock on PyPI</a></li>
222 <li><a class="reference external" href="http://www.voidspace.org.uk/downloads/mock-1.0.0.pdf">mock documentation as PDF</a></li>
223 <li><a class="reference external" href="http://code.google.com/p/mock/">Google Code Home &amp; Mercurial Repository</a></li>
224 </ul>
225 <span class="target" id="index-2"></span><p id="index-3">You can checkout the latest development version from the Google Code Mercurial
226 repository with the following command:</p>
227 <blockquote>
228 <div><tt class="docutils literal"><span class="pre">hg</span> <span class="pre">clone</span> <span class="pre">https://mock.googlecode.com/hg/</span> <span class="pre">mock</span></tt></div></blockquote>
229 <span class="target" id="index-4"></span><span class="target" id="index-5"></span><p id="index-6">If you have pip, setuptools or distribute you can install mock with:</p>
230 <blockquote>
231 <div><div class="line-block">
232 <div class="line"><tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">-U</span> <span class="pre">mock</span></tt></div>
233 <div class="line"><tt class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-U</span> <span class="pre">mock</span></tt></div>
234 </div>
235 </div></blockquote>
236 <p>Alternatively you can download the mock distribution from PyPI and after
237 unpacking run:</p>
238 <blockquote>
239 <div><tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></tt></div></blockquote>
240 </div>
241 <div class="section" id="quick-guide">
242 <h2>Quick Guide<a class="headerlink" href="#quick-guide" title="Permalink to this headline">¶</a></h2>
243 <p><a class="reference internal" href="mock.html#mock.Mock" title="mock.Mock"><tt class="xref py py-class docutils literal"><span class="pre">Mock</span></tt></a> and <a class="reference internal" href="magicmock.html#mock.MagicMock" title="mock.MagicMock"><tt class="xref py py-class docutils literal"><span class="pre">MagicMock</span></tt></a> objects create all attributes and
244 methods as you access them and store details of how they have been used. You
245 can configure them, to specify return values or limit what attributes are
246 available, and then make assertions about how they have been used:</p>
247 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">MagicMock</span>
248 <span class="gp">&gt;&gt;&gt; </span><span class="n">thing</span> <span class="o">=</span> <span class="n">ProductionClass</span><span class="p">()</span>
249 <span class="gp">&gt;&gt;&gt; </span><span class="n">thing</span><span class="o">.</span><span class="n">method</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
250 <span class="gp">&gt;&gt;&gt; </span><span class="n">thing</span><span class="o">.</span><span class="n">method</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s">&#39;value&#39;</span><span class="p">)</span>
251 <span class="go">3</span>
252 <span class="gp">&gt;&gt;&gt; </span><span class="n">thing</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s">&#39;value&#39;</span><span class="p">)</span>
253 </pre></div>
254 </div>
255 <p><tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt> allows you to perform side effects, including raising an
256 exception when a mock is called:</p>
257 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="ne">KeyError</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">))</span>
258 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>
259 <span class="gt">Traceback (most recent call last):</span>
260 <span class="c">...</span>
261 <span class="gr">KeyError</span>: <span class="n">&#39;foo&#39;</span>
262
263 <span class="gp">&gt;&gt;&gt; </span><span class="n">values</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;a&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="s">&#39;c&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">}</span>
264 <span class="gp">&gt;&gt;&gt; </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>
265 <span class="gp">... </span> <span class="k">return</span> <span class="n">values</span><span class="p">[</span><span class="n">arg</span><span class="p">]</span>
266 <span class="gp">...</span>
267 <span class="gp">&gt;&gt;&gt; </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>
268 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">),</span> <span class="n">mock</span><span class="p">(</span><span class="s">&#39;b&#39;</span><span class="p">),</span> <span class="n">mock</span><span class="p">(</span><span class="s">&#39;c&#39;</span><span class="p">)</span>
269 <span class="go">(1, 2, 3)</span>
270 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="p">[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span>
271 <span class="gp">&gt;&gt;&gt; </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>
272 <span class="go">(5, 4, 3)</span>
273 </pre></div>
274 </div>
275 <p>Mock has many other ways you can configure it and control its behaviour. For
276 example the <cite>spec</cite> argument configures the mock to take its specification
277 from another object. Attempting to access attributes or methods on the mock
278 that don&#8217;t exist on the spec will fail with an <cite>AttributeError</cite>.</p>
279 <p>The <a class="reference internal" href="patch.html#mock.patch" title="mock.patch"><tt class="xref py py-func docutils literal"><span class="pre">patch()</span></tt></a> decorator / context manager makes it easy to mock classes or
280 objects in a module under test. The object you specify will be replaced with a
281 mock (or other object) during the test and restored when the test ends:</p>
282 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">patch</span>
283 <span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s">&#39;module.ClassName2&#39;</span><span class="p">)</span>
284 <span class="gp">... </span><span class="nd">@patch</span><span class="p">(</span><span class="s">&#39;module.ClassName1&#39;</span><span class="p">)</span>
285 <span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">MockClass1</span><span class="p">,</span> <span class="n">MockClass2</span><span class="p">):</span>
286 <span class="gp">... </span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName1</span><span class="p">()</span>
287 <span class="gp">... </span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName2</span><span class="p">()</span>
288
289 <span class="gp">... </span> <span class="k">assert</span> <span class="n">MockClass1</span> <span class="ow">is</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName1</span>
290 <span class="gp">... </span> <span class="k">assert</span> <span class="n">MockClass2</span> <span class="ow">is</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName2</span>
291 <span class="gp">... </span> <span class="k">assert</span> <span class="n">MockClass1</span><span class="o">.</span><span class="n">called</span>
292 <span class="gp">... </span> <span class="k">assert</span> <span class="n">MockClass2</span><span class="o">.</span><span class="n">called</span>
293 <span class="gp">...</span>
294 <span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">()</span>
295 </pre></div>
296 </div>
297 <div class="admonition note">
298 <p class="first admonition-title">Note</p>
299 <p>When you nest patch decorators the mocks are passed in to the decorated
300 function in the same order they applied (the normal <em>python</em> order that
301 decorators are applied). This means from the bottom up, so in the example
302 above the mock for <cite>module.ClassName1</cite> is passed in first.</p>
303 <p class="last">With <cite>patch</cite> it matters that you patch objects in the namespace where they
304 are looked up. This is normally straightforward, but for a quick guide
305 read <a class="reference internal" href="patch.html#where-to-patch"><em>where to patch</em></a>.</p>
306 </div>
307 <p>As well as a decorator <cite>patch</cite> can be used as a context manager in a with
308 statement:</p>
309 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">object</span><span class="p">(</span><span class="n">ProductionClass</span><span class="p">,</span> <span class="s">&#39;method&#39;</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_method</span><span class="p">:</span>
310 <span class="gp">... </span> <span class="n">thing</span> <span class="o">=</span> <span class="n">ProductionClass</span><span class="p">()</span>
311 <span class="gp">... </span> <span class="n">thing</span><span class="o">.</span><span class="n">method</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
312 <span class="gp">...</span>
313 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_method</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
314 </pre></div>
315 </div>
316 <p>There is also <a class="reference internal" href="patch.html#mock.patch.dict" title="mock.patch.dict"><tt class="xref py py-func docutils literal"><span class="pre">patch.dict()</span></tt></a> for setting values in a dictionary just
317 during a scope and restoring the dictionary to its original state when the test
318 ends:</p>
319 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">foo</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;key&#39;</span><span class="p">:</span> <span class="s">&#39;value&#39;</span><span class="p">}</span>
320 <span class="gp">&gt;&gt;&gt; </span><span class="n">original</span> <span class="o">=</span> <span class="n">foo</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
321 <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="n">foo</span><span class="p">,</span> <span class="p">{</span><span class="s">&#39;newkey&#39;</span><span class="p">:</span> <span class="s">&#39;newvalue&#39;</span><span class="p">},</span> <span class="n">clear</span><span class="o">=</span><span class="bp">True</span><span class="p">):</span>
322 <span class="gp">... </span> <span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{</span><span class="s">&#39;newkey&#39;</span><span class="p">:</span> <span class="s">&#39;newvalue&#39;</span><span class="p">}</span>
323 <span class="gp">...</span>
324 <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="n">original</span>
325 </pre></div>
326 </div>
327 <p>Mock supports the mocking of Python <a class="reference internal" href="magicmock.html#magic-methods"><em>magic methods</em></a>. The
328 easiest way of using magic methods is with the <a class="reference internal" href="magicmock.html#mock.MagicMock" title="mock.MagicMock"><tt class="xref py py-class docutils literal"><span class="pre">MagicMock</span></tt></a> class. It
329 allows you to do things like:</p>
330 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
331 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">__str__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s">&#39;foobarbaz&#39;</span>
332 <span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>
333 <span class="go">&#39;foobarbaz&#39;</span>
334 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">__str__</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">()</span>
335 </pre></div>
336 </div>
337 <p>Mock allows you to assign functions (or other Mock instances) to magic methods
338 and they will be called appropriately. The <cite>MagicMock</cite> class is just a Mock
339 variant that has all of the magic methods pre-created for you (well, all the
340 useful ones anyway).</p>
341 <p>The following is an example of using magic methods with the ordinary Mock
342 class:</p>
343 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">()</span>
344 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">__str__</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="s">&#39;wheeeeee&#39;</span><span class="p">)</span>
345 <span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>
346 <span class="go">&#39;wheeeeee&#39;</span>
347 </pre></div>
348 </div>
349 <p>For ensuring that the mock objects in your tests have the same api as the
350 objects they are replacing, you can use <a class="reference internal" href="helpers.html#auto-speccing"><em>auto-speccing</em></a>.
351 Auto-speccing can be done through the <cite>autospec</cite> argument to patch, or the
352 <a class="reference internal" href="helpers.html#mock.create_autospec" title="mock.create_autospec"><tt class="xref py py-func docutils literal"><span class="pre">create_autospec()</span></tt></a> function. Auto-speccing creates mock objects that
353 have the same attributes and methods as the objects they are replacing, and
354 any functions and methods (including constructors) have the same call
355 signature as the real object.</p>
356 <p>This ensures that your mocks will fail in the same way as your production
357 code if they are used incorrectly:</p>
358 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">create_autospec</span>
359 <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">function</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">):</span>
360 <span class="gp">... </span> <span class="k">pass</span>
361 <span class="gp">...</span>
362 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_function</span> <span class="o">=</span> <span class="n">create_autospec</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="s">&#39;fishy&#39;</span><span class="p">)</span>
363 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_function</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
364 <span class="go">&#39;fishy&#39;</span>
365 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_function</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
366 <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_function</span><span class="p">(</span><span class="s">&#39;wrong arguments&#39;</span><span class="p">)</span>
367 <span class="gt">Traceback (most recent call last):</span>
368 <span class="c">...</span>
369 <span class="gr">TypeError</span>: <span class="n">&lt;lambda&gt;() takes exactly 3 arguments (1 given)</span>
370 </pre></div>
371 </div>
372 <p><cite>create_autospec</cite> can also be used on classes, where it copies the signature of
373 the <cite>__init__</cite> method, and on callable objects where it copies the signature of
374 the <cite>__call__</cite> method.</p>
375 <span class="target" id="index-7"></span></div>
376 <div class="section" id="references">
377 <span id="index-8"></span><h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
378 <p>Articles, blog entries and other stuff related to testing with Mock:</p>
379 <ul class="simple">
380 <li><a class="reference external" href="https://github.com/carljm/django-testing-slides/blob/master/models/30_no_database.md">Imposing a No DB Discipline on Django unit tests</a></li>
381 <li><a class="reference external" href="https://github.com/dcramer/mock-django">mock-django: tools for mocking the Django ORM and models</a></li>
382 <li><a class="reference external" href="https://blip.tv/file/4881513">PyCon 2011 Video: Testing with mock</a></li>
383 <li><a class="reference external" href="http://noopenblockers.com/2012/01/06/mock-objects-in-python/">Mock objects in Python</a></li>
384 <li><a class="reference external" href="http://blueprintforge.com/blog/2012/01/08/python-injecting-mock-objects-for-powerful-testing/">Python: Injecting Mock Objects for Powerful Testing</a></li>
385 <li><a class="reference external" href="http://www.michaelpollmeier.com/python-mock-how-to-assert-a-substring-of-logger-output/">Python Mock: How to assert a substring of logger output</a></li>
386 <li><a class="reference external" href="http://www.mattjmorrison.com/2011/09/mocking-django.html">Mocking Django</a></li>
387 <li><a class="reference external" href="http://williamjohnbert.com/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/">Mocking dates and other classes that can&#8217;t be modified</a></li>
388 <li><a class="reference external" href="http://konryd.blogspot.com/2010/06/mock-recipies.html">Mock recipes</a></li>
389 <li><a class="reference external" href="http://konryd.blogspot.com/2010/05/mockity-mock-mock-some-love-for-mock.html">Mockity mock mock - some love for the mock module</a></li>
390 <li><a class="reference external" href="http://mattsnider.com/python/mock-and-coverage/">Coverage and Mock (with django)</a></li>
391 <li><a class="reference external" href="http://www.insomnihack.com/?p=194">Python Unit Testing with Mock</a></li>
392 <li><a class="reference external" href="http://myadventuresincoding.wordpress.com/2011/02/26/python-python-mock-cheat-sheet/">Getting started with Python Mock</a></li>
393 <li><a class="reference external" href="http://tobyho.com/2011/03/24/smart-parameter-checks-in/">Smart Parameter Checks with mock</a></li>
394 <li><a class="reference external" href="http://agiletesting.blogspot.com/2009/07/python-mock-testing-techniques-and.html">Python mock testing techniques and tools</a></li>
395 <li><a class="reference external" href="http://techblog.ironfroggy.com/2008/10/how-to-test.html">How To Test Django Template Tags</a></li>
396 <li><a class="reference external" href="http://pypap.blogspot.com/2008/10/newbie-nugget-unit-testing-with-mock.html">A presentation on Unit Testing with Mock</a></li>
397 <li><a class="reference external" href="http://michael-a-nelson.blogspot.com/2008/09/mocking-with-django-and-google-app.html">Mocking with Django and Google AppEngine</a></li>
398 </ul>
399 <span class="target" id="index-9"></span></div>
400 <div class="section" id="tests">
401 <span id="index-10"></span><h2>Tests<a class="headerlink" href="#tests" title="Permalink to this headline">¶</a></h2>
402 <p>Mock uses <a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest2</a> for its own
403 test suite. In order to run it, use the <cite>unit2</cite> script that comes with
404 <cite>unittest2</cite> module on a checkout of the source repository:</p>
405 <blockquote>
406 <div><cite>unit2 discover</cite></div></blockquote>
407 <p>If you have <a class="reference external" href="http://pypi.python.org/pypi/distribute">setuptools</a> as well as
408 unittest2 you can run:</p>
409 <blockquote>
410 <div><tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">test</span></tt></div></blockquote>
411 <p>On Python 3.2 you can use <tt class="docutils literal"><span class="pre">unittest</span></tt> module from the standard library.</p>
412 <blockquote>
413 <div><tt class="docutils literal"><span class="pre">python3.2</span> <span class="pre">-m</span> <span class="pre">unittest</span> <span class="pre">discover</span></tt></div></blockquote>
414 <p id="index-11">On Python 3 the tests for unicode are skipped as they are not relevant. On
415 Python 2.4 tests that use the with statements are skipped as the with statement
416 is invalid syntax on Python 2.4.</p>
417 </div>
418 <div class="section" id="older-versions">
419 <span id="index-12"></span><h2>Older Versions<a class="headerlink" href="#older-versions" title="Permalink to this headline">¶</a></h2>
420 <p>Documentation for older versions of mock:</p>
421 <ul class="simple">
422 <li><a class="reference external" href="http://www.voidspace.org.uk/python/mock/0.8/">mock 0.8</a></li>
423 <li><a class="reference external" href="http://www.voidspace.org.uk/python/mock/0.7/">mock 0.7</a></li>
424 <li><a class="reference external" href="http://www.voidspace.org.uk/python/mock/0.6.0/">mock 0.6</a></li>
425 </ul>
426 <p>Docs from the in-development version of <cite>mock</cite> can be found at
427 <a class="reference external" href="http://mock.readthedocs.org">mock.readthedocs.org</a>.</p>
428 </div>
429 <div class="section" id="terminology">
430 <h2>Terminology<a class="headerlink" href="#terminology" title="Permalink to this headline">¶</a></h2>
431 <p>Terminology for objects used to replace other ones can be confusing. Terms
432 like double, fake, mock, stub, and spy are all used with varying meanings.</p>
433 <p>In <a class="reference external" href="http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html">classic mock terminology</a>
434 <a class="reference internal" href="mock.html#mock.Mock" title="mock.Mock"><tt class="xref py py-class docutils literal"><span class="pre">mock.Mock</span></tt></a> is a <a class="reference external" href="http://xunitpatterns.com/Test%20Spy.html">spy</a> that
435 allows for <em>post-mortem</em> examination. This is what I call the &#8220;action -&gt;
436 assertion&#8221; <a class="footnote-reference" href="#id2" id="id1">[1]</a> pattern of testing.</p>
437 <p>I&#8217;m not however a fan of this &#8220;statically typed mocking terminology&#8221;
438 promulgated by <a class="reference external" href="http://martinfowler.com/articles/mocksArentStubs.html">Martin Fowler</a>. It confuses usage
439 patterns with implementation and prevents you from using natural terminology
440 when discussing mocking.</p>
441 <p>I much prefer duck typing, if an object used in your test suite looks like a
442 mock object and quacks like a mock object then it&#8217;s fine to call it a mock, no
443 matter what the implementation looks like.</p>
444 <p>This terminology is perhaps more useful in less capable languages where
445 different usage patterns will <em>require</em> different implementations.
446 <cite>mock.Mock()</cite> is capable of being used in most of the different roles
447 described by Fowler, except (annoyingly / frustratingly / ironically) a Mock
448 itself!</p>
449 <p>How about a simpler definition: a &#8220;mock object&#8221; is an object used to replace a
450 real one in a system under test.</p>
451 <table class="docutils footnote" frame="void" id="id2" rules="none">
452 <colgroup><col class="label" /><col /></colgroup>
453 <tbody valign="top">
454 <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>This pattern is called &#8220;AAA&#8221; by some members of the testing community;
455 &#8220;Arrange - Act - Assert&#8221;.</td></tr>
456 </tbody>
457 </table>
458 </div>
459 </div>
460
461
462 </div>
463 </div>
464 </div>
465 <div class="sphinxsidebar">
466 <div class="sphinxsidebarwrapper">
467 <h3><a href="#">Table Of Contents</a></h3>
468 <ul>
469 <li><a class="reference internal" href="#">Mock - Mocking and Testing Library</a><ul>
470 <li><a class="reference internal" href="#api-documentation">API Documentation</a><ul>
471 </ul>
472 </li>
473 <li><a class="reference internal" href="#user-guide">User Guide</a><ul>
474 </ul>
475 </li>
476 <li><a class="reference internal" href="#installing">Installing</a></li>
477 <li><a class="reference internal" href="#quick-guide">Quick Guide</a></li>
478 <li><a class="reference internal" href="#references">References</a></li>
479 <li><a class="reference internal" href="#tests">Tests</a></li>
480 <li><a class="reference internal" href="#older-versions">Older Versions</a></li>
481 <li><a class="reference internal" href="#terminology">Terminology</a></li>
482 </ul>
483 </li>
484 </ul>
485
486 <h4>Next topic</h4>
487 <p class="topless"><a href="mock.html"
488 title="next chapter">The Mock Class</a></p>
489 <h3>This Page</h3>
490 <ul class="this-page-menu">
491 <li><a href="_sources/index.txt"
492 rel="nofollow">Show Source</a></li>
493 </ul>
494 <div id="searchbox" style="display: none">
495 <h3>Quick search</h3>
496 <form class="search" action="search.html" method="get">
497 <input type="text" name="q" />
498 <input type="submit" value="Go" />
499 <input type="hidden" name="check_keywords" value="yes" />
500 <input type="hidden" name="area" value="default" />
501 </form>
502 <p class="searchtip" style="font-size: 90%">
503 Enter search terms or a module, class or function name.
504 </p>
505 </div>
506 <script type="text/javascript">$('#searchbox').show(0);</script>
507 </div>
508 </div>
509 <div class="clearer"></div>
510 </div>
511 <div class="related">
512 <h3>Navigation</h3>
513 <ul>
514 <li class="right" style="margin-right: 10px">
515 <a href="genindex.html" title="General Index"
516 >index</a></li>
517 <li class="right" >
518 <a href="mock.html" title="The Mock Class"
519 >next</a> |</li>
520 <li><a href="#">Mock 1.0.0 documentation</a> &raquo;</li>
521 </ul>
522 </div>
523 <div class="footer">
524 &copy; Copyright 2007-2012, Michael Foord &amp; the mock team.
525 Last updated on Oct 07, 2012.
526 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
527 </div>
528 </body>
529 </html>

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial