The Tor Browser / file comparison
comparison: python/mock-1.0.0/html/patch.html
python/mock-1.0.0/html/patch.html
- branch
- TOR_BUG_3246
- changeset 4
- fc2d59ddac77
equal
deleted
inserted
replaced
| -1:000000000000 | 0:b81fc7f5327c |
|---|---|
| 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>Patch Decorators — 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="index.html" /> | |
| 28 <link rel="next" title="Helpers" href="helpers.html" /> | |
| 29 <link rel="prev" title="The Mock Class" href="mock.html" /> | |
| 30 </head> | |
| 31 <body> | |
| 32 <div class="related"> | |
| 33 <h3>Navigation</h3> | |
| 34 <ul> | |
| 35 <li class="right" style="margin-right: 10px"> | |
| 36 <a href="genindex.html" title="General Index" | |
| 37 accesskey="I">index</a></li> | |
| 38 <li class="right" > | |
| 39 <a href="helpers.html" title="Helpers" | |
| 40 accesskey="N">next</a> |</li> | |
| 41 <li class="right" > | |
| 42 <a href="mock.html" title="The Mock Class" | |
| 43 accesskey="P">previous</a> |</li> | |
| 44 <li><a href="index.html">Mock 1.0.0 documentation</a> »</li> | |
| 45 </ul> | |
| 46 </div> | |
| 47 | |
| 48 <div class="document"> | |
| 49 <div class="documentwrapper"> | |
| 50 <div class="bodywrapper"> | |
| 51 <div class="body"> | |
| 52 | |
| 53 <div class="section" id="patch-decorators"> | |
| 54 <h1>Patch Decorators<a class="headerlink" href="#patch-decorators" title="Permalink to this headline">¶</a></h1> | |
| 55 <p>The patch decorators are used for patching objects only within the scope of | |
| 56 the function they decorate. They automatically handle the unpatching for you, | |
| 57 even if exceptions are raised. All of these functions can also be used in with | |
| 58 statements or as class decorators.</p> | |
| 59 <div class="section" id="patch"> | |
| 60 <h2>patch<a class="headerlink" href="#patch" title="Permalink to this headline">¶</a></h2> | |
| 61 <div class="admonition note"> | |
| 62 <p class="first admonition-title">Note</p> | |
| 63 <p class="last"><cite>patch</cite> is straightforward to use. The key is to do the patching in the | |
| 64 right namespace. See the section <a class="reference internal" href="#id1">where to patch</a>.</p> | |
| 65 </div> | |
| 66 <dl class="function"> | |
| 67 <dt id="mock.patch"> | |
| 68 <tt class="descname">patch</tt><big>(</big><em>target</em>, <em>new=DEFAULT</em>, <em>spec=None</em>, <em>create=False</em>, <em>spec_set=None</em>, <em>autospec=None</em>, <em>new_callable=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.patch" title="Permalink to this definition">¶</a></dt> | |
| 69 <dd><p><cite>patch</cite> acts as a function decorator, class decorator or a context | |
| 70 manager. Inside the body of the function or with statement, the <cite>target</cite> | |
| 71 is patched with a <cite>new</cite> object. When the function/with statement exits | |
| 72 the patch is undone.</p> | |
| 73 <p>If <cite>new</cite> is omitted, then the target is replaced with a | |
| 74 <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>. If <cite>patch</cite> is used as a decorator and <cite>new</cite> is | |
| 75 omitted, the created mock is passed in as an extra argument to the | |
| 76 decorated function. If <cite>patch</cite> is used as a context manager the created | |
| 77 mock is returned by the context manager.</p> | |
| 78 <p><cite>target</cite> should be a string in the form <cite>‘package.module.ClassName’</cite>. The | |
| 79 <cite>target</cite> is imported and the specified object replaced with the <cite>new</cite> | |
| 80 object, so the <cite>target</cite> must be importable from the environment you are | |
| 81 calling <cite>patch</cite> from. The target is imported when the decorated function | |
| 82 is executed, not at decoration time.</p> | |
| 83 <p>The <cite>spec</cite> and <cite>spec_set</cite> keyword arguments are passed to the <cite>MagicMock</cite> | |
| 84 if patch is creating one for you.</p> | |
| 85 <p>In addition you can pass <cite>spec=True</cite> or <cite>spec_set=True</cite>, which causes | |
| 86 patch to pass in the object being mocked as the spec/spec_set object.</p> | |
| 87 <p><cite>new_callable</cite> allows you to specify a different class, or callable object, | |
| 88 that will be called to create the <cite>new</cite> object. By default <cite>MagicMock</cite> is | |
| 89 used.</p> | |
| 90 <p>A more powerful form of <cite>spec</cite> is <cite>autospec</cite>. If you set <cite>autospec=True</cite> | |
| 91 then the mock with be created with a spec from the object being replaced. | |
| 92 All attributes of the mock will also have the spec of the corresponding | |
| 93 attribute of the object being replaced. Methods and functions being mocked | |
| 94 will have their arguments checked and will raise a <cite>TypeError</cite> if they are | |
| 95 called with the wrong signature. For mocks | |
| 96 replacing a class, their return value (the ‘instance’) will have the same | |
| 97 spec as the class. See the <a class="reference internal" href="helpers.html#mock.create_autospec" title="mock.create_autospec"><tt class="xref py py-func docutils literal"><span class="pre">create_autospec()</span></tt></a> function and | |
| 98 <a class="reference internal" href="helpers.html#auto-speccing"><em>Autospeccing</em></a>.</p> | |
| 99 <p>Instead of <cite>autospec=True</cite> you can pass <cite>autospec=some_object</cite> to use an | |
| 100 arbitrary object as the spec instead of the one being replaced.</p> | |
| 101 <p>By default <cite>patch</cite> will fail to replace attributes that don’t exist. If | |
| 102 you pass in <cite>create=True</cite>, and the attribute doesn’t exist, patch will | |
| 103 create the attribute for you when the patched function is called, and | |
| 104 delete it again afterwards. This is useful for writing tests against | |
| 105 attributes that your production code creates at runtime. It is off by by | |
| 106 default because it can be dangerous. With it switched on you can write | |
| 107 passing tests against APIs that don’t actually exist!</p> | |
| 108 <p>Patch can be used as a <cite>TestCase</cite> class decorator. It works by | |
| 109 decorating each test method in the class. This reduces the boilerplate | |
| 110 code when your test methods share a common patchings set. <cite>patch</cite> finds | |
| 111 tests by looking for method names that start with <cite>patch.TEST_PREFIX</cite>. | |
| 112 By default this is <cite>test</cite>, which matches the way <cite>unittest</cite> finds tests. | |
| 113 You can specify an alternative prefix by setting <cite>patch.TEST_PREFIX</cite>.</p> | |
| 114 <p>Patch can be used as a context manager, with the with statement. Here the | |
| 115 patching applies to the indented block after the with statement. If you | |
| 116 use “as” then the patched object will be bound to the name after the | |
| 117 “as”; very useful if <cite>patch</cite> is creating a mock object for you.</p> | |
| 118 <p><cite>patch</cite> takes arbitrary keyword arguments. These will be passed to | |
| 119 the <cite>Mock</cite> (or <cite>new_callable</cite>) on construction.</p> | |
| 120 <p><cite>patch.dict(...)</cite>, <cite>patch.multiple(...)</cite> and <cite>patch.object(...)</cite> are | |
| 121 available for alternate use-cases.</p> | |
| 122 </dd></dl> | |
| 123 | |
| 124 <p><cite>patch</cite> as function decorator, creating the mock for you and passing it into | |
| 125 the decorated function:</p> | |
| 126 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'__main__.SomeClass'</span><span class="p">)</span> | |
| 127 <span class="gp">... </span><span class="k">def</span> <span class="nf">function</span><span class="p">(</span><span class="n">normal_argument</span><span class="p">,</span> <span class="n">mock_class</span><span class="p">):</span> | |
| 128 <span class="gp">... </span> <span class="k">print</span> <span class="n">mock_class</span> <span class="ow">is</span> <span class="n">SomeClass</span> | |
| 129 <span class="gp">...</span> | |
| 130 <span class="gp">>>> </span><span class="n">function</span><span class="p">(</span><span class="bp">None</span><span class="p">)</span> | |
| 131 <span class="go">True</span> | |
| 132 </pre></div> | |
| 133 </div> | |
| 134 <p>Patching a class replaces the class with a <cite>MagicMock</cite> <em>instance</em>. If the | |
| 135 class is instantiated in the code under test then it will be the | |
| 136 <a class="reference internal" href="mock.html#mock.Mock.return_value" title="mock.Mock.return_value"><tt class="xref py py-attr docutils literal"><span class="pre">return_value</span></tt></a> of the mock that will be used.</p> | |
| 137 <p>If the class is instantiated multiple times you could use | |
| 138 <a class="reference internal" href="mock.html#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> to return a new mock each time. Alternatively you | |
| 139 can set the <cite>return_value</cite> to be anything you want.</p> | |
| 140 <p>To configure return values on methods of <em>instances</em> on the patched class | |
| 141 you must do this on the <cite>return_value</cite>. For example:</p> | |
| 142 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Class</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> | |
| 143 <span class="gp">... </span> <span class="k">def</span> <span class="nf">method</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 144 <span class="gp">... </span> <span class="k">pass</span> | |
| 145 <span class="gp">...</span> | |
| 146 <span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.Class'</span><span class="p">)</span> <span class="k">as</span> <span class="n">MockClass</span><span class="p">:</span> | |
| 147 <span class="gp">... </span> <span class="n">instance</span> <span class="o">=</span> <span class="n">MockClass</span><span class="o">.</span><span class="n">return_value</span> | |
| 148 <span class="gp">... </span> <span class="n">instance</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s">'foo'</span> | |
| 149 <span class="gp">... </span> <span class="k">assert</span> <span class="n">Class</span><span class="p">()</span> <span class="ow">is</span> <span class="n">instance</span> | |
| 150 <span class="gp">... </span> <span class="k">assert</span> <span class="n">Class</span><span class="p">()</span><span class="o">.</span><span class="n">method</span><span class="p">()</span> <span class="o">==</span> <span class="s">'foo'</span> | |
| 151 <span class="gp">...</span> | |
| 152 </pre></div> | |
| 153 </div> | |
| 154 <p>If you use <cite>spec</cite> or <cite>spec_set</cite> and <cite>patch</cite> is replacing a <em>class</em>, then the | |
| 155 return value of the created mock will have the same spec.</p> | |
| 156 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Original</span> <span class="o">=</span> <span class="n">Class</span> | |
| 157 <span class="gp">>>> </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.Class'</span><span class="p">,</span> <span class="n">spec</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> | |
| 158 <span class="gp">>>> </span><span class="n">MockClass</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> | |
| 159 <span class="gp">>>> </span><span class="n">instance</span> <span class="o">=</span> <span class="n">MockClass</span><span class="p">()</span> | |
| 160 <span class="gp">>>> </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">instance</span><span class="p">,</span> <span class="n">Original</span><span class="p">)</span> | |
| 161 <span class="gp">>>> </span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> | |
| 162 </pre></div> | |
| 163 </div> | |
| 164 <p>The <cite>new_callable</cite> argument is useful where you want to use an alternative | |
| 165 class to the default <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> for the created mock. For example, if | |
| 166 you wanted a <a class="reference internal" href="mock.html#mock.NonCallableMock" title="mock.NonCallableMock"><tt class="xref py py-class docutils literal"><span class="pre">NonCallableMock</span></tt></a> to be used:</p> | |
| 167 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">thing</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span> | |
| 168 <span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.thing'</span><span class="p">,</span> <span class="n">new_callable</span><span class="o">=</span><span class="n">NonCallableMock</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_thing</span><span class="p">:</span> | |
| 169 <span class="gp">... </span> <span class="k">assert</span> <span class="n">thing</span> <span class="ow">is</span> <span class="n">mock_thing</span> | |
| 170 <span class="gp">... </span> <span class="n">thing</span><span class="p">()</span> | |
| 171 <span class="gp">...</span> | |
| 172 <span class="gt">Traceback (most recent call last):</span> | |
| 173 <span class="c">...</span> | |
| 174 <span class="gr">TypeError</span>: <span class="n">'NonCallableMock' object is not callable</span> | |
| 175 </pre></div> | |
| 176 </div> | |
| 177 <p>Another use case might be to replace an object with a <cite>StringIO</cite> instance:</p> | |
| 178 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">StringIO</span> <span class="kn">import</span> <span class="n">StringIO</span> | |
| 179 <span class="gp">>>> </span><span class="k">def</span> <span class="nf">foo</span><span class="p">():</span> | |
| 180 <span class="gp">... </span> <span class="k">print</span> <span class="s">'Something'</span> | |
| 181 <span class="gp">...</span> | |
| 182 <span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'sys.stdout'</span><span class="p">,</span> <span class="n">new_callable</span><span class="o">=</span><span class="n">StringIO</span><span class="p">)</span> | |
| 183 <span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">mock_stdout</span><span class="p">):</span> | |
| 184 <span class="gp">... </span> <span class="n">foo</span><span class="p">()</span> | |
| 185 <span class="gp">... </span> <span class="k">assert</span> <span class="n">mock_stdout</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span> <span class="o">==</span> <span class="s">'Something</span><span class="se">\n</span><span class="s">'</span> | |
| 186 <span class="gp">...</span> | |
| 187 <span class="gp">>>> </span><span class="n">test</span><span class="p">()</span> | |
| 188 </pre></div> | |
| 189 </div> | |
| 190 <p>When <cite>patch</cite> is creating a mock for you, it is common that the first thing | |
| 191 you need to do is to configure the mock. Some of that configuration can be done | |
| 192 in the call to patch. Any arbitrary keywords you pass into the call will be | |
| 193 used to set attributes on the created mock:</p> | |
| 194 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.thing'</span><span class="p">,</span> <span class="n">first</span><span class="o">=</span><span class="s">'one'</span><span class="p">,</span> <span class="n">second</span><span class="o">=</span><span class="s">'two'</span><span class="p">)</span> | |
| 195 <span class="gp">>>> </span><span class="n">mock_thing</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> | |
| 196 <span class="gp">>>> </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">first</span> | |
| 197 <span class="go">'one'</span> | |
| 198 <span class="gp">>>> </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">second</span> | |
| 199 <span class="go">'two'</span> | |
| 200 </pre></div> | |
| 201 </div> | |
| 202 <p>As well as attributes on the created mock attributes, like the | |
| 203 <a class="reference internal" href="mock.html#mock.Mock.return_value" title="mock.Mock.return_value"><tt class="xref py py-attr docutils literal"><span class="pre">return_value</span></tt></a> and <a class="reference internal" href="mock.html#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>, of child mocks can | |
| 204 also be configured. These aren’t syntactically valid to pass in directly as | |
| 205 keyword arguments, but a dictionary with these as keys can still be expanded | |
| 206 into a <cite>patch</cite> call using <cite>**</cite>:</p> | |
| 207 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">config</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> | |
| 208 <span class="gp">>>> </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.thing'</span><span class="p">,</span> <span class="o">**</span><span class="n">config</span><span class="p">)</span> | |
| 209 <span class="gp">>>> </span><span class="n">mock_thing</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> | |
| 210 <span class="gp">>>> </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">method</span><span class="p">()</span> | |
| 211 <span class="go">3</span> | |
| 212 <span class="gp">>>> </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">other</span><span class="p">()</span> | |
| 213 <span class="gt">Traceback (most recent call last):</span> | |
| 214 <span class="c">...</span> | |
| 215 <span class="gr">KeyError</span> | |
| 216 </pre></div> | |
| 217 </div> | |
| 218 </div> | |
| 219 <div class="section" id="patch-object"> | |
| 220 <h2>patch.object<a class="headerlink" href="#patch-object" title="Permalink to this headline">¶</a></h2> | |
| 221 <dl class="function"> | |
| 222 <dt id="mock.patch.object"> | |
| 223 <tt class="descclassname">patch.</tt><tt class="descname">object</tt><big>(</big><em>target</em>, <em>attribute</em>, <em>new=DEFAULT</em>, <em>spec=None</em>, <em>create=False</em>, <em>spec_set=None</em>, <em>autospec=None</em>, <em>new_callable=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.patch.object" title="Permalink to this definition">¶</a></dt> | |
| 224 <dd><p>patch the named member (<cite>attribute</cite>) on an object (<cite>target</cite>) with a mock | |
| 225 object.</p> | |
| 226 <p><cite>patch.object</cite> can be used as a decorator, class decorator or a context | |
| 227 manager. Arguments <cite>new</cite>, <cite>spec</cite>, <cite>create</cite>, <cite>spec_set</cite>, <cite>autospec</cite> and | |
| 228 <cite>new_callable</cite> have the same meaning as for <cite>patch</cite>. Like <cite>patch</cite>, | |
| 229 <cite>patch.object</cite> takes arbitrary keyword arguments for configuring the mock | |
| 230 object it creates.</p> | |
| 231 <p>When used as a class decorator <cite>patch.object</cite> honours <cite>patch.TEST_PREFIX</cite> | |
| 232 for choosing which methods to wrap.</p> | |
| 233 </dd></dl> | |
| 234 | |
| 235 <p>You can either call <cite>patch.object</cite> with three arguments or two arguments. The | |
| 236 three argument form takes the object to be patched, the attribute name and the | |
| 237 object to replace the attribute with.</p> | |
| 238 <p>When calling with the two argument form you omit the replacement object, and a | |
| 239 mock is created for you and passed in as an extra argument to the decorated | |
| 240 function:</p> | |
| 241 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch.object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s">'class_method'</span><span class="p">)</span> | |
| 242 <span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">mock_method</span><span class="p">):</span> | |
| 243 <span class="gp">... </span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">class_method</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> | |
| 244 <span class="gp">... </span> <span class="n">mock_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> | |
| 245 <span class="gp">...</span> | |
| 246 <span class="gp">>>> </span><span class="n">test</span><span class="p">()</span> | |
| 247 </pre></div> | |
| 248 </div> | |
| 249 <p><cite>spec</cite>, <cite>create</cite> and the other arguments to <cite>patch.object</cite> have the same | |
| 250 meaning as they do for <cite>patch</cite>.</p> | |
| 251 </div> | |
| 252 <div class="section" id="patch-dict"> | |
| 253 <h2>patch.dict<a class="headerlink" href="#patch-dict" title="Permalink to this headline">¶</a></h2> | |
| 254 <dl class="function"> | |
| 255 <dt id="mock.patch.dict"> | |
| 256 <tt class="descclassname">patch.</tt><tt class="descname">dict</tt><big>(</big><em>in_dict</em>, <em>values=()</em>, <em>clear=False</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.patch.dict" title="Permalink to this definition">¶</a></dt> | |
| 257 <dd><p>Patch a dictionary, or dictionary like object, and restore the dictionary | |
| 258 to its original state after the test.</p> | |
| 259 <p><cite>in_dict</cite> can be a dictionary or a mapping like container. If it is a | |
| 260 mapping then it must at least support getting, setting and deleting items | |
| 261 plus iterating over keys.</p> | |
| 262 <p><cite>in_dict</cite> can also be a string specifying the name of the dictionary, which | |
| 263 will then be fetched by importing it.</p> | |
| 264 <p><cite>values</cite> can be a dictionary of values to set in the dictionary. <cite>values</cite> | |
| 265 can also be an iterable of <cite>(key, value)</cite> pairs.</p> | |
| 266 <p>If <cite>clear</cite> is True then the dictionary will be cleared before the new | |
| 267 values are set.</p> | |
| 268 <p><cite>patch.dict</cite> can also be called with arbitrary keyword arguments to set | |
| 269 values in the dictionary.</p> | |
| 270 <p><cite>patch.dict</cite> can be used as a context manager, decorator or class | |
| 271 decorator. When used as a class decorator <cite>patch.dict</cite> honours | |
| 272 <cite>patch.TEST_PREFIX</cite> for choosing which methods to wrap.</p> | |
| 273 </dd></dl> | |
| 274 | |
| 275 <p><cite>patch.dict</cite> can be used to add members to a dictionary, or simply let a test | |
| 276 change a dictionary, and ensure the dictionary is restored when the test | |
| 277 ends.</p> | |
| 278 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">patch</span> | |
| 279 <span class="gp">>>> </span><span class="n">foo</span> <span class="o">=</span> <span class="p">{}</span> | |
| 280 <span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="n">foo</span><span class="p">,</span> <span class="p">{</span><span class="s">'newkey'</span><span class="p">:</span> <span class="s">'newvalue'</span><span class="p">}):</span> | |
| 281 <span class="gp">... </span> <span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{</span><span class="s">'newkey'</span><span class="p">:</span> <span class="s">'newvalue'</span><span class="p">}</span> | |
| 282 <span class="gp">...</span> | |
| 283 <span class="gp">>>> </span><span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{}</span> | |
| 284 | |
| 285 <span class="gp">>>> </span><span class="kn">import</span> <span class="nn">os</span> | |
| 286 <span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="s">'os.environ'</span><span class="p">,</span> <span class="p">{</span><span class="s">'newkey'</span><span class="p">:</span> <span class="s">'newvalue'</span><span class="p">}):</span> | |
| 287 <span class="gp">... </span> <span class="k">print</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s">'newkey'</span><span class="p">]</span> | |
| 288 <span class="gp">...</span> | |
| 289 <span class="go">newvalue</span> | |
| 290 <span class="gp">>>> </span><span class="k">assert</span> <span class="s">'newkey'</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span> | |
| 291 </pre></div> | |
| 292 </div> | |
| 293 <p>Keywords can be used in the <cite>patch.dict</cite> call to set values in the dictionary:</p> | |
| 294 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mymodule</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span> | |
| 295 <span class="gp">>>> </span><span class="n">mymodule</span><span class="o">.</span><span class="n">function</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s">'fish'</span> | |
| 296 <span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="s">'sys.modules'</span><span class="p">,</span> <span class="n">mymodule</span><span class="o">=</span><span class="n">mymodule</span><span class="p">):</span> | |
| 297 <span class="gp">... </span> <span class="kn">import</span> <span class="nn">mymodule</span> | |
| 298 <span class="gp">... </span> <span class="n">mymodule</span><span class="o">.</span><span class="n">function</span><span class="p">(</span><span class="s">'some'</span><span class="p">,</span> <span class="s">'args'</span><span class="p">)</span> | |
| 299 <span class="gp">...</span> | |
| 300 <span class="go">'fish'</span> | |
| 301 </pre></div> | |
| 302 </div> | |
| 303 <p><cite>patch.dict</cite> can be used with dictionary like objects that aren’t actually | |
| 304 dictionaries. At the very minimum they must support item getting, setting, | |
| 305 deleting and either iteration or membership test. This corresponds to the | |
| 306 magic methods <cite>__getitem__</cite>, <cite>__setitem__</cite>, <cite>__delitem__</cite> and either | |
| 307 <cite>__iter__</cite> or <cite>__contains__</cite>.</p> | |
| 308 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Container</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> | |
| 309 <span class="gp">... </span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 310 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">values</span> <span class="o">=</span> <span class="p">{}</span> | |
| 311 <span class="gp">... </span> <span class="k">def</span> <span class="nf">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> | |
| 312 <span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">values</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> | |
| 313 <span class="gp">... </span> <span class="k">def</span> <span class="nf">__setitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span> | |
| 314 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">values</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span> | |
| 315 <span class="gp">... </span> <span class="k">def</span> <span class="nf">__delitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> | |
| 316 <span class="gp">... </span> <span class="k">del</span> <span class="bp">self</span><span class="o">.</span><span class="n">values</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> | |
| 317 <span class="gp">... </span> <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 318 <span class="gp">... </span> <span class="k">return</span> <span class="nb">iter</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">values</span><span class="p">)</span> | |
| 319 <span class="gp">...</span> | |
| 320 <span class="gp">>>> </span><span class="n">thing</span> <span class="o">=</span> <span class="n">Container</span><span class="p">()</span> | |
| 321 <span class="gp">>>> </span><span class="n">thing</span><span class="p">[</span><span class="s">'one'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span> | |
| 322 <span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="n">thing</span><span class="p">,</span> <span class="n">one</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">two</span><span class="o">=</span><span class="mi">3</span><span class="p">):</span> | |
| 323 <span class="gp">... </span> <span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s">'one'</span><span class="p">]</span> <span class="o">==</span> <span class="mi">2</span> | |
| 324 <span class="gp">... </span> <span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s">'two'</span><span class="p">]</span> <span class="o">==</span> <span class="mi">3</span> | |
| 325 <span class="gp">...</span> | |
| 326 <span class="gp">>>> </span><span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s">'one'</span><span class="p">]</span> <span class="o">==</span> <span class="mi">1</span> | |
| 327 <span class="gp">>>> </span><span class="k">assert</span> <span class="nb">list</span><span class="p">(</span><span class="n">thing</span><span class="p">)</span> <span class="o">==</span> <span class="p">[</span><span class="s">'one'</span><span class="p">]</span> | |
| 328 </pre></div> | |
| 329 </div> | |
| 330 </div> | |
| 331 <div class="section" id="patch-multiple"> | |
| 332 <h2>patch.multiple<a class="headerlink" href="#patch-multiple" title="Permalink to this headline">¶</a></h2> | |
| 333 <dl class="function"> | |
| 334 <dt id="mock.patch.multiple"> | |
| 335 <tt class="descclassname">patch.</tt><tt class="descname">multiple</tt><big>(</big><em>target</em>, <em>spec=None</em>, <em>create=False</em>, <em>spec_set=None</em>, <em>autospec=None</em>, <em>new_callable=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.patch.multiple" title="Permalink to this definition">¶</a></dt> | |
| 336 <dd><p>Perform multiple patches in a single call. It takes the object to be | |
| 337 patched (either as an object or a string to fetch the object by importing) | |
| 338 and keyword arguments for the patches:</p> | |
| 339 <div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">multiple</span><span class="p">(</span><span class="n">settings</span><span class="p">,</span> <span class="n">FIRST_PATCH</span><span class="o">=</span><span class="s">'one'</span><span class="p">,</span> <span class="n">SECOND_PATCH</span><span class="o">=</span><span class="s">'two'</span><span class="p">):</span> | |
| 340 <span class="o">...</span> | |
| 341 </pre></div> | |
| 342 </div> | |
| 343 <p>Use <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> as the value if you want <cite>patch.multiple</cite> to create | |
| 344 mocks for you. In this case the created mocks are passed into a decorated | |
| 345 function by keyword, and a dictionary is returned when <cite>patch.multiple</cite> is | |
| 346 used as a context manager.</p> | |
| 347 <p><cite>patch.multiple</cite> can be used as a decorator, class decorator or a context | |
| 348 manager. The arguments <cite>spec</cite>, <cite>spec_set</cite>, <cite>create</cite>, <cite>autospec</cite> and | |
| 349 <cite>new_callable</cite> have the same meaning as for <cite>patch</cite>. These arguments will | |
| 350 be applied to <em>all</em> patches done by <cite>patch.multiple</cite>.</p> | |
| 351 <p>When used as a class decorator <cite>patch.multiple</cite> honours <cite>patch.TEST_PREFIX</cite> | |
| 352 for choosing which methods to wrap.</p> | |
| 353 </dd></dl> | |
| 354 | |
| 355 <p>If you want <cite>patch.multiple</cite> to create mocks for you, then you can use | |
| 356 <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> as the value. If you use <cite>patch.multiple</cite> as a decorator | |
| 357 then the created mocks are passed into the decorated function by keyword.</p> | |
| 358 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">thing</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span> | |
| 359 <span class="gp">>>> </span><span class="n">other</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span> | |
| 360 | |
| 361 <span class="gp">>>> </span><span class="nd">@patch.multiple</span><span class="p">(</span><span class="s">'__main__'</span><span class="p">,</span> <span class="n">thing</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">)</span> | |
| 362 <span class="gp">... </span><span class="k">def</span> <span class="nf">test_function</span><span class="p">(</span><span class="n">thing</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> | |
| 363 <span class="gp">... </span> <span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">thing</span><span class="p">,</span> <span class="n">MagicMock</span><span class="p">)</span> | |
| 364 <span class="gp">... </span> <span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">MagicMock</span><span class="p">)</span> | |
| 365 <span class="gp">...</span> | |
| 366 <span class="gp">>>> </span><span class="n">test_function</span><span class="p">()</span> | |
| 367 </pre></div> | |
| 368 </div> | |
| 369 <p><cite>patch.multiple</cite> can be nested with other <cite>patch</cite> decorators, but put arguments | |
| 370 passed by keyword <em>after</em> any of the standard arguments created by <cite>patch</cite>:</p> | |
| 371 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'sys.exit'</span><span class="p">)</span> | |
| 372 <span class="gp">... </span><span class="nd">@patch.multiple</span><span class="p">(</span><span class="s">'__main__'</span><span class="p">,</span> <span class="n">thing</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">)</span> | |
| 373 <span class="gp">... </span><span class="k">def</span> <span class="nf">test_function</span><span class="p">(</span><span class="n">mock_exit</span><span class="p">,</span> <span class="n">other</span><span class="p">,</span> <span class="n">thing</span><span class="p">):</span> | |
| 374 <span class="gp">... </span> <span class="k">assert</span> <span class="s">'other'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> | |
| 375 <span class="gp">... </span> <span class="k">assert</span> <span class="s">'thing'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">thing</span><span class="p">)</span> | |
| 376 <span class="gp">... </span> <span class="k">assert</span> <span class="s">'exit'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">mock_exit</span><span class="p">)</span> | |
| 377 <span class="gp">...</span> | |
| 378 <span class="gp">>>> </span><span class="n">test_function</span><span class="p">()</span> | |
| 379 </pre></div> | |
| 380 </div> | |
| 381 <p>If <cite>patch.multiple</cite> is used as a context manager, the value returned by the | |
| 382 context manger is a dictionary where created mocks are keyed by name:</p> | |
| 383 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">multiple</span><span class="p">(</span><span class="s">'__main__'</span><span class="p">,</span> <span class="n">thing</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">)</span> <span class="k">as</span> <span class="n">values</span><span class="p">:</span> | |
| 384 <span class="gp">... </span> <span class="k">assert</span> <span class="s">'other'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">values</span><span class="p">[</span><span class="s">'other'</span><span class="p">])</span> | |
| 385 <span class="gp">... </span> <span class="k">assert</span> <span class="s">'thing'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">values</span><span class="p">[</span><span class="s">'thing'</span><span class="p">])</span> | |
| 386 <span class="gp">... </span> <span class="k">assert</span> <span class="n">values</span><span class="p">[</span><span class="s">'thing'</span><span class="p">]</span> <span class="ow">is</span> <span class="n">thing</span> | |
| 387 <span class="gp">... </span> <span class="k">assert</span> <span class="n">values</span><span class="p">[</span><span class="s">'other'</span><span class="p">]</span> <span class="ow">is</span> <span class="n">other</span> | |
| 388 <span class="gp">...</span> | |
| 389 </pre></div> | |
| 390 </div> | |
| 391 </div> | |
| 392 <div class="section" id="patch-methods-start-and-stop"> | |
| 393 <span id="start-and-stop"></span><h2>patch methods: start and stop<a class="headerlink" href="#patch-methods-start-and-stop" title="Permalink to this headline">¶</a></h2> | |
| 394 <p>All the patchers have <cite>start</cite> and <cite>stop</cite> methods. These make it simpler to do | |
| 395 patching in <cite>setUp</cite> methods or where you want to do multiple patches without | |
| 396 nesting decorators or with statements.</p> | |
| 397 <p>To use them call <cite>patch</cite>, <cite>patch.object</cite> or <cite>patch.dict</cite> as normal and keep a | |
| 398 reference to the returned <cite>patcher</cite> object. You can then call <cite>start</cite> to put | |
| 399 the patch in place and <cite>stop</cite> to undo it.</p> | |
| 400 <p>If you are using <cite>patch</cite> to create a mock for you then it will be returned by | |
| 401 the call to <cite>patcher.start</cite>.</p> | |
| 402 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.ClassName'</span><span class="p">)</span> | |
| 403 <span class="gp">>>> </span><span class="kn">from</span> <span class="nn">package</span> <span class="kn">import</span> <span class="n">module</span> | |
| 404 <span class="gp">>>> </span><span class="n">original</span> <span class="o">=</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> | |
| 405 <span class="gp">>>> </span><span class="n">new_mock</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> | |
| 406 <span class="gp">>>> </span><span class="k">assert</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">original</span> | |
| 407 <span class="gp">>>> </span><span class="k">assert</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> <span class="ow">is</span> <span class="n">new_mock</span> | |
| 408 <span class="gp">>>> </span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> | |
| 409 <span class="gp">>>> </span><span class="k">assert</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> <span class="ow">is</span> <span class="n">original</span> | |
| 410 <span class="gp">>>> </span><span class="k">assert</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">new_mock</span> | |
| 411 </pre></div> | |
| 412 </div> | |
| 413 <p>A typical use case for this might be for doing multiple patches in the <cite>setUp</cite> | |
| 414 method of a <cite>TestCase</cite>:</p> | |
| 415 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span> | |
| 416 <span class="gp">... </span> <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 417 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher1</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.Class1'</span><span class="p">)</span> | |
| 418 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher2</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.Class2'</span><span class="p">)</span> | |
| 419 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass1</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher1</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> | |
| 420 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass2</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher2</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> | |
| 421 <span class="gp">...</span> | |
| 422 <span class="gp">... </span> <span class="k">def</span> <span class="nf">tearDown</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 423 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher1</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> | |
| 424 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher2</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> | |
| 425 <span class="gp">...</span> | |
| 426 <span class="gp">... </span> <span class="k">def</span> <span class="nf">test_something</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 427 <span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">Class1</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass1</span> | |
| 428 <span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">Class2</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass2</span> | |
| 429 <span class="gp">...</span> | |
| 430 <span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_something'</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span> | |
| 431 </pre></div> | |
| 432 </div> | |
| 433 <div class="admonition caution"> | |
| 434 <p class="first admonition-title">Caution</p> | |
| 435 <p>If you use this technique you must ensure that the patching is “undone” by | |
| 436 calling <cite>stop</cite>. This can be fiddlier than you might think, because if an | |
| 437 exception is raised in the setUp then tearDown is not called. <a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest2</a> cleanup functions make this | |
| 438 easier.</p> | |
| 439 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span> | |
| 440 <span class="gp">... </span> <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 441 <span class="gp">... </span> <span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.Class'</span><span class="p">)</span> | |
| 442 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> | |
| 443 <span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">addCleanup</span><span class="p">(</span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">)</span> | |
| 444 <span class="gp">...</span> | |
| 445 <span class="gp">... </span> <span class="k">def</span> <span class="nf">test_something</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 446 <span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">Class</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass</span> | |
| 447 <span class="gp">...</span> | |
| 448 <span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_something'</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span> | |
| 449 </pre></div> | |
| 450 </div> | |
| 451 <p class="last">As an added bonus you no longer need to keep a reference to the <cite>patcher</cite> | |
| 452 object.</p> | |
| 453 </div> | |
| 454 <p>It is also possible to stop all patches which have been started by using | |
| 455 <cite>patch.stopall</cite>.</p> | |
| 456 <dl class="function"> | |
| 457 <dt id="mock.patch.stopall"> | |
| 458 <tt class="descclassname">patch.</tt><tt class="descname">stopall</tt><big>(</big><big>)</big><a class="headerlink" href="#mock.patch.stopall" title="Permalink to this definition">¶</a></dt> | |
| 459 <dd><p>Stop all active patches. Only stops patches started with <cite>start</cite>.</p> | |
| 460 </dd></dl> | |
| 461 | |
| 462 </div> | |
| 463 <div class="section" id="test-prefix"> | |
| 464 <h2>TEST_PREFIX<a class="headerlink" href="#test-prefix" title="Permalink to this headline">¶</a></h2> | |
| 465 <p>All of the patchers can be used as class decorators. When used in this way | |
| 466 they wrap every test method on the class. The patchers recognise methods that | |
| 467 start with <cite>test</cite> as being test methods. This is the same way that the | |
| 468 <cite>unittest.TestLoader</cite> finds test methods by default.</p> | |
| 469 <p>It is possible that you want to use a different prefix for your tests. You can | |
| 470 inform the patchers of the different prefix by setting <cite>patch.TEST_PREFIX</cite>:</p> | |
| 471 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">patch</span><span class="o">.</span><span class="n">TEST_PREFIX</span> <span class="o">=</span> <span class="s">'foo'</span> | |
| 472 <span class="gp">>>> </span><span class="n">value</span> <span class="o">=</span> <span class="mi">3</span> | |
| 473 <span class="go">>>></span> | |
| 474 <span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'__main__.value'</span><span class="p">,</span> <span class="s">'not three'</span><span class="p">)</span> | |
| 475 <span class="gp">... </span><span class="k">class</span> <span class="nc">Thing</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> | |
| 476 <span class="gp">... </span> <span class="k">def</span> <span class="nf">foo_one</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 477 <span class="gp">... </span> <span class="k">print</span> <span class="n">value</span> | |
| 478 <span class="gp">... </span> <span class="k">def</span> <span class="nf">foo_two</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> | |
| 479 <span class="gp">... </span> <span class="k">print</span> <span class="n">value</span> | |
| 480 <span class="gp">...</span> | |
| 481 <span class="go">>>></span> | |
| 482 <span class="gp">>>> </span><span class="n">Thing</span><span class="p">()</span><span class="o">.</span><span class="n">foo_one</span><span class="p">()</span> | |
| 483 <span class="go">not three</span> | |
| 484 <span class="gp">>>> </span><span class="n">Thing</span><span class="p">()</span><span class="o">.</span><span class="n">foo_two</span><span class="p">()</span> | |
| 485 <span class="go">not three</span> | |
| 486 <span class="gp">>>> </span><span class="n">value</span> | |
| 487 <span class="go">3</span> | |
| 488 </pre></div> | |
| 489 </div> | |
| 490 </div> | |
| 491 <div class="section" id="nesting-patch-decorators"> | |
| 492 <h2>Nesting Patch Decorators<a class="headerlink" href="#nesting-patch-decorators" title="Permalink to this headline">¶</a></h2> | |
| 493 <p>If you want to perform multiple patches then you can simply stack up the | |
| 494 decorators.</p> | |
| 495 <p>You can stack up multiple patch decorators using this pattern:</p> | |
| 496 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch.object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s">'class_method'</span><span class="p">)</span> | |
| 497 <span class="gp">... </span><span class="nd">@patch.object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s">'static_method'</span><span class="p">)</span> | |
| 498 <span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">mock1</span><span class="p">,</span> <span class="n">mock2</span><span class="p">):</span> | |
| 499 <span class="gp">... </span> <span class="k">assert</span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">static_method</span> <span class="ow">is</span> <span class="n">mock1</span> | |
| 500 <span class="gp">... </span> <span class="k">assert</span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">class_method</span> <span class="ow">is</span> <span class="n">mock2</span> | |
| 501 <span class="gp">... </span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">static_method</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span> | |
| 502 <span class="gp">... </span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">class_method</span><span class="p">(</span><span class="s">'bar'</span><span class="p">)</span> | |
| 503 <span class="gp">... </span> <span class="k">return</span> <span class="n">mock1</span><span class="p">,</span> <span class="n">mock2</span> | |
| 504 <span class="gp">...</span> | |
| 505 <span class="gp">>>> </span><span class="n">mock1</span><span class="p">,</span> <span class="n">mock2</span> <span class="o">=</span> <span class="n">test</span><span class="p">()</span> | |
| 506 <span class="gp">>>> </span><span class="n">mock1</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> | |
| 507 <span class="gp">>>> </span><span class="n">mock2</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s">'bar'</span><span class="p">)</span> | |
| 508 </pre></div> | |
| 509 </div> | |
| 510 <p>Note that the decorators are applied from the bottom upwards. This is the | |
| 511 standard way that Python applies decorators. The order of the created mocks | |
| 512 passed into your test function matches this order.</p> | |
| 513 <p>Like all context-managers patches can be nested using contextlib’s nested | |
| 514 function; <em>every</em> patching will appear in the tuple after “as”:</p> | |
| 515 <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">nested</span> | |
| 516 <span class="gp">>>> </span><span class="k">with</span> <span class="n">nested</span><span class="p">(</span> | |
| 517 <span class="gp">... </span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.ClassName1'</span><span class="p">),</span> | |
| 518 <span class="gp">... </span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.ClassName2'</span><span class="p">)</span> | |
| 519 <span class="gp">... </span> <span class="p">)</span> <span class="k">as</span> <span class="p">(</span><span class="n">MockClass1</span><span class="p">,</span> <span class="n">MockClass2</span><span class="p">):</span> | |
| 520 <span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">ClassName1</span> <span class="ow">is</span> <span class="n">MockClass1</span> | |
| 521 <span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">ClassName2</span> <span class="ow">is</span> <span class="n">MockClass2</span> | |
| 522 <span class="gp">...</span> | |
| 523 </pre></div> | |
| 524 </div> | |
| 525 </div> | |
| 526 <div class="section" id="where-to-patch"> | |
| 527 <span id="id1"></span><h2>Where to patch<a class="headerlink" href="#where-to-patch" title="Permalink to this headline">¶</a></h2> | |
| 528 <p><cite>patch</cite> works by (temporarily) changing the object that a <em>name</em> points to with | |
| 529 another one. There can be many names pointing to any individual object, so | |
| 530 for patching to work you must ensure that you patch the name used by the system | |
| 531 under test.</p> | |
| 532 <p>The basic principle is that you patch where an object is <em>looked up</em>, which | |
| 533 is not necessarily the same place as where it is defined. A couple of | |
| 534 examples will help to clarify this.</p> | |
| 535 <p>Imagine we have a project that we want to test with the following structure:</p> | |
| 536 <div class="highlight-python"><pre>a.py | |
| 537 -> Defines SomeClass | |
| 538 | |
| 539 b.py | |
| 540 -> from a import SomeClass | |
| 541 -> some_function instantiates SomeClass</pre> | |
| 542 </div> | |
| 543 <p>Now we want to test <cite>some_function</cite> but we want to mock out <cite>SomeClass</cite> using | |
| 544 <cite>patch</cite>. The problem is that when we import module b, which we will have to | |
| 545 do then it imports <cite>SomeClass</cite> from module a. If we use <cite>patch</cite> to mock out | |
| 546 <cite>a.SomeClass</cite> then it will have no effect on our test; module b already has a | |
| 547 reference to the <em>real</em> <cite>SomeClass</cite> and it looks like our patching had no | |
| 548 effect.</p> | |
| 549 <p>The key is to patch out <cite>SomeClass</cite> where it is used (or where it is looked up | |
| 550 ). In this case <cite>some_function</cite> will actually look up <cite>SomeClass</cite> in module b, | |
| 551 where we have imported it. The patching should look like:</p> | |
| 552 <blockquote> | |
| 553 <div><cite>@patch(‘b.SomeClass’)</cite></div></blockquote> | |
| 554 <p>However, consider the alternative scenario where instead of <cite>from a import | |
| 555 SomeClass</cite> module b does <cite>import a</cite> and <cite>some_function</cite> uses <cite>a.SomeClass</cite>. Both | |
| 556 of these import forms are common. In this case the class we want to patch is | |
| 557 being looked up on the a module and so we have to patch <cite>a.SomeClass</cite> instead:</p> | |
| 558 <blockquote> | |
| 559 <div><cite>@patch(‘a.SomeClass’)</cite></div></blockquote> | |
| 560 </div> | |
| 561 <div class="section" id="patching-descriptors-and-proxy-objects"> | |
| 562 <h2>Patching Descriptors and Proxy Objects<a class="headerlink" href="#patching-descriptors-and-proxy-objects" title="Permalink to this headline">¶</a></h2> | |
| 563 <p>Since version 0.6.0 both <a class="reference internal" href="#patch">patch</a> and <a class="reference internal" href="#patch-object">patch.object</a> have been able to correctly | |
| 564 patch and restore descriptors: class methods, static methods and properties. | |
| 565 You should patch these on the <em>class</em> rather than an instance.</p> | |
| 566 <p>Since version 0.7.0 <a class="reference internal" href="#patch">patch</a> and <a class="reference internal" href="#patch-object">patch.object</a> work correctly with some objects | |
| 567 that proxy attribute access, like the <a class="reference external" href="http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198">django setttings object</a>.</p> | |
| 568 <div class="admonition note"> | |
| 569 <p class="first admonition-title">Note</p> | |
| 570 <p class="last">In django <cite>import settings</cite> and <cite>from django.conf import settings</cite> | |
| 571 return different objects. If you are using libraries / apps that do both you | |
| 572 may have to patch both. Grrr...</p> | |
| 573 </div> | |
| 574 </div> | |
| 575 </div> | |
| 576 | |
| 577 | |
| 578 </div> | |
| 579 </div> | |
| 580 </div> | |
| 581 <div class="sphinxsidebar"> | |
| 582 <div class="sphinxsidebarwrapper"> | |
| 583 <h3><a href="index.html">Table Of Contents</a></h3> | |
| 584 <ul> | |
| 585 <li><a class="reference internal" href="#">Patch Decorators</a><ul> | |
| 586 <li><a class="reference internal" href="#patch">patch</a></li> | |
| 587 <li><a class="reference internal" href="#patch-object">patch.object</a></li> | |
| 588 <li><a class="reference internal" href="#patch-dict">patch.dict</a></li> | |
| 589 <li><a class="reference internal" href="#patch-multiple">patch.multiple</a></li> | |
| 590 <li><a class="reference internal" href="#patch-methods-start-and-stop">patch methods: start and stop</a></li> | |
| 591 <li><a class="reference internal" href="#test-prefix">TEST_PREFIX</a></li> | |
| 592 <li><a class="reference internal" href="#nesting-patch-decorators">Nesting Patch Decorators</a></li> | |
| 593 <li><a class="reference internal" href="#where-to-patch">Where to patch</a></li> | |
| 594 <li><a class="reference internal" href="#patching-descriptors-and-proxy-objects">Patching Descriptors and Proxy Objects</a></li> | |
| 595 </ul> | |
| 596 </li> | |
| 597 </ul> | |
| 598 | |
| 599 <h4>Previous topic</h4> | |
| 600 <p class="topless"><a href="mock.html" | |
| 601 title="previous chapter">The Mock Class</a></p> | |
| 602 <h4>Next topic</h4> | |
| 603 <p class="topless"><a href="helpers.html" | |
| 604 title="next chapter">Helpers</a></p> | |
| 605 <h3>This Page</h3> | |
| 606 <ul class="this-page-menu"> | |
| 607 <li><a href="_sources/patch.txt" | |
| 608 rel="nofollow">Show Source</a></li> | |
| 609 </ul> | |
| 610 <div id="searchbox" style="display: none"> | |
| 611 <h3>Quick search</h3> | |
| 612 <form class="search" action="search.html" method="get"> | |
| 613 <input type="text" name="q" /> | |
| 614 <input type="submit" value="Go" /> | |
| 615 <input type="hidden" name="check_keywords" value="yes" /> | |
| 616 <input type="hidden" name="area" value="default" /> | |
| 617 </form> | |
| 618 <p class="searchtip" style="font-size: 90%"> | |
| 619 Enter search terms or a module, class or function name. | |
| 620 </p> | |
| 621 </div> | |
| 622 <script type="text/javascript">$('#searchbox').show(0);</script> | |
| 623 </div> | |
| 624 </div> | |
| 625 <div class="clearer"></div> | |
| 626 </div> | |
| 627 <div class="related"> | |
| 628 <h3>Navigation</h3> | |
| 629 <ul> | |
| 630 <li class="right" style="margin-right: 10px"> | |
| 631 <a href="genindex.html" title="General Index" | |
| 632 >index</a></li> | |
| 633 <li class="right" > | |
| 634 <a href="helpers.html" title="Helpers" | |
| 635 >next</a> |</li> | |
| 636 <li class="right" > | |
| 637 <a href="mock.html" title="The Mock Class" | |
| 638 >previous</a> |</li> | |
| 639 <li><a href="index.html">Mock 1.0.0 documentation</a> »</li> | |
| 640 </ul> | |
| 641 </div> | |
| 642 <div class="footer"> | |
| 643 © Copyright 2007-2012, Michael Foord & the mock team. | |
| 644 Last updated on Oct 07, 2012. | |
| 645 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3. | |
| 646 </div> | |
| 647 </body> | |
| 648 </html> |
