Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
關注 1
收藏 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
目錄樹: 0f75e31513
分支列表 標籤
${ item.name }
建立分支 ${ searchTerm }
從 '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/unittest.mock.html

3230 line
386KB
原始文件 Blame 歷史記錄 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="unittest.mock — mock object library" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/library/unittest.mock.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Source code: Lib/unittest/mock.py unittest.mock is a library for testing in Python. It allows you to replace parts of your system under test with mock objects and make assertions about how they hav..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Source code: Lib/unittest/mock.py unittest.mock is a library for testing in Python. It allows you to replace parts of your system under test with mock objects and make assertions about how they hav..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>unittest.mock — mock object library &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="unittest.mock — getting started" href="unittest.mock-examples.html" />

  39.     <link rel="prev" title="unittest — Unit testing framework" href="unittest.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/unittest.mock.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code> — mock object library</a><ul>

  99. <li><a class="reference internal" href="#quick-guide">Quick Guide</a></li>

  100. <li><a class="reference internal" href="#the-mock-class">The Mock Class</a><ul>

  101. <li><a class="reference internal" href="#calling">Calling</a></li>

  102. <li><a class="reference internal" href="#deleting-attributes">Deleting Attributes</a></li>

  103. <li><a class="reference internal" href="#mock-names-and-the-name-attribute">Mock names and the name attribute</a></li>

  104. <li><a class="reference internal" href="#attaching-mocks-as-attributes">Attaching Mocks as Attributes</a></li>

  105. </ul>

  106. </li>

  107. <li><a class="reference internal" href="#the-patchers">The patchers</a><ul>

  108. <li><a class="reference internal" href="#patch">patch</a></li>

  109. <li><a class="reference internal" href="#patch-object">patch.object</a></li>

  110. <li><a class="reference internal" href="#patch-dict">patch.dict</a></li>

  111. <li><a class="reference internal" href="#patch-multiple">patch.multiple</a></li>

  112. <li><a class="reference internal" href="#patch-methods-start-and-stop">patch methods: start and stop</a></li>

  113. <li><a class="reference internal" href="#patch-builtins">patch builtins</a></li>

  114. <li><a class="reference internal" href="#test-prefix">TEST_PREFIX</a></li>

  115. <li><a class="reference internal" href="#nesting-patch-decorators">Nesting Patch Decorators</a></li>

  116. <li><a class="reference internal" href="#where-to-patch">Where to patch</a></li>

  117. <li><a class="reference internal" href="#patching-descriptors-and-proxy-objects">Patching Descriptors and Proxy Objects</a></li>

  118. </ul>

  119. </li>

  120. <li><a class="reference internal" href="#magicmock-and-magic-method-support">MagicMock and magic method support</a><ul>

  121. <li><a class="reference internal" href="#mocking-magic-methods">Mocking Magic Methods</a></li>

  122. <li><a class="reference internal" href="#magic-mock">Magic Mock</a></li>

  123. </ul>

  124. </li>

  125. <li><a class="reference internal" href="#helpers">Helpers</a><ul>

  126. <li><a class="reference internal" href="#sentinel">sentinel</a></li>

  127. <li><a class="reference internal" href="#default">DEFAULT</a></li>

  128. <li><a class="reference internal" href="#call">call</a></li>

  129. <li><a class="reference internal" href="#create-autospec">create_autospec</a></li>

  130. <li><a class="reference internal" href="#any">ANY</a></li>

  131. <li><a class="reference internal" href="#filter-dir">FILTER_DIR</a></li>

  132. <li><a class="reference internal" href="#mock-open">mock_open</a></li>

  133. <li><a class="reference internal" href="#autospeccing">Autospeccing</a></li>

  134. <li><a class="reference internal" href="#sealing-mocks">Sealing mocks</a></li>

  135. </ul>

  136. </li>

  137. <li><a class="reference internal" href="#order-of-precedence-of-side-effect-return-value-and-wraps">Order of precedence of <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code> and <em>wraps</em></a></li>

  138. </ul>

  139. </li>

  140. </ul>

  141. 

  142.   </div>

  143.   <div>

  144.     <h4>Previous topic</h4>

  145.     <p class="topless"><a href="unittest.html"

  146.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> — Unit testing framework</a></p>

  147.   </div>

  148.   <div>

  149.     <h4>Next topic</h4>

  150.     <p class="topless"><a href="unittest.mock-examples.html"

  151.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code> — getting started</a></p>

  152.   </div>

  153.   <div role="note" aria-label="source link">

  154.     <h3>This Page</h3>

  155.     <ul class="this-page-menu">

  156.       <li><a href="../bugs.html">Report a Bug</a></li>

  157.       <li>

  158.         <a href="https://github.com/python/cpython/blob/main/Doc/library/unittest.mock.rst"

  159.             rel="nofollow">Show Source

  160.         </a>

  161.       </li>

  162.     </ul>

  163.   </div>

  164.         </nav>

  165.     </div>

  166. </div>

  167. 

  168.   

  169.     <div class="related" role="navigation" aria-label="related navigation">

  170.       <h3>Navigation</h3>

  171.       <ul>

  172.         <li class="right" style="margin-right: 10px">

  173.           <a href="../genindex.html" title="General Index"

  174.              accesskey="I">index</a></li>

  175.         <li class="right" >

  176.           <a href="../py-modindex.html" title="Python Module Index"

  177.              >modules</a> |</li>

  178.         <li class="right" >

  179.           <a href="unittest.mock-examples.html" title="unittest.mock — getting started"

  180.              accesskey="N">next</a> |</li>

  181.         <li class="right" >

  182.           <a href="unittest.html" title="unittest — Unit testing framework"

  183.              accesskey="P">previous</a> |</li>

  184. 

  185.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  186.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  187.           <li class="switchers">

  188.             <div class="language_switcher_placeholder"></div>

  189.             <div class="version_switcher_placeholder"></div>

  190.           </li>

  191.           <li>

  192.               

  193.           </li>

  194.     <li id="cpython-language-and-version">

  195.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  196.     </li>

  197. 

  198.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  199.           <li class="nav-item nav-item-2"><a href="development.html" accesskey="U">Development Tools</a> &#187;</li>

  200.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code> — mock object library</a></li>

  201.                 <li class="right">

  202.                     

  203. 

  204.     <div class="inline-search" role="search">

  205.         <form class="inline-search" action="../search.html" method="get">

  206.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  207.           <input type="submit" value="Go" />

  208.         </form>

  209.     </div>

  210.                      |

  211.                 </li>

  212.             <li class="right">

  213. <label class="theme-selector-label">

  214.     Theme

  215.     <select class="theme-selector" oninput="activateTheme(this.value)">

  216.         <option value="auto" selected>Auto</option>

  217.         <option value="light">Light</option>

  218.         <option value="dark">Dark</option>

  219.     </select>

  220. </label> |</li>

  221.             

  222.       </ul>

  223.     </div>    

  224. 

  225.     <div class="document">

  226.       <div class="documentwrapper">

  227.         <div class="bodywrapper">

  228.           <div class="body" role="main">

  229.             

  230.   <section id="module-unittest.mock">

  231. <span id="unittest-mock-mock-object-library"></span><h1><a class="reference internal" href="#module-unittest.mock" title="unittest.mock: Mock object library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code></a> — mock object library<a class="headerlink" href="#module-unittest.mock" title="Link to this heading">¶</a></h1>

  232. <div class="versionadded">

  233. <p><span class="versionmodified added">New in version 3.3.</span></p>

  234. </div>

  235. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/unittest/mock.py">Lib/unittest/mock.py</a></p>

  236. <hr class="docutils" />

  237. <p><a class="reference internal" href="#module-unittest.mock" title="unittest.mock: Mock object library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code></a> is a library for testing in Python. It allows you to

  238. replace parts of your system under test with mock objects and make assertions

  239. about how they have been used.</p>

  240. <p><a class="reference internal" href="#module-unittest.mock" title="unittest.mock: Mock object library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code></a> provides a core <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> class removing the need to

  241. create a host of stubs throughout your test suite. After performing an

  242. action, you can make assertions about which methods / attributes were used

  243. and arguments they were called with. You can also specify return values and

  244. set needed attributes in the normal way.</p>

  245. <p>Additionally, mock provides a <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> decorator that handles patching

  246. module and class level attributes within the scope of a test, along with

  247. <a class="reference internal" href="#unittest.mock.sentinel" title="unittest.mock.sentinel"><code class="xref py py-const docutils literal notranslate"><span class="pre">sentinel</span></code></a> for creating unique objects. See the <a class="reference internal" href="#quick-guide">quick guide</a> for

  248. some examples of how to use <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a>, <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> and

  249. <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>.</p>

  250. <p>Mock is designed for use with <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> and

  251. is based on the ‘action -&gt; assertion’ pattern instead of ‘record -&gt; replay’

  252. used by many mocking frameworks.</p>

  253. <p>There is a backport of <a class="reference internal" href="#module-unittest.mock" title="unittest.mock: Mock object library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code></a> for earlier versions of Python,

  254. available as <a class="reference external" href="https://pypi.org/project/mock">mock on PyPI</a>.</p>

  255. <section id="quick-guide">

  256. <h2>Quick Guide<a class="headerlink" href="#quick-guide" title="Link to this heading">¶</a></h2>

  257. <p><a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> and <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> objects create all attributes and

  258. methods as you access them and store details of how they have been used. You

  259. can configure them, to specify return values or limit what attributes are

  260. available, and then make assertions about how they have been used:</p>

  261. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">MagicMock</span>

  262. <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>

  263. <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>

  264. <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="s1">&#39;value&#39;</span><span class="p">)</span>

  265. <span class="go">3</span>

  266. <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="s1">&#39;value&#39;</span><span class="p">)</span>

  267. </pre></div>

  268. </div>

  269. <p><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code> allows you to perform side effects, including raising an

  270. exception when a mock is called:</p>

  271. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">Mock</span>

  272. <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="s1">&#39;foo&#39;</span><span class="p">))</span>

  273. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  274. <span class="gt">Traceback (most recent call last):</span>

  275. <span class="w"> </span><span class="c">...</span>

  276. <span class="gr">KeyError</span>: <span class="n">&#39;foo&#39;</span>

  277. </pre></div>

  278. </div>

  279. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">values</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;a&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;c&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">}</span>

  280. <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>

  281. <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>

  282. <span class="gp">...</span>

  283. <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>

  284. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="s1">&#39;a&#39;</span><span class="p">),</span> <span class="n">mock</span><span class="p">(</span><span class="s1">&#39;b&#39;</span><span class="p">),</span> <span class="n">mock</span><span class="p">(</span><span class="s1">&#39;c&#39;</span><span class="p">)</span>

  285. <span class="go">(1, 2, 3)</span>

  286. <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>

  287. <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>

  288. <span class="go">(5, 4, 3)</span>

  289. </pre></div>

  290. </div>

  291. <p>Mock has many other ways you can configure it and control its behaviour. For

  292. example the <em>spec</em> argument configures the mock to take its specification

  293. from another object. Attempting to access attributes or methods on the mock

  294. that don’t exist on the spec will fail with an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.</p>

  295. <p>The <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> decorator / context manager makes it easy to mock classes or

  296. objects in a module under test. The object you specify will be replaced with a

  297. mock (or other object) during the test and restored when the test ends:</p>

  298. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">patch</span>

  299. <span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;module.ClassName2&#39;</span><span class="p">)</span>

  300. <span class="gp">... </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;module.ClassName1&#39;</span><span class="p">)</span>

  301. <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>

  302. <span class="gp">... </span>    <span class="n">module</span><span class="o">.</span><span class="n">ClassName1</span><span class="p">()</span>

  303. <span class="gp">... </span>    <span class="n">module</span><span class="o">.</span><span class="n">ClassName2</span><span class="p">()</span>

  304. <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>

  305. <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>

  306. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">MockClass1</span><span class="o">.</span><span class="n">called</span>

  307. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">MockClass2</span><span class="o">.</span><span class="n">called</span>

  308. <span class="gp">...</span>

  309. <span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">()</span>

  310. </pre></div>

  311. </div>

  312. <div class="admonition note">

  313. <p class="admonition-title">Note</p>

  314. <p>When you nest patch decorators the mocks are passed in to the decorated

  315. function in the same order they applied (the normal <em>Python</em> order that

  316. decorators are applied). This means from the bottom up, so in the example

  317. above the mock for <code class="docutils literal notranslate"><span class="pre">module.ClassName1</span></code> is passed in first.</p>

  318. <p>With <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> it matters that you patch objects in the namespace where they

  319. are looked up. This is normally straightforward, but for a quick guide

  320. read <a class="reference internal" href="#where-to-patch"><span class="std std-ref">where to patch</span></a>.</p>

  321. </div>

  322. <p>As well as a decorator <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> can be used as a context manager in a with

  323. statement:</p>

  324. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">&#39;method&#39;</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_method</span><span class="p">:</span>

  325. <span class="gp">... </span>    <span class="n">thing</span> <span class="o">=</span> <span class="n">ProductionClass</span><span class="p">()</span>

  326. <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>

  327. <span class="gp">...</span>

  328. <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>

  329. </pre></div>

  330. </div>

  331. <p>There is also <a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> for setting values in a dictionary just

  332. during a scope and restoring the dictionary to its original state when the test

  333. ends:</p>

  334. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">foo</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;key&#39;</span><span class="p">:</span> <span class="s1">&#39;value&#39;</span><span class="p">}</span>

  335. <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>

  336. <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="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">},</span> <span class="n">clear</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>

  337. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{</span><span class="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">}</span>

  338. <span class="gp">...</span>

  339. <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>

  340. </pre></div>

  341. </div>

  342. <p>Mock supports the mocking of Python <a class="reference internal" href="#magic-methods"><span class="std std-ref">magic methods</span></a>. The

  343. easiest way of using magic methods is with the <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> class. It

  344. allows you to do things like:</p>

  345. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  346. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__str__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s1">&#39;foobarbaz&#39;</span>

  347. <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>

  348. <span class="go">&#39;foobarbaz&#39;</span>

  349. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__str__</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">()</span>

  350. </pre></div>

  351. </div>

  352. <p>Mock allows you to assign functions (or other Mock instances) to magic methods

  353. and they will be called appropriately. The <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> class is just a Mock

  354. variant that has all of the magic methods pre-created for you (well, all the

  355. useful ones anyway).</p>

  356. <p>The following is an example of using magic methods with the ordinary Mock

  357. class:</p>

  358. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  359. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__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="s1">&#39;wheeeeee&#39;</span><span class="p">)</span>

  360. <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>

  361. <span class="go">&#39;wheeeeee&#39;</span>

  362. </pre></div>

  363. </div>

  364. <p>For ensuring that the mock objects in your tests have the same api as the

  365. objects they are replacing, you can use <a class="reference internal" href="#auto-speccing"><span class="std std-ref">auto-speccing</span></a>.

  366. Auto-speccing can be done through the <em>autospec</em> argument to patch, or the

  367. <a class="reference internal" href="#unittest.mock.create_autospec" title="unittest.mock.create_autospec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_autospec()</span></code></a> function. Auto-speccing creates mock objects that

  368. have the same attributes and methods as the objects they are replacing, and

  369. any functions and methods (including constructors) have the same call

  370. signature as the real object.</p>

  371. <p>This ensures that your mocks will fail in the same way as your production

  372. code if they are used incorrectly:</p>

  373. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">create_autospec</span>

  374. <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>

  375. <span class="gp">... </span>    <span class="k">pass</span>

  376. <span class="gp">...</span>

  377. <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="s1">&#39;fishy&#39;</span><span class="p">)</span>

  378. <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>

  379. <span class="go">&#39;fishy&#39;</span>

  380. <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>

  381. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_function</span><span class="p">(</span><span class="s1">&#39;wrong arguments&#39;</span><span class="p">)</span>

  382. <span class="gt">Traceback (most recent call last):</span>

  383. <span class="w"> </span><span class="c">...</span>

  384. <span class="gr">TypeError</span>: <span class="n">&lt;lambda&gt;() takes exactly 3 arguments (1 given)</span>

  385. </pre></div>

  386. </div>

  387. <p><a class="reference internal" href="#unittest.mock.create_autospec" title="unittest.mock.create_autospec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_autospec()</span></code></a> can also be used on classes, where it copies the signature of

  388. the <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method, and on callable objects where it copies the signature of

  389. the <code class="docutils literal notranslate"><span class="pre">__call__</span></code> method.</p>

  390. </section>

  391. <section id="the-mock-class">

  392. <h2>The Mock Class<a class="headerlink" href="#the-mock-class" title="Link to this heading">¶</a></h2>

  393. <p><a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> is a flexible mock object intended to replace the use of stubs and

  394. test doubles throughout your code. Mocks are callable and create attributes as

  395. new mocks when you access them <a class="footnote-reference brackets" href="#id3" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. Accessing the same attribute will always

  396. return the same mock. Mocks record how you use them, allowing you to make

  397. assertions about what your code has done to them.</p>

  398. <p><a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> is a subclass of <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> with all the magic methods

  399. pre-created and ready to use. There are also non-callable variants, useful

  400. when you are mocking out objects that aren’t callable:

  401. <a class="reference internal" href="#unittest.mock.NonCallableMock" title="unittest.mock.NonCallableMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">NonCallableMock</span></code></a> and <a class="reference internal" href="#unittest.mock.NonCallableMagicMock" title="unittest.mock.NonCallableMagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">NonCallableMagicMock</span></code></a></p>

  402. <p>The <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> decorators makes it easy to temporarily replace classes

  403. in a particular module with a <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> object. By default <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> will create

  404. a <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> for you. You can specify an alternative class of <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> using

  405. the <em>new_callable</em> argument to <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>.</p>

  406. <dl class="py class">

  407. <dt class="sig sig-object py" id="unittest.mock.Mock">

  408. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">Mock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">spec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">side_effect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wraps</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec_set</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">unsafe</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock" title="Link to this definition">¶</a></dt>

  409. <dd><p>Create a new <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> object. <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> takes several optional arguments

  410. that specify the behaviour of the Mock object:</p>

  411. <ul>

  412. <li><p><em>spec</em>: This can be either a list of strings or an existing object (a

  413. class or instance) that acts as the specification for the mock object. If

  414. you pass in an object then a list of strings is formed by calling dir on

  415. the object (excluding unsupported magic attributes and methods).

  416. Accessing any attribute not in this list will raise an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.</p>

  417. <p>If <em>spec</em> is an object (rather than a list of strings) then

  418. <a class="reference internal" href="stdtypes.html#instance.__class__" title="instance.__class__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__class__</span></code></a> returns the class of the spec object. This

  419. allows mocks to pass <a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> tests.</p>

  420. </li>

  421. <li><p><em>spec_set</em>: A stricter variant of <em>spec</em>. If used, attempting to <em>set</em>

  422. or get an attribute on the mock that isn’t on the object passed as

  423. <em>spec_set</em> will raise an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.</p></li>

  424. <li><p><em>side_effect</em>: A function to be called whenever the Mock is called. See

  425. the <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> attribute. Useful for raising exceptions or

  426. dynamically changing return values. The function is called with the same

  427. arguments as the mock, and unless it returns <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a>, the return

  428. value of this function is used as the return value.</p>

  429. <p>Alternatively <em>side_effect</em> can be an exception class or instance. In

  430. this case the exception will be raised when the mock is called.</p>

  431. <p>If <em>side_effect</em> is an iterable then each call to the mock will return

  432. the next value from the iterable.</p>

  433. <p>A <em>side_effect</em> can be cleared by setting it to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>

  434. </li>

  435. <li><p><em>return_value</em>: The value returned when the mock is called. By default

  436. this is a new Mock (created on first access). See the

  437. <a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a> attribute.</p></li>

  438. <li><p><em>unsafe</em>: By default, accessing any attribute whose name starts with

  439. <em>assert</em>, <em>assret</em>, <em>asert</em>, <em>aseert</em> or <em>assrt</em> will raise an

  440. <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>. Passing <code class="docutils literal notranslate"><span class="pre">unsafe=True</span></code> will allow access to

  441. these attributes.</p>

  442. <div class="versionadded">

  443. <p><span class="versionmodified added">New in version 3.5.</span></p>

  444. </div>

  445. </li>

  446. <li><p><em>wraps</em>: Item for the mock object to wrap. If <em>wraps</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code> then

  447. calling the Mock will pass the call through to the wrapped object

  448. (returning the real result). Attribute access on the mock will return a

  449. Mock object that wraps the corresponding attribute of the wrapped

  450. object (so attempting to access an attribute that doesn’t exist will

  451. raise an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>).</p>

  452. <p>If the mock has an explicit <em>return_value</em> set then calls are not passed

  453. to the wrapped object and the <em>return_value</em> is returned instead.</p>

  454. </li>

  455. <li><p><em>name</em>: If the mock has a name then it will be used in the repr of the

  456. mock. This can be useful for debugging. The name is propagated to child

  457. mocks.</p></li>

  458. </ul>

  459. <p>Mocks can also be called with arbitrary keyword arguments. These will be

  460. used to set attributes on the mock after it is created. See the

  461. <a class="reference internal" href="#unittest.mock.Mock.configure_mock" title="unittest.mock.Mock.configure_mock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">configure_mock()</span></code></a> method for details.</p>

  462. <dl class="py method">

  463. <dt class="sig sig-object py" id="unittest.mock.Mock.assert_called">

  464. <span class="sig-name descname"><span class="pre">assert_called</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.assert_called" title="Link to this definition">¶</a></dt>

  465. <dd><p>Assert that the mock was called at least once.</p>

  466. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  467. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  468. <span class="go">&lt;Mock name=&#39;mock.method()&#39; id=&#39;...&#39;&gt;</span>

  469. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">assert_called</span><span class="p">()</span>

  470. </pre></div>

  471. </div>

  472. <div class="versionadded">

  473. <p><span class="versionmodified added">New in version 3.6.</span></p>

  474. </div>

  475. </dd></dl>

  476. 

  477. <dl class="py method">

  478. <dt class="sig sig-object py" id="unittest.mock.Mock.assert_called_once">

  479. <span class="sig-name descname"><span class="pre">assert_called_once</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.assert_called_once" title="Link to this definition">¶</a></dt>

  480. <dd><p>Assert that the mock was called exactly once.</p>

  481. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  482. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  483. <span class="go">&lt;Mock name=&#39;mock.method()&#39; id=&#39;...&#39;&gt;</span>

  484. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">assert_called_once</span><span class="p">()</span>

  485. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  486. <span class="go">&lt;Mock name=&#39;mock.method()&#39; id=&#39;...&#39;&gt;</span>

  487. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">assert_called_once</span><span class="p">()</span>

  488. <span class="gt">Traceback (most recent call last):</span>

  489. <span class="c">...</span>

  490. <span class="gr">AssertionError</span>: <span class="n">Expected &#39;method&#39; to have been called once. Called 2 times.</span>

  491. </pre></div>

  492. </div>

  493. <div class="versionadded">

  494. <p><span class="versionmodified added">New in version 3.6.</span></p>

  495. </div>

  496. </dd></dl>

  497. 

  498. <dl class="py method">

  499. <dt class="sig sig-object py" id="unittest.mock.Mock.assert_called_with">

  500. <span class="sig-name descname"><span class="pre">assert_called_with</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.assert_called_with" title="Link to this definition">¶</a></dt>

  501. <dd><p>This method is a convenient way of asserting that the last call has been

  502. made in a particular way:</p>

  503. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  504. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="n">test</span><span class="o">=</span><span class="s1">&#39;wow&#39;</span><span class="p">)</span>

  505. <span class="go">&lt;Mock name=&#39;mock.method()&#39; id=&#39;...&#39;&gt;</span>

  506. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="n">test</span><span class="o">=</span><span class="s1">&#39;wow&#39;</span><span class="p">)</span>

  507. </pre></div>

  508. </div>

  509. </dd></dl>

  510. 

  511. <dl class="py method">

  512. <dt class="sig sig-object py" id="unittest.mock.Mock.assert_called_once_with">

  513. <span class="sig-name descname"><span class="pre">assert_called_once_with</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.assert_called_once_with" title="Link to this definition">¶</a></dt>

  514. <dd><p>Assert that the mock was called exactly once and that call was with the

  515. specified arguments.</p>

  516. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  517. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;baz&#39;</span><span class="p">)</span>

  518. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;baz&#39;</span><span class="p">)</span>

  519. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="s1">&#39;other&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;values&#39;</span><span class="p">)</span>

  520. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s1">&#39;other&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;values&#39;</span><span class="p">)</span>

  521. <span class="gt">Traceback (most recent call last):</span>

  522. <span class="w">  </span><span class="c">...</span>

  523. <span class="gr">AssertionError</span>: <span class="n">Expected &#39;mock&#39; to be called once. Called 2 times.</span>

  524. </pre></div>

  525. </div>

  526. </dd></dl>

  527. 

  528. <dl class="py method">

  529. <dt class="sig sig-object py" id="unittest.mock.Mock.assert_any_call">

  530. <span class="sig-name descname"><span class="pre">assert_any_call</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.assert_any_call" title="Link to this definition">¶</a></dt>

  531. <dd><p>assert the mock has been called with the specified arguments.</p>

  532. <p>The assert passes if the mock has <em>ever</em> been called, unlike

  533. <a class="reference internal" href="#unittest.mock.Mock.assert_called_with" title="unittest.mock.Mock.assert_called_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_with()</span></code></a> and <a class="reference internal" href="#unittest.mock.Mock.assert_called_once_with" title="unittest.mock.Mock.assert_called_once_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_once_with()</span></code></a> that

  534. only pass if the call is the most recent one, and in the case of

  535. <a class="reference internal" href="#unittest.mock.Mock.assert_called_once_with" title="unittest.mock.Mock.assert_called_once_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_once_with()</span></code></a> it must also be the only call.</p>

  536. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  537. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">arg</span><span class="o">=</span><span class="s1">&#39;thing&#39;</span><span class="p">)</span>

  538. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="s1">&#39;some&#39;</span><span class="p">,</span> <span class="s1">&#39;thing&#39;</span><span class="p">,</span> <span class="s1">&#39;else&#39;</span><span class="p">)</span>

  539. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_any_call</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">arg</span><span class="o">=</span><span class="s1">&#39;thing&#39;</span><span class="p">)</span>

  540. </pre></div>

  541. </div>

  542. </dd></dl>

  543. 

  544. <dl class="py method">

  545. <dt class="sig sig-object py" id="unittest.mock.Mock.assert_has_calls">

  546. <span class="sig-name descname"><span class="pre">assert_has_calls</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">calls</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">any_order</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.assert_has_calls" title="Link to this definition">¶</a></dt>

  547. <dd><p>assert the mock has been called with the specified calls.

  548. The <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> list is checked for the calls.</p>

  549. <p>If <em>any_order</em> is false then the calls must be

  550. sequential. There can be extra calls before or after the

  551. specified calls.</p>

  552. <p>If <em>any_order</em> is true then the calls can be in any order, but

  553. they must all appear in <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a>.</p>

  554. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  555. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  556. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>

  557. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  558. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span>

  559. <span class="gp">&gt;&gt;&gt; </span><span class="n">calls</span> <span class="o">=</span> <span class="p">[</span><span class="n">call</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="n">call</span><span class="p">(</span><span class="mi">3</span><span class="p">)]</span>

  560. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_has_calls</span><span class="p">(</span><span class="n">calls</span><span class="p">)</span>

  561. <span class="gp">&gt;&gt;&gt; </span><span class="n">calls</span> <span class="o">=</span> <span class="p">[</span><span class="n">call</span><span class="p">(</span><span class="mi">4</span><span class="p">),</span> <span class="n">call</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="n">call</span><span class="p">(</span><span class="mi">3</span><span class="p">)]</span>

  562. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_has_calls</span><span class="p">(</span><span class="n">calls</span><span class="p">,</span> <span class="n">any_order</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  563. </pre></div>

  564. </div>

  565. </dd></dl>

  566. 

  567. <dl class="py method">

  568. <dt class="sig sig-object py" id="unittest.mock.Mock.assert_not_called">

  569. <span class="sig-name descname"><span class="pre">assert_not_called</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.assert_not_called" title="Link to this definition">¶</a></dt>

  570. <dd><p>Assert the mock was never called.</p>

  571. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">()</span>

  572. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">hello</span><span class="o">.</span><span class="n">assert_not_called</span><span class="p">()</span>

  573. <span class="gp">&gt;&gt;&gt; </span><span class="n">obj</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">hello</span><span class="p">()</span>

  574. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">hello</span><span class="o">.</span><span class="n">assert_not_called</span><span class="p">()</span>

  575. <span class="gt">Traceback (most recent call last):</span>

  576. <span class="w">  </span><span class="c">...</span>

  577. <span class="gr">AssertionError</span>: <span class="n">Expected &#39;hello&#39; to not have been called. Called 1 times.</span>

  578. </pre></div>

  579. </div>

  580. <div class="versionadded">

  581. <p><span class="versionmodified added">New in version 3.5.</span></p>

  582. </div>

  583. </dd></dl>

  584. 

  585. <dl class="py method">

  586. <dt class="sig sig-object py" id="unittest.mock.Mock.reset_mock">

  587. <span class="sig-name descname"><span class="pre">reset_mock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">side_effect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.reset_mock" title="Link to this definition">¶</a></dt>

  588. <dd><p>The reset_mock method resets all the call attributes on a mock object:</p>

  589. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  590. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)</span>

  591. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>

  592. <span class="go">True</span>

  593. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">reset_mock</span><span class="p">()</span>

  594. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>

  595. <span class="go">False</span>

  596. </pre></div>

  597. </div>

  598. <div class="versionchanged">

  599. <p><span class="versionmodified changed">Changed in version 3.6: </span>Added two keyword-only arguments to the reset_mock function.</p>

  600. </div>

  601. <p>This can be useful where you want to make a series of assertions that

  602. reuse the same object. Note that <a class="reference internal" href="#unittest.mock.Mock.reset_mock" title="unittest.mock.Mock.reset_mock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">reset_mock()</span></code></a> <em>doesn’t</em> clear the

  603. return value, <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> or any child attributes you have

  604. set using normal assignment by default. In case you want to reset

  605. <em>return_value</em> or <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a>, then pass the corresponding

  606. parameter as <code class="docutils literal notranslate"><span class="pre">True</span></code>. Child mocks and the return value mock

  607. (if any) are reset as well.</p>

  608. <div class="admonition note">

  609. <p class="admonition-title">Note</p>

  610. <p><em>return_value</em>, and <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> are keyword-only

  611. arguments.</p>

  612. </div>

  613. </dd></dl>

  614. 

  615. <dl class="py method">

  616. <dt class="sig sig-object py" id="unittest.mock.Mock.mock_add_spec">

  617. <span class="sig-name descname"><span class="pre">mock_add_spec</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">spec</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec_set</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.mock_add_spec" title="Link to this definition">¶</a></dt>

  618. <dd><p>Add a spec to a mock. <em>spec</em> can either be an object or a

  619. list of strings. Only attributes on the <em>spec</em> can be fetched as

  620. attributes from the mock.</p>

  621. <p>If <em>spec_set</em> is true then only attributes on the spec can be set.</p>

  622. </dd></dl>

  623. 

  624. <dl class="py method">

  625. <dt class="sig sig-object py" id="unittest.mock.Mock.attach_mock">

  626. <span class="sig-name descname"><span class="pre">attach_mock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mock</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attribute</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.attach_mock" title="Link to this definition">¶</a></dt>

  627. <dd><p>Attach a mock as an attribute of this one, replacing its name and

  628. parent. Calls to the attached mock will be recorded in the

  629. <a class="reference internal" href="#unittest.mock.Mock.method_calls" title="unittest.mock.Mock.method_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">method_calls</span></code></a> and <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> attributes of this one.</p>

  630. </dd></dl>

  631. 

  632. <dl class="py method">

  633. <dt class="sig sig-object py" id="unittest.mock.Mock.configure_mock">

  634. <span class="sig-name descname"><span class="pre">configure_mock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.configure_mock" title="Link to this definition">¶</a></dt>

  635. <dd><p>Set attributes on the mock through keyword arguments.</p>

  636. <p>Attributes plus return values and side effects can be set on child

  637. mocks using standard dot notation and unpacking a dictionary in the

  638. method call:</p>

  639. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  640. <span class="gp">&gt;&gt;&gt; </span><span class="n">attrs</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;method.return_value&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s1">&#39;other.side_effect&#39;</span><span class="p">:</span> <span class="ne">KeyError</span><span class="p">}</span>

  641. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">configure_mock</span><span class="p">(</span><span class="o">**</span><span class="n">attrs</span><span class="p">)</span>

  642. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  643. <span class="go">3</span>

  644. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">other</span><span class="p">()</span>

  645. <span class="gt">Traceback (most recent call last):</span>

  646. <span class="w">  </span><span class="c">...</span>

  647. <span class="gr">KeyError</span>

  648. </pre></div>

  649. </div>

  650. <p>The same thing can be achieved in the constructor call to mocks:</p>

  651. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">attrs</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;method.return_value&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s1">&#39;other.side_effect&#39;</span><span class="p">:</span> <span class="ne">KeyError</span><span class="p">}</span>

  652. <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">some_attribute</span><span class="o">=</span><span class="s1">&#39;eggs&#39;</span><span class="p">,</span> <span class="o">**</span><span class="n">attrs</span><span class="p">)</span>

  653. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">some_attribute</span>

  654. <span class="go">&#39;eggs&#39;</span>

  655. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  656. <span class="go">3</span>

  657. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">other</span><span class="p">()</span>

  658. <span class="gt">Traceback (most recent call last):</span>

  659. <span class="w">  </span><span class="c">...</span>

  660. <span class="gr">KeyError</span>

  661. </pre></div>

  662. </div>

  663. <p><a class="reference internal" href="#unittest.mock.Mock.configure_mock" title="unittest.mock.Mock.configure_mock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">configure_mock()</span></code></a> exists to make it easier to do configuration

  664. after the mock has been created.</p>

  665. </dd></dl>

  666. 

  667. <dl class="py method">

  668. <dt class="sig sig-object py" id="unittest.mock.Mock.__dir__">

  669. <span class="sig-name descname"><span class="pre">__dir__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock.__dir__" title="Link to this definition">¶</a></dt>

  670. <dd><p><a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> objects limit the results of <code class="docutils literal notranslate"><span class="pre">dir(some_mock)</span></code> to useful results.

  671. For mocks with a <em>spec</em> this includes all the permitted attributes

  672. for the mock.</p>

  673. <p>See <a class="reference internal" href="#unittest.mock.FILTER_DIR" title="unittest.mock.FILTER_DIR"><code class="xref py py-data docutils literal notranslate"><span class="pre">FILTER_DIR</span></code></a> for what this filtering does, and how to

  674. switch it off.</p>

  675. </dd></dl>

  676. 

  677. <dl class="py method">

  678. <dt class="sig sig-object py" id="unittest.mock.Mock._get_child_mock">

  679. <span class="sig-name descname"><span class="pre">_get_child_mock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.Mock._get_child_mock" title="Link to this definition">¶</a></dt>

  680. <dd><p>Create the child mocks for attributes and return value.

  681. By default child mocks will be the same type as the parent.

  682. Subclasses of Mock may want to override this to customize the way

  683. child mocks are made.</p>

  684. <p>For non-callable mocks the callable variant will be used (rather than

  685. any custom subclass).</p>

  686. </dd></dl>

  687. 

  688. <dl class="py attribute">

  689. <dt class="sig sig-object py" id="unittest.mock.Mock.called">

  690. <span class="sig-name descname"><span class="pre">called</span></span><a class="headerlink" href="#unittest.mock.Mock.called" title="Link to this definition">¶</a></dt>

  691. <dd><p>A boolean representing whether or not the mock object has been called:</p>

  692. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  693. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>

  694. <span class="go">False</span>

  695. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  696. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>

  697. <span class="go">True</span>

  698. </pre></div>

  699. </div>

  700. </dd></dl>

  701. 

  702. <dl class="py attribute">

  703. <dt class="sig sig-object py" id="unittest.mock.Mock.call_count">

  704. <span class="sig-name descname"><span class="pre">call_count</span></span><a class="headerlink" href="#unittest.mock.Mock.call_count" title="Link to this definition">¶</a></dt>

  705. <dd><p>An integer telling you how many times the mock object has been called:</p>

  706. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  707. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_count</span>

  708. <span class="go">0</span>

  709. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  710. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  711. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_count</span>

  712. <span class="go">2</span>

  713. </pre></div>

  714. </div>

  715. </dd></dl>

  716. 

  717. <dl class="py attribute">

  718. <dt class="sig sig-object py" id="unittest.mock.Mock.return_value">

  719. <span class="sig-name descname"><span class="pre">return_value</span></span><a class="headerlink" href="#unittest.mock.Mock.return_value" title="Link to this definition">¶</a></dt>

  720. <dd><p>Set this to configure the value returned by calling the mock:</p>

  721. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  722. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s1">&#39;fish&#39;</span>

  723. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  724. <span class="go">&#39;fish&#39;</span>

  725. </pre></div>

  726. </div>

  727. <p>The default return value is a mock object and you can configure it in

  728. the normal way:</p>

  729. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  730. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">return_value</span><span class="o">.</span><span class="n">attribute</span> <span class="o">=</span> <span class="n">sentinel</span><span class="o">.</span><span class="n">Attribute</span>

  731. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">return_value</span><span class="p">()</span>

  732. <span class="go">&lt;Mock name=&#39;mock()()&#39; id=&#39;...&#39;&gt;</span>

  733. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">return_value</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">()</span>

  734. </pre></div>

  735. </div>

  736. <p><a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a> can also be set in the constructor:</p>

  737. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  738. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">return_value</span>

  739. <span class="go">3</span>

  740. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  741. <span class="go">3</span>

  742. </pre></div>

  743. </div>

  744. </dd></dl>

  745. 

  746. <dl class="py attribute">

  747. <dt class="sig sig-object py" id="unittest.mock.Mock.side_effect">

  748. <span class="sig-name descname"><span class="pre">side_effect</span></span><a class="headerlink" href="#unittest.mock.Mock.side_effect" title="Link to this definition">¶</a></dt>

  749. <dd><p>This can either be a function to be called when the mock is called,

  750. an iterable or an exception (class or instance) to be raised.</p>

  751. <p>If you pass in a function it will be called with same arguments as the

  752. mock and unless the function returns the <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a> singleton the

  753. call to the mock will then return whatever the function returns. If the

  754. function returns <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a> then the mock will return its normal

  755. value (from the <a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a>).</p>

  756. <p>If you pass in an iterable, it is used to retrieve an iterator which

  757. must yield a value on every call.  This value can either be an exception

  758. instance to be raised, or a value to be returned from the call to the

  759. mock (<a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a> handling is identical to the function case).</p>

  760. <p>An example of a mock that raises an exception (to test exception

  761. handling of an API):</p>

  762. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  763. <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="ne">Exception</span><span class="p">(</span><span class="s1">&#39;Boom!&#39;</span><span class="p">)</span>

  764. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  765. <span class="gt">Traceback (most recent call last):</span>

  766. <span class="w">  </span><span class="c">...</span>

  767. <span class="gr">Exception</span>: <span class="n">Boom!</span>

  768. </pre></div>

  769. </div>

  770. <p>Using <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> to return a sequence of values:</p>

  771. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  772. <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">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span>

  773. <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>

  774. <span class="go">(3, 2, 1)</span>

  775. </pre></div>

  776. </div>

  777. <p>Using a callable:</p>

  778. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  779. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">side_effect</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  780. <span class="gp">... </span>    <span class="k">return</span> <span class="n">DEFAULT</span>

  781. <span class="gp">...</span>

  782. <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>

  783. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  784. <span class="go">3</span>

  785. </pre></div>

  786. </div>

  787. <p><a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> can be set in the constructor. Here’s an example that

  788. adds one to the value the mock is called with and returns it:</p>

  789. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">side_effect</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">value</span><span class="p">:</span> <span class="n">value</span> <span class="o">+</span> <span class="mi">1</span>

  790. <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="n">side_effect</span><span class="p">)</span>

  791. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>

  792. <span class="go">4</span>

  793. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="o">-</span><span class="mi">8</span><span class="p">)</span>

  794. <span class="go">-7</span>

  795. </pre></div>

  796. </div>

  797. <p>Setting <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> to <code class="docutils literal notranslate"><span class="pre">None</span></code> clears it:</p>

  798. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="ne">KeyError</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  799. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  800. <span class="gt">Traceback (most recent call last):</span>

  801. <span class="w"> </span><span class="c">...</span>

  802. <span class="gr">KeyError</span>

  803. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="kc">None</span>

  804. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  805. <span class="go">3</span>

  806. </pre></div>

  807. </div>

  808. </dd></dl>

  809. 

  810. <dl class="py attribute">

  811. <dt class="sig sig-object py" id="unittest.mock.Mock.call_args">

  812. <span class="sig-name descname"><span class="pre">call_args</span></span><a class="headerlink" href="#unittest.mock.Mock.call_args" title="Link to this definition">¶</a></dt>

  813. <dd><p>This is either <code class="docutils literal notranslate"><span class="pre">None</span></code> (if the mock hasn’t been called), or the

  814. arguments that the mock was last called with. This will be in the

  815. form of a tuple: the first member, which can also be accessed through

  816. the <code class="docutils literal notranslate"><span class="pre">args</span></code> property, is any ordered arguments the mock was

  817. called with (or an empty tuple) and the second member, which can

  818. also be accessed through the <code class="docutils literal notranslate"><span class="pre">kwargs</span></code> property, is any keyword

  819. arguments (or an empty dictionary).</p>

  820. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  821. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span><span class="p">)</span>

  822. <span class="go">None</span>

  823. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  824. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span>

  825. <span class="go">call()</span>

  826. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span> <span class="o">==</span> <span class="p">()</span>

  827. <span class="go">True</span>

  828. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span>

  829. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span>

  830. <span class="go">call(3, 4)</span>

  831. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span> <span class="o">==</span> <span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">),)</span>

  832. <span class="go">True</span>

  833. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span><span class="o">.</span><span class="n">args</span>

  834. <span class="go">(3, 4)</span>

  835. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span><span class="o">.</span><span class="n">kwargs</span>

  836. <span class="go">{}</span>

  837. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s1">&#39;fish&#39;</span><span class="p">,</span> <span class="nb">next</span><span class="o">=</span><span class="s1">&#39;w00t!&#39;</span><span class="p">)</span>

  838. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span>

  839. <span class="go">call(3, 4, 5, key=&#39;fish&#39;, next=&#39;w00t!&#39;)</span>

  840. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span><span class="o">.</span><span class="n">args</span>

  841. <span class="go">(3, 4, 5)</span>

  842. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args</span><span class="o">.</span><span class="n">kwargs</span>

  843. <span class="go">{&#39;key&#39;: &#39;fish&#39;, &#39;next&#39;: &#39;w00t!&#39;}</span>

  844. </pre></div>

  845. </div>

  846. <p><a class="reference internal" href="#unittest.mock.Mock.call_args" title="unittest.mock.Mock.call_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args</span></code></a>, along with members of the lists <a class="reference internal" href="#unittest.mock.Mock.call_args_list" title="unittest.mock.Mock.call_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args_list</span></code></a>,

  847. <a class="reference internal" href="#unittest.mock.Mock.method_calls" title="unittest.mock.Mock.method_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">method_calls</span></code></a> and <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> are <a class="reference internal" href="#unittest.mock.call" title="unittest.mock.call"><code class="xref py py-data docutils literal notranslate"><span class="pre">call</span></code></a> objects.

  848. These are tuples, so they can be unpacked to get at the individual

  849. arguments and make more complex assertions. See

  850. <a class="reference internal" href="#calls-as-tuples"><span class="std std-ref">calls as tuples</span></a>.</p>

  851. <div class="versionchanged">

  852. <p><span class="versionmodified changed">Changed in version 3.8: </span>Added <code class="docutils literal notranslate"><span class="pre">args</span></code> and <code class="docutils literal notranslate"><span class="pre">kwargs</span></code> properties.</p>

  853. </div>

  854. </dd></dl>

  855. 

  856. <dl class="py attribute">

  857. <dt class="sig sig-object py" id="unittest.mock.Mock.call_args_list">

  858. <span class="sig-name descname"><span class="pre">call_args_list</span></span><a class="headerlink" href="#unittest.mock.Mock.call_args_list" title="Link to this definition">¶</a></dt>

  859. <dd><p>This is a list of all the calls made to the mock object in sequence

  860. (so the length of the list is the number of times it has been

  861. called). Before any calls have been made it is an empty list. The

  862. <a class="reference internal" href="#unittest.mock.call" title="unittest.mock.call"><code class="xref py py-data docutils literal notranslate"><span class="pre">call</span></code></a> object can be used for conveniently constructing lists of

  863. calls to compare with <a class="reference internal" href="#unittest.mock.Mock.call_args_list" title="unittest.mock.Mock.call_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args_list</span></code></a>.</p>

  864. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  865. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>

  866. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span>

  867. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s1">&#39;fish&#39;</span><span class="p">,</span> <span class="nb">next</span><span class="o">=</span><span class="s1">&#39;w00t!&#39;</span><span class="p">)</span>

  868. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args_list</span>

  869. <span class="go">[call(), call(3, 4), call(key=&#39;fish&#39;, next=&#39;w00t!&#39;)]</span>

  870. <span class="gp">&gt;&gt;&gt; </span><span class="n">expected</span> <span class="o">=</span> <span class="p">[(),</span> <span class="p">((</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">),),</span> <span class="p">({</span><span class="s1">&#39;key&#39;</span><span class="p">:</span> <span class="s1">&#39;fish&#39;</span><span class="p">,</span> <span class="s1">&#39;next&#39;</span><span class="p">:</span> <span class="s1">&#39;w00t!&#39;</span><span class="p">},)]</span>

  871. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">call_args_list</span> <span class="o">==</span> <span class="n">expected</span>

  872. <span class="go">True</span>

  873. </pre></div>

  874. </div>

  875. <p>Members of <a class="reference internal" href="#unittest.mock.Mock.call_args_list" title="unittest.mock.Mock.call_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args_list</span></code></a> are <a class="reference internal" href="#unittest.mock.call" title="unittest.mock.call"><code class="xref py py-data docutils literal notranslate"><span class="pre">call</span></code></a> objects. These can be

  876. unpacked as tuples to get at the individual arguments. See

  877. <a class="reference internal" href="#calls-as-tuples"><span class="std std-ref">calls as tuples</span></a>.</p>

  878. </dd></dl>

  879. 

  880. <dl class="py attribute">

  881. <dt class="sig sig-object py" id="unittest.mock.Mock.method_calls">

  882. <span class="sig-name descname"><span class="pre">method_calls</span></span><a class="headerlink" href="#unittest.mock.Mock.method_calls" title="Link to this definition">¶</a></dt>

  883. <dd><p>As well as tracking calls to themselves, mocks also track calls to

  884. methods and attributes, and <em>their</em> methods and attributes:</p>

  885. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  886. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  887. <span class="go">&lt;Mock name=&#39;mock.method()&#39; id=&#39;...&#39;&gt;</span>

  888. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">property</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">attribute</span><span class="p">()</span>

  889. <span class="go">&lt;Mock name=&#39;mock.property.method.attribute()&#39; id=&#39;...&#39;&gt;</span>

  890. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method_calls</span>

  891. <span class="go">[call.method(), call.property.method.attribute()]</span>

  892. </pre></div>

  893. </div>

  894. <p>Members of <a class="reference internal" href="#unittest.mock.Mock.method_calls" title="unittest.mock.Mock.method_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">method_calls</span></code></a> are <a class="reference internal" href="#unittest.mock.call" title="unittest.mock.call"><code class="xref py py-data docutils literal notranslate"><span class="pre">call</span></code></a> objects. These can be

  895. unpacked as tuples to get at the individual arguments. See

  896. <a class="reference internal" href="#calls-as-tuples"><span class="std std-ref">calls as tuples</span></a>.</p>

  897. </dd></dl>

  898. 

  899. <dl class="py attribute">

  900. <dt class="sig sig-object py" id="unittest.mock.Mock.mock_calls">

  901. <span class="sig-name descname"><span class="pre">mock_calls</span></span><a class="headerlink" href="#unittest.mock.Mock.mock_calls" title="Link to this definition">¶</a></dt>

  902. <dd><p><a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> records <em>all</em> calls to the mock object, its methods,

  903. magic methods <em>and</em> return value mocks.</p>

  904. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  905. <span class="gp">&gt;&gt;&gt; </span><span class="n">result</span> <span class="o">=</span> <span class="n">mock</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>

  906. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">first</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  907. <span class="go">&lt;MagicMock name=&#39;mock.first()&#39; id=&#39;...&#39;&gt;</span>

  908. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">second</span><span class="p">()</span>

  909. <span class="go">&lt;MagicMock name=&#39;mock.second()&#39; id=&#39;...&#39;&gt;</span>

  910. <span class="gp">&gt;&gt;&gt; </span><span class="nb">int</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  911. <span class="go">1</span>

  912. <span class="gp">&gt;&gt;&gt; </span><span class="n">result</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  913. <span class="go">&lt;MagicMock name=&#39;mock()()&#39; id=&#39;...&#39;&gt;</span>

  914. <span class="gp">&gt;&gt;&gt; </span><span class="n">expected</span> <span class="o">=</span> <span class="p">[</span><span class="n">call</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span> <span class="n">call</span><span class="o">.</span><span class="n">first</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">3</span><span class="p">),</span> <span class="n">call</span><span class="o">.</span><span class="n">second</span><span class="p">(),</span>

  915. <span class="gp">... </span><span class="n">call</span><span class="o">.</span><span class="fm">__int__</span><span class="p">(),</span> <span class="n">call</span><span class="p">()(</span><span class="mi">1</span><span class="p">)]</span>

  916. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">mock_calls</span> <span class="o">==</span> <span class="n">expected</span>

  917. <span class="go">True</span>

  918. </pre></div>

  919. </div>

  920. <p>Members of <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> are <a class="reference internal" href="#unittest.mock.call" title="unittest.mock.call"><code class="xref py py-data docutils literal notranslate"><span class="pre">call</span></code></a> objects. These can be

  921. unpacked as tuples to get at the individual arguments. See

  922. <a class="reference internal" href="#calls-as-tuples"><span class="std std-ref">calls as tuples</span></a>.</p>

  923. <div class="admonition note">

  924. <p class="admonition-title">Note</p>

  925. <p>The way <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> are recorded means that where nested

  926. calls are made, the parameters of ancestor calls are not recorded

  927. and so will always compare equal:</p>

  928. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  929. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">top</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span><span class="o">.</span><span class="n">bottom</span><span class="p">()</span>

  930. <span class="go">&lt;MagicMock name=&#39;mock.top().bottom()&#39; id=&#39;...&#39;&gt;</span>

  931. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">mock_calls</span>

  932. <span class="go">[call.top(a=3), call.top().bottom()]</span>

  933. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">mock_calls</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="n">call</span><span class="o">.</span><span class="n">top</span><span class="p">(</span><span class="n">a</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">bottom</span><span class="p">()</span>

  934. <span class="go">True</span>

  935. </pre></div>

  936. </div>

  937. </div>

  938. </dd></dl>

  939. 

  940. <dl class="py attribute">

  941. <dt class="sig sig-object py" id="unittest.mock.Mock.__class__">

  942. <span class="sig-name descname"><span class="pre">__class__</span></span><a class="headerlink" href="#unittest.mock.Mock.__class__" title="Link to this definition">¶</a></dt>

  943. <dd><p>Normally the <a class="reference internal" href="#unittest.mock.Mock.__class__" title="unittest.mock.Mock.__class__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__class__</span></code></a> attribute of an object will return its type.

  944. For a mock object with a <code class="xref py py-attr docutils literal notranslate"><span class="pre">spec</span></code>, <code class="docutils literal notranslate"><span class="pre">__class__</span></code> returns the spec class

  945. instead. This allows mock objects to pass <a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> tests for the

  946. object they are replacing / masquerading as:</p>

  947. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">spec</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  948. <span class="gp">&gt;&gt;&gt; </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>

  949. <span class="go">True</span>

  950. </pre></div>

  951. </div>

  952. <p><a class="reference internal" href="#unittest.mock.Mock.__class__" title="unittest.mock.Mock.__class__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__class__</span></code></a> is assignable to, this allows a mock to pass an

  953. <a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> check without forcing you to use a spec:</p>

  954. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  955. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="vm">__class__</span> <span class="o">=</span> <span class="nb">dict</span>

  956. <span class="gp">&gt;&gt;&gt; </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="nb">dict</span><span class="p">)</span>

  957. <span class="go">True</span>

  958. </pre></div>

  959. </div>

  960. </dd></dl>

  961. 

  962. </dd></dl>

  963. 

  964. <dl class="py class">

  965. <dt class="sig sig-object py" id="unittest.mock.NonCallableMock">

  966. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">NonCallableMock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">spec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wraps</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec_set</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.NonCallableMock" title="Link to this definition">¶</a></dt>

  967. <dd><p>A non-callable version of <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a>. The constructor parameters have the same

  968. meaning of <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a>, with the exception of <em>return_value</em> and <em>side_effect</em>

  969. which have no meaning on a non-callable mock.</p>

  970. </dd></dl>

  971. 

  972. <p>Mock objects that use a class or an instance as a <code class="xref py py-attr docutils literal notranslate"><span class="pre">spec</span></code> or

  973. <code class="xref py py-attr docutils literal notranslate"><span class="pre">spec_set</span></code> are able to pass <a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a> tests:</p>

  974. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">spec</span><span class="o">=</span><span class="n">SomeClass</span><span class="p">)</span>

  975. <span class="gp">&gt;&gt;&gt; </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="n">SomeClass</span><span class="p">)</span>

  976. <span class="go">True</span>

  977. <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">spec_set</span><span class="o">=</span><span class="n">SomeClass</span><span class="p">())</span>

  978. <span class="gp">&gt;&gt;&gt; </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="n">SomeClass</span><span class="p">)</span>

  979. <span class="go">True</span>

  980. </pre></div>

  981. </div>

  982. <p>The <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> classes have support for mocking magic methods. See <a class="reference internal" href="#magic-methods"><span class="std std-ref">magic

  983. methods</span></a> for the full details.</p>

  984. <p>The mock classes and the <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> decorators all take arbitrary keyword

  985. arguments for configuration. For the <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> decorators the keywords are

  986. passed to the constructor of the mock being created. The keyword arguments

  987. are for configuring attributes of the mock:</p>

  988. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">attribute</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="s1">&#39;fish&#39;</span><span class="p">)</span>

  989. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">attribute</span>

  990. <span class="go">3</span>

  991. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">other</span>

  992. <span class="go">&#39;fish&#39;</span>

  993. </pre></div>

  994. </div>

  995. <p>The return value and side effect of child mocks can be set in the same way,

  996. using dotted notation. As you can’t use dotted names directly in a call you

  997. have to create a dictionary and unpack it using <code class="docutils literal notranslate"><span class="pre">**</span></code>:</p>

  998. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">attrs</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;method.return_value&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s1">&#39;other.side_effect&#39;</span><span class="p">:</span> <span class="ne">KeyError</span><span class="p">}</span>

  999. <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">some_attribute</span><span class="o">=</span><span class="s1">&#39;eggs&#39;</span><span class="p">,</span> <span class="o">**</span><span class="n">attrs</span><span class="p">)</span>

  1000. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">some_attribute</span>

  1001. <span class="go">&#39;eggs&#39;</span>

  1002. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  1003. <span class="go">3</span>

  1004. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">other</span><span class="p">()</span>

  1005. <span class="gt">Traceback (most recent call last):</span>

  1006. <span class="w">  </span><span class="c">...</span>

  1007. <span class="gr">KeyError</span>

  1008. </pre></div>

  1009. </div>

  1010. <p>A callable mock which was created with a <em>spec</em> (or a <em>spec_set</em>) will

  1011. introspect the specification object’s signature when matching calls to

  1012. the mock.  Therefore, it can match the actual call’s arguments regardless

  1013. of whether they were passed positionally or by name:</p>

  1014. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">):</span> <span class="k">pass</span>

  1015. <span class="gp">...</span>

  1016. <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">spec</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>

  1017. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">c</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  1018. <span class="go">&lt;Mock name=&#39;mock()&#39; id=&#39;140161580456576&#39;&gt;</span>

  1019. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>

  1020. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">c</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  1021. </pre></div>

  1022. </div>

  1023. <p>This applies to <a class="reference internal" href="#unittest.mock.Mock.assert_called_with" title="unittest.mock.Mock.assert_called_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_with()</span></code></a>,

  1024. <a class="reference internal" href="#unittest.mock.Mock.assert_called_once_with" title="unittest.mock.Mock.assert_called_once_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_once_with()</span></code></a>, <a class="reference internal" href="#unittest.mock.Mock.assert_has_calls" title="unittest.mock.Mock.assert_has_calls"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_has_calls()</span></code></a> and

  1025. <a class="reference internal" href="#unittest.mock.Mock.assert_any_call" title="unittest.mock.Mock.assert_any_call"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_any_call()</span></code></a>.  When <a class="reference internal" href="#auto-speccing"><span class="std std-ref">Autospeccing</span></a>, it will also

  1026. apply to method calls on the mock object.</p>

  1027. <div class="versionchanged">

  1028. <p><span class="versionmodified changed">Changed in version 3.4: </span>Added signature introspection on specced and autospecced mock objects.</p>

  1029. </div>

  1030. <dl class="py class">

  1031. <dt class="sig sig-object py" id="unittest.mock.PropertyMock">

  1032. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">PropertyMock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.PropertyMock" title="Link to this definition">¶</a></dt>

  1033. <dd><p>A mock intended to be used as a <a class="reference internal" href="functions.html#property" title="property"><code class="xref py py-class docutils literal notranslate"><span class="pre">property</span></code></a>, or other

  1034. <a class="reference internal" href="../glossary.html#term-descriptor"><span class="xref std std-term">descriptor</span></a>, on a class. <a class="reference internal" href="#unittest.mock.PropertyMock" title="unittest.mock.PropertyMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">PropertyMock</span></code></a> provides

  1035. <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__get__()</span></code></a> and <a class="reference internal" href="../reference/datamodel.html#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__set__()</span></code></a> methods

  1036. so you can specify a return value when it is fetched.</p>

  1037. <p>Fetching a <a class="reference internal" href="#unittest.mock.PropertyMock" title="unittest.mock.PropertyMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">PropertyMock</span></code></a> instance from an object calls the mock, with

  1038. no args. Setting it calls the mock with the value being set.</p>

  1039. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Foo</span><span class="p">:</span>

  1040. <span class="gp">... </span>    <span class="nd">@property</span>

  1041. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1042. <span class="gp">... </span>        <span class="k">return</span> <span class="s1">&#39;something&#39;</span>

  1043. <span class="gp">... </span>    <span class="nd">@foo</span><span class="o">.</span><span class="n">setter</span>

  1044. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>

  1045. <span class="gp">... </span>        <span class="k">pass</span>

  1046. <span class="gp">...</span>

  1047. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.Foo.foo&#39;</span><span class="p">,</span> <span class="n">new_callable</span><span class="o">=</span><span class="n">PropertyMock</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_foo</span><span class="p">:</span>

  1048. <span class="gp">... </span>    <span class="n">mock_foo</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s1">&#39;mockity-mock&#39;</span>

  1049. <span class="gp">... </span>    <span class="n">this_foo</span> <span class="o">=</span> <span class="n">Foo</span><span class="p">()</span>

  1050. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">this_foo</span><span class="o">.</span><span class="n">foo</span><span class="p">)</span>

  1051. <span class="gp">... </span>    <span class="n">this_foo</span><span class="o">.</span><span class="n">foo</span> <span class="o">=</span> <span class="mi">6</span>

  1052. <span class="gp">...</span>

  1053. <span class="go">mockity-mock</span>

  1054. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_foo</span><span class="o">.</span><span class="n">mock_calls</span>

  1055. <span class="go">[call(), call(6)]</span>

  1056. </pre></div>

  1057. </div>

  1058. </dd></dl>

  1059. 

  1060. <p>Because of the way mock attributes are stored you can’t directly attach a

  1061. <a class="reference internal" href="#unittest.mock.PropertyMock" title="unittest.mock.PropertyMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">PropertyMock</span></code></a> to a mock object. Instead you can attach it to the mock type

  1062. object:</p>

  1063. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>

  1064. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">PropertyMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>

  1065. <span class="gp">&gt;&gt;&gt; </span><span class="nb">type</span><span class="p">(</span><span class="n">m</span><span class="p">)</span><span class="o">.</span><span class="n">foo</span> <span class="o">=</span> <span class="n">p</span>

  1066. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">foo</span>

  1067. <span class="go">3</span>

  1068. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">()</span>

  1069. </pre></div>

  1070. </div>

  1071. <dl class="py class">

  1072. <dt class="sig sig-object py" id="unittest.mock.AsyncMock">

  1073. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">AsyncMock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">spec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">side_effect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">wraps</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec_set</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">unsafe</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock" title="Link to this definition">¶</a></dt>

  1074. <dd><p>An asynchronous version of <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a>. The <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a> object will

  1075. behave so the object is recognized as an async function, and the result of a

  1076. call is an awaitable.</p>

  1077. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1078. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">iscoroutinefunction</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  1079. <span class="go">True</span>

  1080. <span class="gp">&gt;&gt;&gt; </span><span class="n">inspect</span><span class="o">.</span><span class="n">isawaitable</span><span class="p">(</span><span class="n">mock</span><span class="p">())</span>  

  1081. <span class="go">True</span>

  1082. </pre></div>

  1083. </div>

  1084. <p>The result of <code class="docutils literal notranslate"><span class="pre">mock()</span></code> is an async function which will have the outcome

  1085. of <code class="docutils literal notranslate"><span class="pre">side_effect</span></code> or <code class="docutils literal notranslate"><span class="pre">return_value</span></code> after it has been awaited:</p>

  1086. <ul class="simple">

  1087. <li><p>if <code class="docutils literal notranslate"><span class="pre">side_effect</span></code> is a function, the async function will return the

  1088. result of that function,</p></li>

  1089. <li><p>if <code class="docutils literal notranslate"><span class="pre">side_effect</span></code> is an exception, the async function will raise the

  1090. exception,</p></li>

  1091. <li><p>if <code class="docutils literal notranslate"><span class="pre">side_effect</span></code> is an iterable, the async function will return the

  1092. next value of the iterable, however, if the sequence of result is

  1093. exhausted, <code class="docutils literal notranslate"><span class="pre">StopAsyncIteration</span></code> is raised immediately,</p></li>

  1094. <li><p>if <code class="docutils literal notranslate"><span class="pre">side_effect</span></code> is not defined, the async function will return the

  1095. value defined by <code class="docutils literal notranslate"><span class="pre">return_value</span></code>, hence, by default, the async function

  1096. returns a new <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a> object.</p></li>

  1097. </ul>

  1098. <p>Setting the <em>spec</em> of a <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> or <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> to an async function

  1099. will result in a coroutine object being returned after calling.</p>

  1100. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">async_func</span><span class="p">():</span> <span class="k">pass</span>

  1101. <span class="gp">...</span>

  1102. <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><span class="n">async_func</span><span class="p">)</span>

  1103. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span>

  1104. <span class="go">&lt;MagicMock spec=&#39;function&#39; id=&#39;...&#39;&gt;</span>

  1105. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">()</span>  

  1106. <span class="go">&lt;coroutine object AsyncMockMixin._mock_call at ...&gt;</span>

  1107. </pre></div>

  1108. </div>

  1109. <p>Setting the <em>spec</em> of a <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a>, <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a>, or <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a>

  1110. to a class with asynchronous and synchronous functions will automatically

  1111. detect the synchronous functions and set them as <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> (if the

  1112. parent mock is <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a> or <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a>) or <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> (if

  1113. the parent mock is <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a>). All asynchronous functions will be

  1114. <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a>.</p>

  1115. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">ExampleClass</span><span class="p">:</span>

  1116. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">sync_foo</span><span class="p">():</span>

  1117. <span class="gp">... </span>        <span class="k">pass</span>

  1118. <span class="gp">... </span>    <span class="k">async</span> <span class="k">def</span> <span class="nf">async_foo</span><span class="p">():</span>

  1119. <span class="gp">... </span>        <span class="k">pass</span>

  1120. <span class="gp">...</span>

  1121. <span class="gp">&gt;&gt;&gt; </span><span class="n">a_mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">(</span><span class="n">ExampleClass</span><span class="p">)</span>

  1122. <span class="gp">&gt;&gt;&gt; </span><span class="n">a_mock</span><span class="o">.</span><span class="n">sync_foo</span>

  1123. <span class="go">&lt;MagicMock name=&#39;mock.sync_foo&#39; id=&#39;...&#39;&gt;</span>

  1124. <span class="gp">&gt;&gt;&gt; </span><span class="n">a_mock</span><span class="o">.</span><span class="n">async_foo</span>

  1125. <span class="go">&lt;AsyncMock name=&#39;mock.async_foo&#39; id=&#39;...&#39;&gt;</span>

  1126. <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">ExampleClass</span><span class="p">)</span>

  1127. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">sync_foo</span>

  1128. <span class="go">&lt;Mock name=&#39;mock.sync_foo&#39; id=&#39;...&#39;&gt;</span>

  1129. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">async_foo</span>

  1130. <span class="go">&lt;AsyncMock name=&#39;mock.async_foo&#39; id=&#39;...&#39;&gt;</span>

  1131. </pre></div>

  1132. </div>

  1133. <div class="versionadded">

  1134. <p><span class="versionmodified added">New in version 3.8.</span></p>

  1135. </div>

  1136. <dl class="py method">

  1137. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.assert_awaited">

  1138. <span class="sig-name descname"><span class="pre">assert_awaited</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock.assert_awaited" title="Link to this definition">¶</a></dt>

  1139. <dd><p>Assert that the mock was awaited at least once. Note that this is separate

  1140. from the object having been called, the <code class="docutils literal notranslate"><span class="pre">await</span></code> keyword must be used:</p>

  1141. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1142. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">(</span><span class="n">coroutine_mock</span><span class="p">):</span>

  1143. <span class="gp">... </span>    <span class="k">await</span> <span class="n">coroutine_mock</span>

  1144. <span class="gp">...</span>

  1145. <span class="gp">&gt;&gt;&gt; </span><span class="n">coroutine_mock</span> <span class="o">=</span> <span class="n">mock</span><span class="p">()</span>

  1146. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">called</span>

  1147. <span class="go">True</span>

  1148. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_awaited</span><span class="p">()</span>

  1149. <span class="gt">Traceback (most recent call last):</span>

  1150. <span class="c">...</span>

  1151. <span class="gr">AssertionError</span>: <span class="n">Expected mock to have been awaited.</span>

  1152. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="n">coroutine_mock</span><span class="p">))</span>

  1153. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_awaited</span><span class="p">()</span>

  1154. </pre></div>

  1155. </div>

  1156. </dd></dl>

  1157. 

  1158. <dl class="py method">

  1159. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.assert_awaited_once">

  1160. <span class="sig-name descname"><span class="pre">assert_awaited_once</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock.assert_awaited_once" title="Link to this definition">¶</a></dt>

  1161. <dd><p>Assert that the mock was awaited exactly once.</p>

  1162. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1163. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  1164. <span class="gp">... </span>    <span class="k">await</span> <span class="n">mock</span><span class="p">()</span>

  1165. <span class="gp">...</span>

  1166. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>

  1167. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_awaited_once</span><span class="p">()</span>

  1168. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>

  1169. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">assert_awaited_once</span><span class="p">()</span>

  1170. <span class="gt">Traceback (most recent call last):</span>

  1171. <span class="c">...</span>

  1172. <span class="gr">AssertionError</span>: <span class="n">Expected mock to have been awaited once. Awaited 2 times.</span>

  1173. </pre></div>

  1174. </div>

  1175. </dd></dl>

  1176. 

  1177. <dl class="py method">

  1178. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.assert_awaited_with">

  1179. <span class="sig-name descname"><span class="pre">assert_awaited_with</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock.assert_awaited_with" title="Link to this definition">¶</a></dt>

  1180. <dd><p>Assert that the last await was with the specified arguments.</p>

  1181. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1182. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1183. <span class="gp">... </span>    <span class="k">await</span> <span class="n">mock</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  1184. <span class="gp">...</span>

  1185. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">))</span>

  1186. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_awaited_with</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1187. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_awaited_with</span><span class="p">(</span><span class="s1">&#39;other&#39;</span><span class="p">)</span>

  1188. <span class="gt">Traceback (most recent call last):</span>

  1189. <span class="c">...</span>

  1190. <span class="gr">AssertionError</span>: <span class="n">expected call not found.</span>

  1191. <span class="x">Expected: mock(&#39;other&#39;)</span>

  1192. <span class="x">Actual: mock(&#39;foo&#39;, bar=&#39;bar&#39;)</span>

  1193. </pre></div>

  1194. </div>

  1195. </dd></dl>

  1196. 

  1197. <dl class="py method">

  1198. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.assert_awaited_once_with">

  1199. <span class="sig-name descname"><span class="pre">assert_awaited_once_with</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock.assert_awaited_once_with" title="Link to this definition">¶</a></dt>

  1200. <dd><p>Assert that the mock was awaited exactly once and with the specified

  1201. arguments.</p>

  1202. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1203. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1204. <span class="gp">... </span>    <span class="k">await</span> <span class="n">mock</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  1205. <span class="gp">...</span>

  1206. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">))</span>

  1207. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_awaited_once_with</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1208. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">))</span>

  1209. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_awaited_once_with</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1210. <span class="gt">Traceback (most recent call last):</span>

  1211. <span class="c">...</span>

  1212. <span class="gr">AssertionError</span>: <span class="n">Expected mock to have been awaited once. Awaited 2 times.</span>

  1213. </pre></div>

  1214. </div>

  1215. </dd></dl>

  1216. 

  1217. <dl class="py method">

  1218. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.assert_any_await">

  1219. <span class="sig-name descname"><span class="pre">assert_any_await</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock.assert_any_await" title="Link to this definition">¶</a></dt>

  1220. <dd><p>Assert the mock has ever been awaited with the specified arguments.</p>

  1221. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1222. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1223. <span class="gp">... </span>    <span class="k">await</span> <span class="n">mock</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  1224. <span class="gp">...</span>

  1225. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">))</span>

  1226. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">))</span>

  1227. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_any_await</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  1228. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_any_await</span><span class="p">(</span><span class="s1">&#39;other&#39;</span><span class="p">)</span>

  1229. <span class="gt">Traceback (most recent call last):</span>

  1230. <span class="c">...</span>

  1231. <span class="gr">AssertionError</span>: <span class="n">mock(&#39;other&#39;) await not found</span>

  1232. </pre></div>

  1233. </div>

  1234. </dd></dl>

  1235. 

  1236. <dl class="py method">

  1237. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.assert_has_awaits">

  1238. <span class="sig-name descname"><span class="pre">assert_has_awaits</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">calls</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">any_order</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock.assert_has_awaits" title="Link to this definition">¶</a></dt>

  1239. <dd><p>Assert the mock has been awaited with the specified calls.

  1240. The <a class="reference internal" href="#unittest.mock.AsyncMock.await_args_list" title="unittest.mock.AsyncMock.await_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">await_args_list</span></code></a> list is checked for the awaits.</p>

  1241. <p>If <em>any_order</em> is false then the awaits must be

  1242. sequential. There can be extra calls before or after the

  1243. specified awaits.</p>

  1244. <p>If <em>any_order</em> is true then the awaits can be in any order, but

  1245. they must all appear in <a class="reference internal" href="#unittest.mock.AsyncMock.await_args_list" title="unittest.mock.AsyncMock.await_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">await_args_list</span></code></a>.</p>

  1246. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1247. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1248. <span class="gp">... </span>    <span class="k">await</span> <span class="n">mock</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

  1249. <span class="gp">...</span>

  1250. <span class="gp">&gt;&gt;&gt; </span><span class="n">calls</span> <span class="o">=</span> <span class="p">[</span><span class="n">call</span><span class="p">(</span><span class="s2">&quot;foo&quot;</span><span class="p">),</span> <span class="n">call</span><span class="p">(</span><span class="s2">&quot;bar&quot;</span><span class="p">)]</span>

  1251. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_has_awaits</span><span class="p">(</span><span class="n">calls</span><span class="p">)</span>

  1252. <span class="gt">Traceback (most recent call last):</span>

  1253. <span class="c">...</span>

  1254. <span class="gr">AssertionError</span>: <span class="n">Awaits not found.</span>

  1255. <span class="x">Expected: [call(&#39;foo&#39;), call(&#39;bar&#39;)]</span>

  1256. <span class="x">Actual: []</span>

  1257. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">))</span>

  1258. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">))</span>

  1259. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_has_awaits</span><span class="p">(</span><span class="n">calls</span><span class="p">)</span>

  1260. </pre></div>

  1261. </div>

  1262. </dd></dl>

  1263. 

  1264. <dl class="py method">

  1265. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.assert_not_awaited">

  1266. <span class="sig-name descname"><span class="pre">assert_not_awaited</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock.assert_not_awaited" title="Link to this definition">¶</a></dt>

  1267. <dd><p>Assert that the mock was never awaited.</p>

  1268. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1269. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_not_awaited</span><span class="p">()</span>

  1270. </pre></div>

  1271. </div>

  1272. </dd></dl>

  1273. 

  1274. <dl class="py method">

  1275. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.reset_mock">

  1276. <span class="sig-name descname"><span class="pre">reset_mock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.AsyncMock.reset_mock" title="Link to this definition">¶</a></dt>

  1277. <dd><p>See <a class="reference internal" href="#unittest.mock.Mock.reset_mock" title="unittest.mock.Mock.reset_mock"><code class="xref py py-func docutils literal notranslate"><span class="pre">Mock.reset_mock()</span></code></a>. Also sets <a class="reference internal" href="#unittest.mock.AsyncMock.await_count" title="unittest.mock.AsyncMock.await_count"><code class="xref py py-attr docutils literal notranslate"><span class="pre">await_count</span></code></a> to 0,

  1278. <a class="reference internal" href="#unittest.mock.AsyncMock.await_args" title="unittest.mock.AsyncMock.await_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">await_args</span></code></a> to None, and clears the <a class="reference internal" href="#unittest.mock.AsyncMock.await_args_list" title="unittest.mock.AsyncMock.await_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">await_args_list</span></code></a>.</p>

  1279. </dd></dl>

  1280. 

  1281. <dl class="py attribute">

  1282. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.await_count">

  1283. <span class="sig-name descname"><span class="pre">await_count</span></span><a class="headerlink" href="#unittest.mock.AsyncMock.await_count" title="Link to this definition">¶</a></dt>

  1284. <dd><p>An integer keeping track of how many times the mock object has been awaited.</p>

  1285. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1286. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">():</span>

  1287. <span class="gp">... </span>    <span class="k">await</span> <span class="n">mock</span><span class="p">()</span>

  1288. <span class="gp">...</span>

  1289. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>

  1290. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">await_count</span>

  1291. <span class="go">1</span>

  1292. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>

  1293. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">await_count</span>

  1294. <span class="go">2</span>

  1295. </pre></div>

  1296. </div>

  1297. </dd></dl>

  1298. 

  1299. <dl class="py attribute">

  1300. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.await_args">

  1301. <span class="sig-name descname"><span class="pre">await_args</span></span><a class="headerlink" href="#unittest.mock.AsyncMock.await_args" title="Link to this definition">¶</a></dt>

  1302. <dd><p>This is either <code class="docutils literal notranslate"><span class="pre">None</span></code> (if the mock hasn’t been awaited), or the arguments that

  1303. the mock was last awaited with. Functions the same as <a class="reference internal" href="#unittest.mock.Mock.call_args" title="unittest.mock.Mock.call_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Mock.call_args</span></code></a>.</p>

  1304. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1305. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>

  1306. <span class="gp">... </span>    <span class="k">await</span> <span class="n">mock</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>

  1307. <span class="gp">...</span>

  1308. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">await_args</span>

  1309. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">))</span>

  1310. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">await_args</span>

  1311. <span class="go">call(&#39;foo&#39;)</span>

  1312. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">))</span>

  1313. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">await_args</span>

  1314. <span class="go">call(&#39;bar&#39;)</span>

  1315. </pre></div>

  1316. </div>

  1317. </dd></dl>

  1318. 

  1319. <dl class="py attribute">

  1320. <dt class="sig sig-object py" id="unittest.mock.AsyncMock.await_args_list">

  1321. <span class="sig-name descname"><span class="pre">await_args_list</span></span><a class="headerlink" href="#unittest.mock.AsyncMock.await_args_list" title="Link to this definition">¶</a></dt>

  1322. <dd><p>This is a list of all the awaits made to the mock object in sequence (so the

  1323. length of the list is the number of times it has been awaited). Before any

  1324. awaits have been made it is an empty list.</p>

  1325. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>

  1326. <span class="gp">&gt;&gt;&gt; </span><span class="k">async</span> <span class="k">def</span> <span class="nf">main</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>

  1327. <span class="gp">... </span>    <span class="k">await</span> <span class="n">mock</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>

  1328. <span class="gp">...</span>

  1329. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">await_args_list</span>

  1330. <span class="go">[]</span>

  1331. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">))</span>

  1332. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">await_args_list</span>

  1333. <span class="go">[call(&#39;foo&#39;)]</span>

  1334. <span class="gp">&gt;&gt;&gt; </span><span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">))</span>

  1335. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">await_args_list</span>

  1336. <span class="go">[call(&#39;foo&#39;), call(&#39;bar&#39;)]</span>

  1337. </pre></div>

  1338. </div>

  1339. </dd></dl>

  1340. 

  1341. </dd></dl>

  1342. 

  1343. <section id="calling">

  1344. <h3>Calling<a class="headerlink" href="#calling" title="Link to this heading">¶</a></h3>

  1345. <p>Mock objects are callable. The call will return the value set as the

  1346. <a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a> attribute. The default return value is a new Mock

  1347. object; it is created the first time the return value is accessed (either

  1348. explicitly or by calling the Mock) - but it is stored and the same one

  1349. returned each time.</p>

  1350. <p>Calls made to the object will be recorded in the attributes

  1351. like <a class="reference internal" href="#unittest.mock.Mock.call_args" title="unittest.mock.Mock.call_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args</span></code></a> and <a class="reference internal" href="#unittest.mock.Mock.call_args_list" title="unittest.mock.Mock.call_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args_list</span></code></a>.</p>

  1352. <p>If <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> is set then it will be called after the call has

  1353. been recorded, so if <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code> raises an exception the call is still

  1354. recorded.</p>

  1355. <p>The simplest way to make a mock raise an exception when called is to make

  1356. <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> an exception class or instance:</p>

  1357. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="ne">IndexError</span><span class="p">)</span>

  1358. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>

  1359. <span class="gt">Traceback (most recent call last):</span>

  1360. <span class="w">  </span><span class="c">...</span>

  1361. <span class="gr">IndexError</span>

  1362. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span>

  1363. <span class="go">[call(1, 2, 3)]</span>

  1364. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="ne">KeyError</span><span class="p">(</span><span class="s1">&#39;Bang!&#39;</span><span class="p">)</span>

  1365. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="s1">&#39;two&#39;</span><span class="p">,</span> <span class="s1">&#39;three&#39;</span><span class="p">,</span> <span class="s1">&#39;four&#39;</span><span class="p">)</span>

  1366. <span class="gt">Traceback (most recent call last):</span>

  1367. <span class="w">  </span><span class="c">...</span>

  1368. <span class="gr">KeyError</span>: <span class="n">&#39;Bang!&#39;</span>

  1369. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span>

  1370. <span class="go">[call(1, 2, 3), call(&#39;two&#39;, &#39;three&#39;, &#39;four&#39;)]</span>

  1371. </pre></div>

  1372. </div>

  1373. <p>If <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code> is a function then whatever that function returns is what

  1374. calls to the mock return. The <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code> function is called with the

  1375. same arguments as the mock. This allows you to vary the return value of the

  1376. call dynamically, based on the input:</p>

  1377. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">value</span><span class="p">):</span>

  1378. <span class="gp">... </span>    <span class="k">return</span> <span class="n">value</span> <span class="o">+</span> <span class="mi">1</span>

  1379. <span class="gp">...</span>

  1380. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="n">side_effect</span><span class="p">)</span>

  1381. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  1382. <span class="go">2</span>

  1383. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>

  1384. <span class="go">3</span>

  1385. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span>

  1386. <span class="go">[call(1), call(2)]</span>

  1387. </pre></div>

  1388. </div>

  1389. <p>If you want the mock to still return the default return value (a new mock), or

  1390. any set return value, then there are two ways of doing this. Either return

  1391. <code class="xref py py-attr docutils literal notranslate"><span class="pre">mock.return_value</span></code> from inside <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code>, or return <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a>:</p>

  1392. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>

  1393. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">side_effect</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1394. <span class="gp">... </span>    <span class="k">return</span> <span class="n">m</span><span class="o">.</span><span class="n">return_value</span>

  1395. <span class="gp">...</span>

  1396. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">side_effect</span>

  1397. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="mi">3</span>

  1398. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1399. <span class="go">3</span>

  1400. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">side_effect</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1401. <span class="gp">... </span>    <span class="k">return</span> <span class="n">DEFAULT</span>

  1402. <span class="gp">...</span>

  1403. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">side_effect</span>

  1404. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1405. <span class="go">3</span>

  1406. </pre></div>

  1407. </div>

  1408. <p>To remove a <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code>, and return to the default behaviour, set the

  1409. <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code> to <code class="docutils literal notranslate"><span class="pre">None</span></code>:</p>

  1410. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span>

  1411. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">side_effect</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>

  1412. <span class="gp">... </span>    <span class="k">return</span> <span class="mi">3</span>

  1413. <span class="gp">...</span>

  1414. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="n">side_effect</span>

  1415. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1416. <span class="go">3</span>

  1417. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="kc">None</span>

  1418. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1419. <span class="go">6</span>

  1420. </pre></div>

  1421. </div>

  1422. <p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code> can also be any iterable object. Repeated calls to the mock

  1423. will return values from the iterable (until the iterable is exhausted and

  1424. a <a class="reference internal" href="exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a> is raised):</p>

  1425. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>

  1426. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1427. <span class="go">1</span>

  1428. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1429. <span class="go">2</span>

  1430. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1431. <span class="go">3</span>

  1432. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1433. <span class="gt">Traceback (most recent call last):</span>

  1434. <span class="w">  </span><span class="c">...</span>

  1435. <span class="gr">StopIteration</span>

  1436. </pre></div>

  1437. </div>

  1438. <p>If any members of the iterable are exceptions they will be raised instead of

  1439. returned:</p>

  1440. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">iterable</span> <span class="o">=</span> <span class="p">(</span><span class="mi">33</span><span class="p">,</span> <span class="ne">ValueError</span><span class="p">,</span> <span class="mi">66</span><span class="p">)</span>

  1441. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">side_effect</span><span class="o">=</span><span class="n">iterable</span><span class="p">)</span>

  1442. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1443. <span class="go">33</span>

  1444. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1445. <span class="gt">Traceback (most recent call last):</span>

  1446. <span class="w"> </span><span class="c">...</span>

  1447. <span class="gr">ValueError</span>

  1448. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  1449. <span class="go">66</span>

  1450. </pre></div>

  1451. </div>

  1452. </section>

  1453. <section id="deleting-attributes">

  1454. <span id="id2"></span><h3>Deleting Attributes<a class="headerlink" href="#deleting-attributes" title="Link to this heading">¶</a></h3>

  1455. <p>Mock objects create attributes on demand. This allows them to pretend to be

  1456. objects of any type.</p>

  1457. <p>You may want a mock object to return <code class="docutils literal notranslate"><span class="pre">False</span></code> to a <a class="reference internal" href="functions.html#hasattr" title="hasattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">hasattr()</span></code></a> call, or raise an

  1458. <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> when an attribute is fetched. You can do this by providing

  1459. an object as a <code class="xref py py-attr docutils literal notranslate"><span class="pre">spec</span></code> for a mock, but that isn’t always convenient.</p>

  1460. <p>You “block” attributes by deleting them. Once deleted, accessing an attribute

  1461. will raise an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.</p>

  1462. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  1463. <span class="gp">&gt;&gt;&gt; </span><span class="nb">hasattr</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="s1">&#39;m&#39;</span><span class="p">)</span>

  1464. <span class="go">True</span>

  1465. <span class="gp">&gt;&gt;&gt; </span><span class="k">del</span> <span class="n">mock</span><span class="o">.</span><span class="n">m</span>

  1466. <span class="gp">&gt;&gt;&gt; </span><span class="nb">hasattr</span><span class="p">(</span><span class="n">mock</span><span class="p">,</span> <span class="s1">&#39;m&#39;</span><span class="p">)</span>

  1467. <span class="go">False</span>

  1468. <span class="gp">&gt;&gt;&gt; </span><span class="k">del</span> <span class="n">mock</span><span class="o">.</span><span class="n">f</span>

  1469. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">f</span>

  1470. <span class="gt">Traceback (most recent call last):</span>

  1471. <span class="w">    </span><span class="o">...</span>

  1472. <span class="gr">AttributeError</span>: <span class="n">f</span>

  1473. </pre></div>

  1474. </div>

  1475. </section>

  1476. <section id="mock-names-and-the-name-attribute">

  1477. <h3>Mock names and the name attribute<a class="headerlink" href="#mock-names-and-the-name-attribute" title="Link to this heading">¶</a></h3>

  1478. <p>Since “name” is an argument to the <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> constructor, if you want your

  1479. mock object to have a “name” attribute you can’t just pass it in at creation

  1480. time. There are two alternatives. One option is to use

  1481. <a class="reference internal" href="#unittest.mock.Mock.configure_mock" title="unittest.mock.Mock.configure_mock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">configure_mock()</span></code></a>:</p>

  1482. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><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>

  1483. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">configure_mock</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">&#39;my_name&#39;</span><span class="p">)</span>

  1484. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">name</span>

  1485. <span class="go">&#39;my_name&#39;</span>

  1486. </pre></div>

  1487. </div>

  1488. <p>A simpler option is to simply set the “name” attribute after mock creation:</p>

  1489. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><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>

  1490. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;foo&quot;</span>

  1491. </pre></div>

  1492. </div>

  1493. </section>

  1494. <section id="attaching-mocks-as-attributes">

  1495. <h3>Attaching Mocks as Attributes<a class="headerlink" href="#attaching-mocks-as-attributes" title="Link to this heading">¶</a></h3>

  1496. <p>When you attach a mock as an attribute of another mock (or as the return

  1497. value) it becomes a “child” of that mock. Calls to the child are recorded in

  1498. the <a class="reference internal" href="#unittest.mock.Mock.method_calls" title="unittest.mock.Mock.method_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">method_calls</span></code></a> and <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> attributes of the

  1499. parent. This is useful for configuring child mocks and then attaching them to

  1500. the parent, or for attaching mocks to a parent that records all calls to the

  1501. children and allows you to make assertions about the order of calls between

  1502. mocks:</p>

  1503. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parent</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>

  1504. <span class="gp">&gt;&gt;&gt; </span><span class="n">child1</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  1505. <span class="gp">&gt;&gt;&gt; </span><span class="n">child2</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  1506. <span class="gp">&gt;&gt;&gt; </span><span class="n">parent</span><span class="o">.</span><span class="n">child1</span> <span class="o">=</span> <span class="n">child1</span>

  1507. <span class="gp">&gt;&gt;&gt; </span><span class="n">parent</span><span class="o">.</span><span class="n">child2</span> <span class="o">=</span> <span class="n">child2</span>

  1508. <span class="gp">&gt;&gt;&gt; </span><span class="n">child1</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  1509. <span class="gp">&gt;&gt;&gt; </span><span class="n">child2</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>

  1510. <span class="gp">&gt;&gt;&gt; </span><span class="n">parent</span><span class="o">.</span><span class="n">mock_calls</span>

  1511. <span class="go">[call.child1(1), call.child2(2)]</span>

  1512. </pre></div>

  1513. </div>

  1514. <p>The exception to this is if the mock has a name. This allows you to prevent

  1515. the “parenting” if for some reason you don’t want it to happen.</p>

  1516. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  1517. <span class="gp">&gt;&gt;&gt; </span><span class="n">not_a_child</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">&#39;not-a-child&#39;</span><span class="p">)</span>

  1518. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">attribute</span> <span class="o">=</span> <span class="n">not_a_child</span>

  1519. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">attribute</span><span class="p">()</span>

  1520. <span class="go">&lt;MagicMock name=&#39;not-a-child()&#39; id=&#39;...&#39;&gt;</span>

  1521. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">mock_calls</span>

  1522. <span class="go">[]</span>

  1523. </pre></div>

  1524. </div>

  1525. <p>Mocks created for you by <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> are automatically given names. To

  1526. attach mocks that have names to a parent you use the <a class="reference internal" href="#unittest.mock.Mock.attach_mock" title="unittest.mock.Mock.attach_mock"><code class="xref py py-meth docutils literal notranslate"><span class="pre">attach_mock()</span></code></a>

  1527. method:</p>

  1528. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">thing1</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1529. <span class="gp">&gt;&gt;&gt; </span><span class="n">thing2</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1530. <span class="gp">&gt;&gt;&gt; </span><span class="n">parent</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>

  1531. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.thing1&#39;</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">child1</span><span class="p">:</span>

  1532. <span class="gp">... </span>    <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.thing2&#39;</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">child2</span><span class="p">:</span>

  1533. <span class="gp">... </span>        <span class="n">parent</span><span class="o">.</span><span class="n">attach_mock</span><span class="p">(</span><span class="n">child1</span><span class="p">,</span> <span class="s1">&#39;child1&#39;</span><span class="p">)</span>

  1534. <span class="gp">... </span>        <span class="n">parent</span><span class="o">.</span><span class="n">attach_mock</span><span class="p">(</span><span class="n">child2</span><span class="p">,</span> <span class="s1">&#39;child2&#39;</span><span class="p">)</span>

  1535. <span class="gp">... </span>        <span class="n">child1</span><span class="p">(</span><span class="s1">&#39;one&#39;</span><span class="p">)</span>

  1536. <span class="gp">... </span>        <span class="n">child2</span><span class="p">(</span><span class="s1">&#39;two&#39;</span><span class="p">)</span>

  1537. <span class="gp">...</span>

  1538. <span class="gp">&gt;&gt;&gt; </span><span class="n">parent</span><span class="o">.</span><span class="n">mock_calls</span>

  1539. <span class="go">[call.child1(&#39;one&#39;), call.child2(&#39;two&#39;)]</span>

  1540. </pre></div>

  1541. </div>

  1542. <aside class="footnote-list brackets">

  1543. <aside class="footnote brackets" id="id3" role="doc-footnote">

  1544. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>

  1545. <p>The only exceptions are magic methods and attributes (those that have

  1546. leading and trailing double underscores). Mock doesn’t create these but

  1547. instead raises an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>. This is because the interpreter

  1548. will often implicitly request these methods, and gets <em>very</em> confused to

  1549. get a new Mock object when it expects a magic method. If you need magic

  1550. method support see <a class="reference internal" href="#magic-methods"><span class="std std-ref">magic methods</span></a>.</p>

  1551. </aside>

  1552. </aside>

  1553. </section>

  1554. </section>

  1555. <section id="the-patchers">

  1556. <h2>The patchers<a class="headerlink" href="#the-patchers" title="Link to this heading">¶</a></h2>

  1557. <p>The patch decorators are used for patching objects only within the scope of

  1558. the function they decorate. They automatically handle the unpatching for you,

  1559. even if exceptions are raised. All of these functions can also be used in with

  1560. statements or as class decorators.</p>

  1561. <section id="patch">

  1562. <h3>patch<a class="headerlink" href="#patch" title="Link to this heading">¶</a></h3>

  1563. <div class="admonition note">

  1564. <p class="admonition-title">Note</p>

  1565. <p>The key is to do the patching in the right namespace. See the section <a class="reference internal" href="#id6">where to patch</a>.</p>

  1566. </div>

  1567. <dl class="py function">

  1568. <dt class="sig sig-object py" id="unittest.mock.patch">

  1569. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">patch</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">target</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">new</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec_set</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">autospec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">new_callable</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.patch" title="Link to this definition">¶</a></dt>

  1570. <dd><p><a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> acts as a function decorator, class decorator or a context

  1571. manager. Inside the body of the function or with statement, the <em>target</em>

  1572. is patched with a <em>new</em> object. When the function/with statement exits

  1573. the patch is undone.</p>

  1574. <p>If <em>new</em> is omitted, then the target is replaced with an

  1575. <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a> if the patched object is an async function or

  1576. a <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> otherwise.

  1577. If <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> is used as a decorator and <em>new</em> is

  1578. omitted, the created mock is passed in as an extra argument to the

  1579. decorated function. If <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> is used as a context manager the created

  1580. mock is returned by the context manager.</p>

  1581. <p><em>target</em> should be a string in the form <code class="docutils literal notranslate"><span class="pre">'package.module.ClassName'</span></code>. The

  1582. <em>target</em> is imported and the specified object replaced with the <em>new</em>

  1583. object, so the <em>target</em> must be importable from the environment you are

  1584. calling <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> from. The target is imported when the decorated function

  1585. is executed, not at decoration time.</p>

  1586. <p>The <em>spec</em> and <em>spec_set</em> keyword arguments are passed to the <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a>

  1587. if patch is creating one for you.</p>

  1588. <p>In addition you can pass <code class="docutils literal notranslate"><span class="pre">spec=True</span></code> or <code class="docutils literal notranslate"><span class="pre">spec_set=True</span></code>, which causes

  1589. patch to pass in the object being mocked as the spec/spec_set object.</p>

  1590. <p><em>new_callable</em> allows you to specify a different class, or callable object,

  1591. that will be called to create the <em>new</em> object. By default <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a>

  1592. is used for async functions and <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> for the rest.</p>

  1593. <p>A more powerful form of <em>spec</em> is <em>autospec</em>. If you set <code class="docutils literal notranslate"><span class="pre">autospec=True</span></code>

  1594. then the mock will be created with a spec from the object being replaced.

  1595. All attributes of the mock will also have the spec of the corresponding

  1596. attribute of the object being replaced. Methods and functions being mocked

  1597. will have their arguments checked and will raise a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if they are

  1598. called with the wrong signature. For mocks

  1599. replacing a class, their return value (the ‘instance’) will have the same

  1600. spec as the class. See the <a class="reference internal" href="#unittest.mock.create_autospec" title="unittest.mock.create_autospec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_autospec()</span></code></a> function and

  1601. <a class="reference internal" href="#auto-speccing"><span class="std std-ref">Autospeccing</span></a>.</p>

  1602. <p>Instead of <code class="docutils literal notranslate"><span class="pre">autospec=True</span></code> you can pass <code class="docutils literal notranslate"><span class="pre">autospec=some_object</span></code> to use an

  1603. arbitrary object as the spec instead of the one being replaced.</p>

  1604. <p>By default <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> will fail to replace attributes that don’t exist.

  1605. If you pass in <code class="docutils literal notranslate"><span class="pre">create=True</span></code>, and the attribute doesn’t exist, patch will

  1606. create the attribute for you when the patched function is called, and delete

  1607. it again after the patched function has exited. This is useful for writing

  1608. tests against attributes that your production code creates at runtime. It is

  1609. off by default because it can be dangerous. With it switched on you can

  1610. write passing tests against APIs that don’t actually exist!</p>

  1611. <div class="admonition note">

  1612. <p class="admonition-title">Note</p>

  1613. <div class="versionchanged">

  1614. <p><span class="versionmodified changed">Changed in version 3.5: </span>If you are patching builtins in a module then you don’t

  1615. need to pass <code class="docutils literal notranslate"><span class="pre">create=True</span></code>, it will be added by default.</p>

  1616. </div>

  1617. </div>

  1618. <p>Patch can be used as a <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code> class decorator. It works by

  1619. decorating each test method in the class. This reduces the boilerplate

  1620. code when your test methods share a common patchings set. <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> finds

  1621. tests by looking for method names that start with <code class="docutils literal notranslate"><span class="pre">patch.TEST_PREFIX</span></code>.

  1622. By default this is <code class="docutils literal notranslate"><span class="pre">'test'</span></code>, which matches the way <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> finds tests.

  1623. You can specify an alternative prefix by setting <code class="docutils literal notranslate"><span class="pre">patch.TEST_PREFIX</span></code>.</p>

  1624. <p>Patch can be used as a context manager, with the with statement. Here the

  1625. patching applies to the indented block after the with statement. If you

  1626. use “as” then the patched object will be bound to the name after the

  1627. “as”; very useful if <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> is creating a mock object for you.</p>

  1628. <p><a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> takes arbitrary keyword arguments. These will be passed to

  1629. <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a> if the patched object is asynchronous, to

  1630. <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> otherwise or to <em>new_callable</em> if specified.</p>

  1631. <p><code class="docutils literal notranslate"><span class="pre">patch.dict(...)</span></code>, <code class="docutils literal notranslate"><span class="pre">patch.multiple(...)</span></code> and <code class="docutils literal notranslate"><span class="pre">patch.object(...)</span></code> are

  1632. available for alternate use-cases.</p>

  1633. </dd></dl>

  1634. 

  1635. <p><a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> as function decorator, creating the mock for you and passing it into

  1636. the decorated function:</p>

  1637. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;__main__.SomeClass&#39;</span><span class="p">)</span>

  1638. <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>

  1639. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">mock_class</span> <span class="ow">is</span> <span class="n">SomeClass</span><span class="p">)</span>

  1640. <span class="gp">...</span>

  1641. <span class="gp">&gt;&gt;&gt; </span><span class="n">function</span><span class="p">(</span><span class="kc">None</span><span class="p">)</span>

  1642. <span class="go">True</span>

  1643. </pre></div>

  1644. </div>

  1645. <p>Patching a class replaces the class with a <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> <em>instance</em>. If the

  1646. class is instantiated in the code under test then it will be the

  1647. <a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a> of the mock that will be used.</p>

  1648. <p>If the class is instantiated multiple times you could use

  1649. <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> to return a new mock each time. Alternatively you

  1650. can set the <em>return_value</em> to be anything you want.</p>

  1651. <p>To configure return values on methods of <em>instances</em> on the patched class

  1652. you must do this on the <code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code>. For example:</p>

  1653. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Class</span><span class="p">:</span>

  1654. <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>

  1655. <span class="gp">... </span>        <span class="k">pass</span>

  1656. <span class="gp">...</span>

  1657. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.Class&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">MockClass</span><span class="p">:</span>

  1658. <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>

  1659. <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="s1">&#39;foo&#39;</span>

  1660. <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>

  1661. <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="s1">&#39;foo&#39;</span>

  1662. <span class="gp">...</span>

  1663. </pre></div>

  1664. </div>

  1665. <p>If you use <em>spec</em> or <em>spec_set</em> and <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> is replacing a <em>class</em>, then the

  1666. return value of the created mock will have the same spec.</p>

  1667. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Original</span> <span class="o">=</span> <span class="n">Class</span>

  1668. <span class="gp">&gt;&gt;&gt; </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.Class&#39;</span><span class="p">,</span> <span class="n">spec</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  1669. <span class="gp">&gt;&gt;&gt; </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>

  1670. <span class="gp">&gt;&gt;&gt; </span><span class="n">instance</span> <span class="o">=</span> <span class="n">MockClass</span><span class="p">()</span>

  1671. <span class="gp">&gt;&gt;&gt; </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>

  1672. <span class="gp">&gt;&gt;&gt; </span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>

  1673. </pre></div>

  1674. </div>

  1675. <p>The <em>new_callable</em> argument is useful where you want to use an alternative

  1676. class to the default <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> for the created mock. For example, if

  1677. you wanted a <a class="reference internal" href="#unittest.mock.NonCallableMock" title="unittest.mock.NonCallableMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">NonCallableMock</span></code></a> to be used:</p>

  1678. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">thing</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1679. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.thing&#39;</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>

  1680. <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>

  1681. <span class="gp">... </span>    <span class="n">thing</span><span class="p">()</span>

  1682. <span class="gp">...</span>

  1683. <span class="gt">Traceback (most recent call last):</span>

  1684. <span class="w">  </span><span class="c">...</span>

  1685. <span class="gr">TypeError</span>: <span class="n">&#39;NonCallableMock&#39; object is not callable</span>

  1686. </pre></div>

  1687. </div>

  1688. <p>Another use case might be to replace an object with an <a class="reference internal" href="io.html#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.StringIO</span></code></a> instance:</p>

  1689. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">io</span> <span class="kn">import</span> <span class="n">StringIO</span>

  1690. <span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">foo</span><span class="p">():</span>

  1691. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Something&#39;</span><span class="p">)</span>

  1692. <span class="gp">...</span>

  1693. <span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;sys.stdout&#39;</span><span class="p">,</span> <span class="n">new_callable</span><span class="o">=</span><span class="n">StringIO</span><span class="p">)</span>

  1694. <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>

  1695. <span class="gp">... </span>    <span class="n">foo</span><span class="p">()</span>

  1696. <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="s1">&#39;Something</span><span class="se">\n</span><span class="s1">&#39;</span>

  1697. <span class="gp">...</span>

  1698. <span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">()</span>

  1699. </pre></div>

  1700. </div>

  1701. <p>When <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> is creating a mock for you, it is common that the first thing

  1702. you need to do is to configure the mock. Some of that configuration can be done

  1703. in the call to patch. Any arbitrary keywords you pass into the call will be

  1704. used to set attributes on the created mock:</p>

  1705. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.thing&#39;</span><span class="p">,</span> <span class="n">first</span><span class="o">=</span><span class="s1">&#39;one&#39;</span><span class="p">,</span> <span class="n">second</span><span class="o">=</span><span class="s1">&#39;two&#39;</span><span class="p">)</span>

  1706. <span class="gp">&gt;&gt;&gt; </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>

  1707. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">first</span>

  1708. <span class="go">&#39;one&#39;</span>

  1709. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">second</span>

  1710. <span class="go">&#39;two&#39;</span>

  1711. </pre></div>

  1712. </div>

  1713. <p>As well as attributes on the created mock attributes, like the

  1714. <a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a> and <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a>, of child mocks can

  1715. also be configured. These aren’t syntactically valid to pass in directly as

  1716. keyword arguments, but a dictionary with these as keys can still be expanded

  1717. into a <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> call using <code class="docutils literal notranslate"><span class="pre">**</span></code>:</p>

  1718. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">config</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;method.return_value&#39;</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s1">&#39;other.side_effect&#39;</span><span class="p">:</span> <span class="ne">KeyError</span><span class="p">}</span>

  1719. <span class="gp">&gt;&gt;&gt; </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.thing&#39;</span><span class="p">,</span> <span class="o">**</span><span class="n">config</span><span class="p">)</span>

  1720. <span class="gp">&gt;&gt;&gt; </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>

  1721. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  1722. <span class="go">3</span>

  1723. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">other</span><span class="p">()</span>

  1724. <span class="gt">Traceback (most recent call last):</span>

  1725. <span class="w">  </span><span class="c">...</span>

  1726. <span class="gr">KeyError</span>

  1727. </pre></div>

  1728. </div>

  1729. <p>By default, attempting to patch a function in a module (or a method or an

  1730. attribute in a class) that does not exist will fail with <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>:</p>

  1731. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;sys.non_existing_attribute&#39;</span><span class="p">,</span> <span class="mi">42</span><span class="p">)</span>

  1732. <span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">():</span>

  1733. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">sys</span><span class="o">.</span><span class="n">non_existing_attribute</span> <span class="o">==</span> <span class="mi">42</span>

  1734. <span class="gp">...</span>

  1735. <span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">()</span>

  1736. <span class="gt">Traceback (most recent call last):</span>

  1737. <span class="w">  </span><span class="c">...</span>

  1738. <span class="gr">AttributeError</span>: <span class="n">&lt;module &#39;sys&#39; (built-in)&gt; does not have the attribute &#39;non_existing_attribute&#39;</span>

  1739. </pre></div>

  1740. </div>

  1741. <p>but adding <code class="docutils literal notranslate"><span class="pre">create=True</span></code> in the call to <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> will make the previous example

  1742. work as expected:</p>

  1743. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;sys.non_existing_attribute&#39;</span><span class="p">,</span> <span class="mi">42</span><span class="p">,</span> <span class="n">create</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  1744. <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>

  1745. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">sys</span><span class="o">.</span><span class="n">non_existing_attribute</span> <span class="o">==</span> <span class="mi">42</span>

  1746. <span class="gp">...</span>

  1747. <span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">()</span>

  1748. </pre></div>

  1749. </div>

  1750. <div class="versionchanged">

  1751. <p><span class="versionmodified changed">Changed in version 3.8: </span><a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> now returns an <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a> if the target is an async function.</p>

  1752. </div>

  1753. </section>

  1754. <section id="patch-object">

  1755. <h3>patch.object<a class="headerlink" href="#patch-object" title="Link to this heading">¶</a></h3>

  1756. <dl class="py function">

  1757. <dt class="sig sig-object py" id="unittest.mock.patch.object">

  1758. <span class="sig-prename descclassname"><span class="pre">patch.</span></span><span class="sig-name descname"><span class="pre">object</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">target</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attribute</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">new</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec_set</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">autospec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">new_callable</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.patch.object" title="Link to this definition">¶</a></dt>

  1759. <dd><p>patch the named member (<em>attribute</em>) on an object (<em>target</em>) with a mock

  1760. object.</p>

  1761. <p><a class="reference internal" href="#unittest.mock.patch.object" title="unittest.mock.patch.object"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.object()</span></code></a> can be used as a decorator, class decorator or a context

  1762. manager. Arguments <em>new</em>, <em>spec</em>, <em>create</em>, <em>spec_set</em>, <em>autospec</em> and

  1763. <em>new_callable</em> have the same meaning as for <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>. Like <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>,

  1764. <a class="reference internal" href="#unittest.mock.patch.object" title="unittest.mock.patch.object"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.object()</span></code></a> takes arbitrary keyword arguments for configuring the mock

  1765. object it creates.</p>

  1766. <p>When used as a class decorator <a class="reference internal" href="#unittest.mock.patch.object" title="unittest.mock.patch.object"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.object()</span></code></a> honours <code class="docutils literal notranslate"><span class="pre">patch.TEST_PREFIX</span></code>

  1767. for choosing which methods to wrap.</p>

  1768. </dd></dl>

  1769. 

  1770. <p>You can either call <a class="reference internal" href="#unittest.mock.patch.object" title="unittest.mock.patch.object"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.object()</span></code></a> with three arguments or two arguments. The

  1771. three argument form takes the object to be patched, the attribute name and the

  1772. object to replace the attribute with.</p>

  1773. <p>When calling with the two argument form you omit the replacement object, and a

  1774. mock is created for you and passed in as an extra argument to the decorated

  1775. function:</p>

  1776. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="o">.</span><span class="n">object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s1">&#39;class_method&#39;</span><span class="p">)</span>

  1777. <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>

  1778. <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>

  1779. <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>

  1780. <span class="gp">...</span>

  1781. <span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">()</span>

  1782. </pre></div>

  1783. </div>

  1784. <p><em>spec</em>, <em>create</em> and the other arguments to <a class="reference internal" href="#unittest.mock.patch.object" title="unittest.mock.patch.object"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.object()</span></code></a> have the same

  1785. meaning as they do for <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>.</p>

  1786. </section>

  1787. <section id="patch-dict">

  1788. <h3>patch.dict<a class="headerlink" href="#patch-dict" title="Link to this heading">¶</a></h3>

  1789. <dl class="py function">

  1790. <dt class="sig sig-object py" id="unittest.mock.patch.dict">

  1791. <span class="sig-prename descclassname"><span class="pre">patch.</span></span><span class="sig-name descname"><span class="pre">dict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">in_dict</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">values</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">clear</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.patch.dict" title="Link to this definition">¶</a></dt>

  1792. <dd><p>Patch a dictionary, or dictionary like object, and restore the dictionary

  1793. to its original state after the test.</p>

  1794. <p><em>in_dict</em> can be a dictionary or a mapping like container. If it is a

  1795. mapping then it must at least support getting, setting and deleting items

  1796. plus iterating over keys.</p>

  1797. <p><em>in_dict</em> can also be a string specifying the name of the dictionary, which

  1798. will then be fetched by importing it.</p>

  1799. <p><em>values</em> can be a dictionary of values to set in the dictionary. <em>values</em>

  1800. can also be an iterable of <code class="docutils literal notranslate"><span class="pre">(key,</span> <span class="pre">value)</span></code> pairs.</p>

  1801. <p>If <em>clear</em> is true then the dictionary will be cleared before the new

  1802. values are set.</p>

  1803. <p><a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> can also be called with arbitrary keyword arguments to set

  1804. values in the dictionary.</p>

  1805. <div class="versionchanged">

  1806. <p><span class="versionmodified changed">Changed in version 3.8: </span><a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> now returns the patched dictionary when used as a context

  1807. manager.</p>

  1808. </div>

  1809. </dd></dl>

  1810. 

  1811. <p><a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> can be used as a context manager, decorator or class

  1812. decorator:</p>

  1813. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">foo</span> <span class="o">=</span> <span class="p">{}</span>

  1814. <span class="gp">&gt;&gt;&gt; </span><span class="nd">@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="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">})</span>

  1815. <span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">():</span>

  1816. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{</span><span class="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">}</span>

  1817. <span class="gp">...</span>

  1818. <span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">()</span>

  1819. <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{}</span>

  1820. </pre></div>

  1821. </div>

  1822. <p>When used as a class decorator <a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> honours

  1823. <code class="docutils literal notranslate"><span class="pre">patch.TEST_PREFIX</span></code> (default to <code class="docutils literal notranslate"><span class="pre">'test'</span></code>) for choosing which methods to wrap:</p>

  1824. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">os</span>

  1825. <span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">unittest</span>

  1826. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">patch</span>

  1827. <span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="s1">&#39;os.environ&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">})</span>

  1828. <span class="gp">... </span><span class="k">class</span> <span class="nc">TestSample</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>

  1829. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">test_sample</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1830. <span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s1">&#39;newkey&#39;</span><span class="p">],</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">)</span>

  1831. </pre></div>

  1832. </div>

  1833. <p>If you want to use a different prefix for your test, you can inform the

  1834. patchers of the different prefix by setting <code class="docutils literal notranslate"><span class="pre">patch.TEST_PREFIX</span></code>. For

  1835. more details about how to change the value of see <a class="reference internal" href="#test-prefix"><span class="std std-ref">TEST_PREFIX</span></a>.</p>

  1836. <p><a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> can be used to add members to a dictionary, or simply let a test

  1837. change a dictionary, and ensure the dictionary is restored when the test

  1838. ends.</p>

  1839. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">foo</span> <span class="o">=</span> <span class="p">{}</span>

  1840. <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="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">})</span> <span class="k">as</span> <span class="n">patched_foo</span><span class="p">:</span>

  1841. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{</span><span class="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">}</span>

  1842. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">patched_foo</span> <span class="o">==</span> <span class="p">{</span><span class="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">}</span>

  1843. <span class="gp">... </span>    <span class="c1"># You can add, update or delete keys of foo (or patched_foo, it&#39;s the same dict)</span>

  1844. <span class="gp">... </span>    <span class="n">patched_foo</span><span class="p">[</span><span class="s1">&#39;spam&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;eggs&#39;</span>

  1845. <span class="gp">...</span>

  1846. <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{}</span>

  1847. <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">patched_foo</span> <span class="o">==</span> <span class="p">{}</span>

  1848. </pre></div>

  1849. </div>

  1850. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">os</span>

  1851. <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="s1">&#39;os.environ&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s1">&#39;newkey&#39;</span><span class="p">:</span> <span class="s1">&#39;newvalue&#39;</span><span class="p">}):</span>

  1852. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s1">&#39;newkey&#39;</span><span class="p">])</span>

  1853. <span class="gp">...</span>

  1854. <span class="go">newvalue</span>

  1855. <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="s1">&#39;newkey&#39;</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>

  1856. </pre></div>

  1857. </div>

  1858. <p>Keywords can be used in the <a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> call to set values in the dictionary:</p>

  1859. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mymodule</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>

  1860. <span class="gp">&gt;&gt;&gt; </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="s1">&#39;fish&#39;</span>

  1861. <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="s1">&#39;sys.modules&#39;</span><span class="p">,</span> <span class="n">mymodule</span><span class="o">=</span><span class="n">mymodule</span><span class="p">):</span>

  1862. <span class="gp">... </span>    <span class="kn">import</span> <span class="nn">mymodule</span>

  1863. <span class="gp">... </span>    <span class="n">mymodule</span><span class="o">.</span><span class="n">function</span><span class="p">(</span><span class="s1">&#39;some&#39;</span><span class="p">,</span> <span class="s1">&#39;args&#39;</span><span class="p">)</span>

  1864. <span class="gp">...</span>

  1865. <span class="go">&#39;fish&#39;</span>

  1866. </pre></div>

  1867. </div>

  1868. <p><a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> can be used with dictionary like objects that aren’t actually

  1869. dictionaries. At the very minimum they must support item getting, setting,

  1870. deleting and either iteration or membership test. This corresponds to the

  1871. magic methods <a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a>,

  1872. <a class="reference internal" href="../reference/datamodel.html#object.__delitem__" title="object.__delitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delitem__()</span></code></a> and either <a class="reference internal" href="stdtypes.html#container.__iter__" title="container.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> or

  1873. <a class="reference internal" href="../reference/datamodel.html#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a>.</p>

  1874. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Container</span><span class="p">:</span>

  1875. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1876. <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>

  1877. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  1878. <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>

  1879. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__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>

  1880. <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>

  1881. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__delitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>

  1882. <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>

  1883. <span class="gp">... </span>    <span class="k">def</span> <span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  1884. <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>

  1885. <span class="gp">...</span>

  1886. <span class="gp">&gt;&gt;&gt; </span><span class="n">thing</span> <span class="o">=</span> <span class="n">Container</span><span class="p">()</span>

  1887. <span class="gp">&gt;&gt;&gt; </span><span class="n">thing</span><span class="p">[</span><span class="s1">&#39;one&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>

  1888. <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">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>

  1889. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s1">&#39;one&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="mi">2</span>

  1890. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s1">&#39;two&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="mi">3</span>

  1891. <span class="gp">...</span>

  1892. <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s1">&#39;one&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="mi">1</span>

  1893. <span class="gp">&gt;&gt;&gt; </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="s1">&#39;one&#39;</span><span class="p">]</span>

  1894. </pre></div>

  1895. </div>

  1896. </section>

  1897. <section id="patch-multiple">

  1898. <h3>patch.multiple<a class="headerlink" href="#patch-multiple" title="Link to this heading">¶</a></h3>

  1899. <dl class="py function">

  1900. <dt class="sig sig-object py" id="unittest.mock.patch.multiple">

  1901. <span class="sig-prename descclassname"><span class="pre">patch.</span></span><span class="sig-name descname"><span class="pre">multiple</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">target</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">create</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec_set</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">autospec</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">new_callable</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.patch.multiple" title="Link to this definition">¶</a></dt>

  1902. <dd><p>Perform multiple patches in a single call. It takes the object to be

  1903. patched (either as an object or a string to fetch the object by importing)

  1904. and keyword arguments for the patches:</p>

  1905. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></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="n">settings</span><span class="p">,</span> <span class="n">FIRST_PATCH</span><span class="o">=</span><span class="s1">&#39;one&#39;</span><span class="p">,</span> <span class="n">SECOND_PATCH</span><span class="o">=</span><span class="s1">&#39;two&#39;</span><span class="p">):</span>

  1906.     <span class="o">...</span>

  1907. </pre></div>

  1908. </div>

  1909. <p>Use <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a> as the value if you want <a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a> to create

  1910. mocks for you. In this case the created mocks are passed into a decorated

  1911. function by keyword, and a dictionary is returned when <a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a> is

  1912. used as a context manager.</p>

  1913. <p><a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a> can be used as a decorator, class decorator or a context

  1914. manager. The arguments <em>spec</em>, <em>spec_set</em>, <em>create</em>, <em>autospec</em> and

  1915. <em>new_callable</em> have the same meaning as for <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>. These arguments will

  1916. be applied to <em>all</em> patches done by <a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a>.</p>

  1917. <p>When used as a class decorator <a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a> honours <code class="docutils literal notranslate"><span class="pre">patch.TEST_PREFIX</span></code>

  1918. for choosing which methods to wrap.</p>

  1919. </dd></dl>

  1920. 

  1921. <p>If you want <a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a> to create mocks for you, then you can use

  1922. <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a> as the value. If you use <a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a> as a decorator

  1923. then the created mocks are passed into the decorated function by keyword.</p>

  1924. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">thing</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1925. <span class="gp">&gt;&gt;&gt; </span><span class="n">other</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>

  1926. 

  1927. <span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="o">.</span><span class="n">multiple</span><span class="p">(</span><span class="s1">&#39;__main__&#39;</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>

  1928. <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>

  1929. <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>

  1930. <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>

  1931. <span class="gp">...</span>

  1932. <span class="gp">&gt;&gt;&gt; </span><span class="n">test_function</span><span class="p">()</span>

  1933. </pre></div>

  1934. </div>

  1935. <p><a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a> can be nested with other <code class="docutils literal notranslate"><span class="pre">patch</span></code> decorators, but put arguments

  1936. passed by keyword <em>after</em> any of the standard arguments created by <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>:</p>

  1937. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;sys.exit&#39;</span><span class="p">)</span>

  1938. <span class="gp">... </span><span class="nd">@patch</span><span class="o">.</span><span class="n">multiple</span><span class="p">(</span><span class="s1">&#39;__main__&#39;</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>

  1939. <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>

  1940. <span class="gp">... </span>    <span class="k">assert</span> <span class="s1">&#39;other&#39;</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">other</span><span class="p">)</span>

  1941. <span class="gp">... </span>    <span class="k">assert</span> <span class="s1">&#39;thing&#39;</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">thing</span><span class="p">)</span>

  1942. <span class="gp">... </span>    <span class="k">assert</span> <span class="s1">&#39;exit&#39;</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>

  1943. <span class="gp">...</span>

  1944. <span class="gp">&gt;&gt;&gt; </span><span class="n">test_function</span><span class="p">()</span>

  1945. </pre></div>

  1946. </div>

  1947. <p>If <a class="reference internal" href="#unittest.mock.patch.multiple" title="unittest.mock.patch.multiple"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.multiple()</span></code></a> is used as a context manager, the value returned by the

  1948. context manager is a dictionary where created mocks are keyed by name:</p>

  1949. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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="s1">&#39;__main__&#39;</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>

  1950. <span class="gp">... </span>    <span class="k">assert</span> <span class="s1">&#39;other&#39;</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="s1">&#39;other&#39;</span><span class="p">])</span>

  1951. <span class="gp">... </span>    <span class="k">assert</span> <span class="s1">&#39;thing&#39;</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="s1">&#39;thing&#39;</span><span class="p">])</span>

  1952. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">values</span><span class="p">[</span><span class="s1">&#39;thing&#39;</span><span class="p">]</span> <span class="ow">is</span> <span class="n">thing</span>

  1953. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">values</span><span class="p">[</span><span class="s1">&#39;other&#39;</span><span class="p">]</span> <span class="ow">is</span> <span class="n">other</span>

  1954. <span class="gp">...</span>

  1955. </pre></div>

  1956. </div>

  1957. </section>

  1958. <section id="patch-methods-start-and-stop">

  1959. <span id="start-and-stop"></span><h3>patch methods: start and stop<a class="headerlink" href="#patch-methods-start-and-stop" title="Link to this heading">¶</a></h3>

  1960. <p>All the patchers have <code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">stop()</span></code> methods. These make it simpler to do

  1961. patching in <code class="docutils literal notranslate"><span class="pre">setUp</span></code> methods or where you want to do multiple patches without

  1962. nesting decorators or with statements.</p>

  1963. <p>To use them call <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>, <a class="reference internal" href="#unittest.mock.patch.object" title="unittest.mock.patch.object"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.object()</span></code></a> or <a class="reference internal" href="#unittest.mock.patch.dict" title="unittest.mock.patch.dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.dict()</span></code></a> as

  1964. normal and keep a reference to the returned <code class="docutils literal notranslate"><span class="pre">patcher</span></code> object. You can then

  1965. call <code class="xref py py-meth docutils literal notranslate"><span class="pre">start()</span></code> to put the patch in place and <code class="xref py py-meth docutils literal notranslate"><span class="pre">stop()</span></code> to undo it.</p>

  1966. <p>If you are using <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> to create a mock for you then it will be returned by

  1967. the call to <code class="docutils literal notranslate"><span class="pre">patcher.start</span></code>.</p>

  1968. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;package.module.ClassName&#39;</span><span class="p">)</span>

  1969. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">package</span> <span class="kn">import</span> <span class="n">module</span>

  1970. <span class="gp">&gt;&gt;&gt; </span><span class="n">original</span> <span class="o">=</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span>

  1971. <span class="gp">&gt;&gt;&gt; </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>

  1972. <span class="gp">&gt;&gt;&gt; </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>

  1973. <span class="gp">&gt;&gt;&gt; </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>

  1974. <span class="gp">&gt;&gt;&gt; </span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>

  1975. <span class="gp">&gt;&gt;&gt; </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>

  1976. <span class="gp">&gt;&gt;&gt; </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>

  1977. </pre></div>

  1978. </div>

  1979. <p>A typical use case for this might be for doing multiple patches in the <code class="docutils literal notranslate"><span class="pre">setUp</span></code>

  1980. method of a <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code>:</p>

  1981. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>

  1982. <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>

  1983. <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="s1">&#39;package.module.Class1&#39;</span><span class="p">)</span>

  1984. <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="s1">&#39;package.module.Class2&#39;</span><span class="p">)</span>

  1985. <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>

  1986. <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>

  1987. <span class="gp">...</span>

  1988. <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>

  1989. <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>

  1990. <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>

  1991. <span class="gp">...</span>

  1992. <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>

  1993. <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>

  1994. <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>

  1995. <span class="gp">...</span>

  1996. <span class="gp">&gt;&gt;&gt; </span><span class="n">MyTest</span><span class="p">(</span><span class="s1">&#39;test_something&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>

  1997. </pre></div>

  1998. </div>

  1999. <div class="admonition caution">

  2000. <p class="admonition-title">Caution</p>

  2001. <p>If you use this technique you must ensure that the patching is “undone” by

  2002. calling <code class="docutils literal notranslate"><span class="pre">stop</span></code>. This can be fiddlier than you might think, because if an

  2003. exception is raised in the <code class="docutils literal notranslate"><span class="pre">setUp</span></code> then <code class="docutils literal notranslate"><span class="pre">tearDown</span></code> is not called.

  2004. <a class="reference internal" href="unittest.html#unittest.TestCase.addCleanup" title="unittest.TestCase.addCleanup"><code class="xref py py-meth docutils literal notranslate"><span class="pre">unittest.TestCase.addCleanup()</span></code></a> makes this easier:</p>

  2005. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>

  2006. <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>

  2007. <span class="gp">... </span>        <span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;package.module.Class&#39;</span><span class="p">)</span>

  2008. <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>

  2009. <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>

  2010. <span class="gp">...</span>

  2011. <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>

  2012. <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>

  2013. <span class="gp">...</span>

  2014. </pre></div>

  2015. </div>

  2016. <p>As an added bonus you no longer need to keep a reference to the <code class="docutils literal notranslate"><span class="pre">patcher</span></code>

  2017. object.</p>

  2018. </div>

  2019. <p>It is also possible to stop all patches which have been started by using

  2020. <a class="reference internal" href="#unittest.mock.patch.stopall" title="unittest.mock.patch.stopall"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.stopall()</span></code></a>.</p>

  2021. <dl class="py function">

  2022. <dt class="sig sig-object py" id="unittest.mock.patch.stopall">

  2023. <span class="sig-prename descclassname"><span class="pre">patch.</span></span><span class="sig-name descname"><span class="pre">stopall</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.patch.stopall" title="Link to this definition">¶</a></dt>

  2024. <dd><p>Stop all active patches. Only stops patches started with <code class="docutils literal notranslate"><span class="pre">start</span></code>.</p>

  2025. </dd></dl>

  2026. 

  2027. </section>

  2028. <section id="patch-builtins">

  2029. <span id="id4"></span><h3>patch builtins<a class="headerlink" href="#patch-builtins" title="Link to this heading">¶</a></h3>

  2030. <p>You can patch any builtins within a module. The following example patches

  2031. builtin <a class="reference internal" href="functions.html#ord" title="ord"><code class="xref py py-func docutils literal notranslate"><span class="pre">ord()</span></code></a>:</p>

  2032. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;__main__.ord&#39;</span><span class="p">)</span>

  2033. <span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">mock_ord</span><span class="p">):</span>

  2034. <span class="gp">... </span>    <span class="n">mock_ord</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="mi">101</span>

  2035. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="nb">ord</span><span class="p">(</span><span class="s1">&#39;c&#39;</span><span class="p">))</span>

  2036. <span class="gp">...</span>

  2037. <span class="gp">&gt;&gt;&gt; </span><span class="n">test</span><span class="p">()</span>

  2038. <span class="go">101</span>

  2039. </pre></div>

  2040. </div>

  2041. </section>

  2042. <section id="test-prefix">

  2043. <span id="id5"></span><h3>TEST_PREFIX<a class="headerlink" href="#test-prefix" title="Link to this heading">¶</a></h3>

  2044. <p>All of the patchers can be used as class decorators. When used in this way

  2045. they wrap every test method on the class. The patchers recognise methods that

  2046. start with <code class="docutils literal notranslate"><span class="pre">'test'</span></code> as being test methods. This is the same way that the

  2047. <a class="reference internal" href="unittest.html#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestLoader</span></code></a> finds test methods by default.</p>

  2048. <p>It is possible that you want to use a different prefix for your tests. You can

  2049. inform the patchers of the different prefix by setting <code class="docutils literal notranslate"><span class="pre">patch.TEST_PREFIX</span></code>:</p>

  2050. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">patch</span><span class="o">.</span><span class="n">TEST_PREFIX</span> <span class="o">=</span> <span class="s1">&#39;foo&#39;</span>

  2051. <span class="gp">&gt;&gt;&gt; </span><span class="n">value</span> <span class="o">=</span> <span class="mi">3</span>

  2052. <span class="gp">&gt;&gt;&gt;</span>

  2053. <span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;__main__.value&#39;</span><span class="p">,</span> <span class="s1">&#39;not three&#39;</span><span class="p">)</span>

  2054. <span class="gp">... </span><span class="k">class</span> <span class="nc">Thing</span><span class="p">:</span>

  2055. <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>

  2056. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>

  2057. <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>

  2058. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>

  2059. <span class="gp">...</span>

  2060. <span class="gp">&gt;&gt;&gt;</span>

  2061. <span class="gp">&gt;&gt;&gt; </span><span class="n">Thing</span><span class="p">()</span><span class="o">.</span><span class="n">foo_one</span><span class="p">()</span>

  2062. <span class="go">not three</span>

  2063. <span class="gp">&gt;&gt;&gt; </span><span class="n">Thing</span><span class="p">()</span><span class="o">.</span><span class="n">foo_two</span><span class="p">()</span>

  2064. <span class="go">not three</span>

  2065. <span class="gp">&gt;&gt;&gt; </span><span class="n">value</span>

  2066. <span class="go">3</span>

  2067. </pre></div>

  2068. </div>

  2069. </section>

  2070. <section id="nesting-patch-decorators">

  2071. <h3>Nesting Patch Decorators<a class="headerlink" href="#nesting-patch-decorators" title="Link to this heading">¶</a></h3>

  2072. <p>If you want to perform multiple patches then you can simply stack up the

  2073. decorators.</p>

  2074. <p>You can stack up multiple patch decorators using this pattern:</p>

  2075. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nd">@patch</span><span class="o">.</span><span class="n">object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s1">&#39;class_method&#39;</span><span class="p">)</span>

  2076. <span class="gp">... </span><span class="nd">@patch</span><span class="o">.</span><span class="n">object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s1">&#39;static_method&#39;</span><span class="p">)</span>

  2077. <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>

  2078. <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>

  2079. <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>

  2080. <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="s1">&#39;foo&#39;</span><span class="p">)</span>

  2081. <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="s1">&#39;bar&#39;</span><span class="p">)</span>

  2082. <span class="gp">... </span>    <span class="k">return</span> <span class="n">mock1</span><span class="p">,</span> <span class="n">mock2</span>

  2083. <span class="gp">...</span>

  2084. <span class="gp">&gt;&gt;&gt; </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>

  2085. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock1</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  2086. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock2</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  2087. </pre></div>

  2088. </div>

  2089. <p>Note that the decorators are applied from the bottom upwards. This is the

  2090. standard way that Python applies decorators. The order of the created mocks

  2091. passed into your test function matches this order.</p>

  2092. </section>

  2093. <section id="where-to-patch">

  2094. <span id="id6"></span><h3>Where to patch<a class="headerlink" href="#where-to-patch" title="Link to this heading">¶</a></h3>

  2095. <p><a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> works by (temporarily) changing the object that a <em>name</em> points to with

  2096. another one. There can be many names pointing to any individual object, so

  2097. for patching to work you must ensure that you patch the name used by the system

  2098. under test.</p>

  2099. <p>The basic principle is that you patch where an object is <em>looked up</em>, which

  2100. is not necessarily the same place as where it is defined. A couple of

  2101. examples will help to clarify this.</p>

  2102. <p>Imagine we have a project that we want to test with the following structure:</p>

  2103. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">a</span><span class="o">.</span><span class="n">py</span>

  2104.     <span class="o">-&gt;</span> <span class="n">Defines</span> <span class="n">SomeClass</span>

  2105. 

  2106. <span class="n">b</span><span class="o">.</span><span class="n">py</span>

  2107.     <span class="o">-&gt;</span> <span class="kn">from</span> <span class="nn">a</span> <span class="kn">import</span> <span class="n">SomeClass</span>

  2108.     <span class="o">-&gt;</span> <span class="n">some_function</span> <span class="n">instantiates</span> <span class="n">SomeClass</span>

  2109. </pre></div>

  2110. </div>

  2111. <p>Now we want to test <code class="docutils literal notranslate"><span class="pre">some_function</span></code> but we want to mock out <code class="docutils literal notranslate"><span class="pre">SomeClass</span></code> using

  2112. <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>. The problem is that when we import module b, which we will have to

  2113. do then it imports <code class="docutils literal notranslate"><span class="pre">SomeClass</span></code> from module a. If we use <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> to mock out

  2114. <code class="docutils literal notranslate"><span class="pre">a.SomeClass</span></code> then it will have no effect on our test; module b already has a

  2115. reference to the <em>real</em> <code class="docutils literal notranslate"><span class="pre">SomeClass</span></code> and it looks like our patching had no

  2116. effect.</p>

  2117. <p>The key is to patch out <code class="docutils literal notranslate"><span class="pre">SomeClass</span></code> where it is used (or where it is looked up).

  2118. In this case <code class="docutils literal notranslate"><span class="pre">some_function</span></code> will actually look up <code class="docutils literal notranslate"><span class="pre">SomeClass</span></code> in module b,

  2119. where we have imported it. The patching should look like:</p>

  2120. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;b.SomeClass&#39;</span><span class="p">)</span>

  2121. </pre></div>

  2122. </div>

  2123. <p>However, consider the alternative scenario where instead of <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">a</span> <span class="pre">import</span>

  2124. <span class="pre">SomeClass</span></code> module b does <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">some_function</span></code> uses <code class="docutils literal notranslate"><span class="pre">a.SomeClass</span></code>. Both

  2125. of these import forms are common. In this case the class we want to patch is

  2126. being looked up in the module and so we have to patch <code class="docutils literal notranslate"><span class="pre">a.SomeClass</span></code> instead:</p>

  2127. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@patch</span><span class="p">(</span><span class="s1">&#39;a.SomeClass&#39;</span><span class="p">)</span>

  2128. </pre></div>

  2129. </div>

  2130. </section>

  2131. <section id="patching-descriptors-and-proxy-objects">

  2132. <h3>Patching Descriptors and Proxy Objects<a class="headerlink" href="#patching-descriptors-and-proxy-objects" title="Link to this heading">¶</a></h3>

  2133. <p>Both <a class="reference internal" href="#patch">patch</a> and <a class="reference internal" href="#patch-object">patch.object</a> correctly patch and restore descriptors: class

  2134. methods, static methods and properties. You should patch these on the <em>class</em>

  2135. rather than an instance. They also work with <em>some</em> objects

  2136. that proxy attribute access, like the <a class="reference external" href="https://web.archive.org/web/20200603181648/http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198">django settings object</a>.</p>

  2137. </section>

  2138. </section>

  2139. <section id="magicmock-and-magic-method-support">

  2140. <h2>MagicMock and magic method support<a class="headerlink" href="#magicmock-and-magic-method-support" title="Link to this heading">¶</a></h2>

  2141. <section id="mocking-magic-methods">

  2142. <span id="magic-methods"></span><h3>Mocking Magic Methods<a class="headerlink" href="#mocking-magic-methods" title="Link to this heading">¶</a></h3>

  2143. <p><a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> supports mocking the Python protocol methods, also known as

  2144. <a class="reference internal" href="../glossary.html#term-magic-method"><span class="xref std std-term">“magic methods”</span></a>. This allows mock objects to replace

  2145. containers or other objects that implement Python protocols.</p>

  2146. <p>Because magic methods are looked up differently from normal methods <a class="footnote-reference brackets" href="#id9" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>, this

  2147. support has been specially implemented. This means that only specific magic

  2148. methods are supported. The supported list includes <em>almost</em> all of them. If

  2149. there are any missing that you need please let us know.</p>

  2150. <p>You mock magic methods by setting the method you are interested in to a function

  2151. or a mock instance. If you are using a function then it <em>must</em> take <code class="docutils literal notranslate"><span class="pre">self</span></code> as

  2152. the first argument <a class="footnote-reference brackets" href="#id10" id="id8" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a>.</p>

  2153. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2154. <span class="gp">... </span>    <span class="k">return</span> <span class="s1">&#39;fooble&#39;</span>

  2155. <span class="gp">...</span>

  2156. <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>

  2157. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__str__</span> <span class="o">=</span> <span class="fm">__str__</span>

  2158. <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>

  2159. <span class="go">&#39;fooble&#39;</span>

  2160. </pre></div>

  2161. </div>

  2162. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  2163. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__str__</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">()</span>

  2164. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__str__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s1">&#39;fooble&#39;</span>

  2165. <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>

  2166. <span class="go">&#39;fooble&#39;</span>

  2167. </pre></div>

  2168. </div>

  2169. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  2170. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__iter__</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="nb">iter</span><span class="p">([]))</span>

  2171. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2172. <span class="go">[]</span>

  2173. </pre></div>

  2174. </div>

  2175. <p>One use case for this is for mocking objects used as context managers in a

  2176. <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement:</p>

  2177. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  2178. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__enter__</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="s1">&#39;foo&#39;</span><span class="p">)</span>

  2179. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__exit__</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="kc">False</span><span class="p">)</span>

  2180. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">mock</span> <span class="k">as</span> <span class="n">m</span><span class="p">:</span>

  2181. <span class="gp">... </span>    <span class="k">assert</span> <span class="n">m</span> <span class="o">==</span> <span class="s1">&#39;foo&#39;</span>

  2182. <span class="gp">...</span>

  2183. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__enter__</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">()</span>

  2184. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__exit__</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>

  2185. </pre></div>

  2186. </div>

  2187. <p>Calls to magic methods do not appear in <a class="reference internal" href="#unittest.mock.Mock.method_calls" title="unittest.mock.Mock.method_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">method_calls</span></code></a>, but they

  2188. are recorded in <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a>.</p>

  2189. <div class="admonition note">

  2190. <p class="admonition-title">Note</p>

  2191. <p>If you use the <em>spec</em> keyword argument to create a mock then attempting to

  2192. set a magic method that isn’t in the spec will raise an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.</p>

  2193. </div>

  2194. <p>The full list of supported magic methods is:</p>

  2195. <ul class="simple">

  2196. <li><p><code class="docutils literal notranslate"><span class="pre">__hash__</span></code>, <code class="docutils literal notranslate"><span class="pre">__sizeof__</span></code>, <code class="docutils literal notranslate"><span class="pre">__repr__</span></code> and <code class="docutils literal notranslate"><span class="pre">__str__</span></code></p></li>

  2197. <li><p><code class="docutils literal notranslate"><span class="pre">__dir__</span></code>, <code class="docutils literal notranslate"><span class="pre">__format__</span></code> and <code class="docutils literal notranslate"><span class="pre">__subclasses__</span></code></p></li>

  2198. <li><p><code class="docutils literal notranslate"><span class="pre">__round__</span></code>, <code class="docutils literal notranslate"><span class="pre">__floor__</span></code>, <code class="docutils literal notranslate"><span class="pre">__trunc__</span></code> and <code class="docutils literal notranslate"><span class="pre">__ceil__</span></code></p></li>

  2199. <li><p>Comparisons: <code class="docutils literal notranslate"><span class="pre">__lt__</span></code>, <code class="docutils literal notranslate"><span class="pre">__gt__</span></code>, <code class="docutils literal notranslate"><span class="pre">__le__</span></code>, <code class="docutils literal notranslate"><span class="pre">__ge__</span></code>,

  2200. <code class="docutils literal notranslate"><span class="pre">__eq__</span></code> and <code class="docutils literal notranslate"><span class="pre">__ne__</span></code></p></li>

  2201. <li><p>Container methods: <code class="docutils literal notranslate"><span class="pre">__getitem__</span></code>, <code class="docutils literal notranslate"><span class="pre">__setitem__</span></code>, <code class="docutils literal notranslate"><span class="pre">__delitem__</span></code>,

  2202. <code class="docutils literal notranslate"><span class="pre">__contains__</span></code>, <code class="docutils literal notranslate"><span class="pre">__len__</span></code>, <code class="docutils literal notranslate"><span class="pre">__iter__</span></code>, <code class="docutils literal notranslate"><span class="pre">__reversed__</span></code>

  2203. and <code class="docutils literal notranslate"><span class="pre">__missing__</span></code></p></li>

  2204. <li><p>Context manager: <code class="docutils literal notranslate"><span class="pre">__enter__</span></code>, <code class="docutils literal notranslate"><span class="pre">__exit__</span></code>, <code class="docutils literal notranslate"><span class="pre">__aenter__</span></code> and <code class="docutils literal notranslate"><span class="pre">__aexit__</span></code></p></li>

  2205. <li><p>Unary numeric methods: <code class="docutils literal notranslate"><span class="pre">__neg__</span></code>, <code class="docutils literal notranslate"><span class="pre">__pos__</span></code> and <code class="docutils literal notranslate"><span class="pre">__invert__</span></code></p></li>

  2206. <li><p>The numeric methods (including right hand and in-place variants):

  2207. <code class="docutils literal notranslate"><span class="pre">__add__</span></code>, <code class="docutils literal notranslate"><span class="pre">__sub__</span></code>, <code class="docutils literal notranslate"><span class="pre">__mul__</span></code>, <code class="docutils literal notranslate"><span class="pre">__matmul__</span></code>, <code class="docutils literal notranslate"><span class="pre">__truediv__</span></code>,

  2208. <code class="docutils literal notranslate"><span class="pre">__floordiv__</span></code>, <code class="docutils literal notranslate"><span class="pre">__mod__</span></code>, <code class="docutils literal notranslate"><span class="pre">__divmod__</span></code>, <code class="docutils literal notranslate"><span class="pre">__lshift__</span></code>,

  2209. <code class="docutils literal notranslate"><span class="pre">__rshift__</span></code>, <code class="docutils literal notranslate"><span class="pre">__and__</span></code>, <code class="docutils literal notranslate"><span class="pre">__xor__</span></code>, <code class="docutils literal notranslate"><span class="pre">__or__</span></code>, and <code class="docutils literal notranslate"><span class="pre">__pow__</span></code></p></li>

  2210. <li><p>Numeric conversion methods: <code class="docutils literal notranslate"><span class="pre">__complex__</span></code>, <code class="docutils literal notranslate"><span class="pre">__int__</span></code>, <code class="docutils literal notranslate"><span class="pre">__float__</span></code>

  2211. and <code class="docutils literal notranslate"><span class="pre">__index__</span></code></p></li>

  2212. <li><p>Descriptor methods: <code class="docutils literal notranslate"><span class="pre">__get__</span></code>, <code class="docutils literal notranslate"><span class="pre">__set__</span></code> and <code class="docutils literal notranslate"><span class="pre">__delete__</span></code></p></li>

  2213. <li><p>Pickling: <code class="docutils literal notranslate"><span class="pre">__reduce__</span></code>, <code class="docutils literal notranslate"><span class="pre">__reduce_ex__</span></code>, <code class="docutils literal notranslate"><span class="pre">__getinitargs__</span></code>,

  2214. <code class="docutils literal notranslate"><span class="pre">__getnewargs__</span></code>, <code class="docutils literal notranslate"><span class="pre">__getstate__</span></code> and <code class="docutils literal notranslate"><span class="pre">__setstate__</span></code></p></li>

  2215. <li><p>File system path representation: <code class="docutils literal notranslate"><span class="pre">__fspath__</span></code></p></li>

  2216. <li><p>Asynchronous iteration methods: <code class="docutils literal notranslate"><span class="pre">__aiter__</span></code> and <code class="docutils literal notranslate"><span class="pre">__anext__</span></code></p></li>

  2217. </ul>

  2218. <div class="versionchanged">

  2219. <p><span class="versionmodified changed">Changed in version 3.8: </span>Added support for <a class="reference internal" href="os.html#os.PathLike.__fspath__" title="os.PathLike.__fspath__"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.PathLike.__fspath__()</span></code></a>.</p>

  2220. </div>

  2221. <div class="versionchanged">

  2222. <p><span class="versionmodified changed">Changed in version 3.8: </span>Added support for <code class="docutils literal notranslate"><span class="pre">__aenter__</span></code>, <code class="docutils literal notranslate"><span class="pre">__aexit__</span></code>, <code class="docutils literal notranslate"><span class="pre">__aiter__</span></code> and <code class="docutils literal notranslate"><span class="pre">__anext__</span></code>.</p>

  2223. </div>

  2224. <p>The following methods exist but are <em>not</em> supported as they are either in use

  2225. by mock, can’t be set dynamically, or can cause problems:</p>

  2226. <ul class="simple">

  2227. <li><p><code class="docutils literal notranslate"><span class="pre">__getattr__</span></code>, <code class="docutils literal notranslate"><span class="pre">__setattr__</span></code>, <code class="docutils literal notranslate"><span class="pre">__init__</span></code> and <code class="docutils literal notranslate"><span class="pre">__new__</span></code></p></li>

  2228. <li><p><code class="docutils literal notranslate"><span class="pre">__prepare__</span></code>, <code class="docutils literal notranslate"><span class="pre">__instancecheck__</span></code>, <code class="docutils literal notranslate"><span class="pre">__subclasscheck__</span></code>, <code class="docutils literal notranslate"><span class="pre">__del__</span></code></p></li>

  2229. </ul>

  2230. </section>

  2231. <section id="magic-mock">

  2232. <h3>Magic Mock<a class="headerlink" href="#magic-mock" title="Link to this heading">¶</a></h3>

  2233. <p>There are two <code class="docutils literal notranslate"><span class="pre">MagicMock</span></code> variants: <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> and <a class="reference internal" href="#unittest.mock.NonCallableMagicMock" title="unittest.mock.NonCallableMagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">NonCallableMagicMock</span></code></a>.</p>

  2234. <dl class="py class">

  2235. <dt class="sig sig-object py" id="unittest.mock.MagicMock">

  2236. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">MagicMock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.MagicMock" title="Link to this definition">¶</a></dt>

  2237. <dd><p><code class="docutils literal notranslate"><span class="pre">MagicMock</span></code> is a subclass of <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> with default implementations

  2238. of most of the <a class="reference internal" href="../glossary.html#term-magic-method"><span class="xref std std-term">magic methods</span></a>. You can use

  2239. <code class="docutils literal notranslate"><span class="pre">MagicMock</span></code> without having to configure the magic methods yourself.</p>

  2240. <p>The constructor parameters have the same meaning as for <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a>.</p>

  2241. <p>If you use the <em>spec</em> or <em>spec_set</em> arguments then <em>only</em> magic methods

  2242. that exist in the spec will be created.</p>

  2243. </dd></dl>

  2244. 

  2245. <dl class="py class">

  2246. <dt class="sig sig-object py" id="unittest.mock.NonCallableMagicMock">

  2247. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">NonCallableMagicMock</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.NonCallableMagicMock" title="Link to this definition">¶</a></dt>

  2248. <dd><p>A non-callable version of <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a>.</p>

  2249. <p>The constructor parameters have the same meaning as for

  2250. <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a>, with the exception of <em>return_value</em> and

  2251. <em>side_effect</em> which have no meaning on a non-callable mock.</p>

  2252. </dd></dl>

  2253. 

  2254. <p>The magic methods are setup with <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> objects, so you can configure them

  2255. and use them in the usual way:</p>

  2256. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  2257. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;fish&#39;</span>

  2258. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__setitem__</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="s1">&#39;fish&#39;</span><span class="p">)</span>

  2259. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__getitem__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s1">&#39;result&#39;</span>

  2260. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>

  2261. <span class="go">&#39;result&#39;</span>

  2262. </pre></div>

  2263. </div>

  2264. <p>By default many of the protocol methods are required to return objects of a

  2265. specific type. These methods are preconfigured with a default return value, so

  2266. that they can be used without you having to do anything if you aren’t interested

  2267. in the return value. You can still <em>set</em> the return value manually if you want

  2268. to change the default.</p>

  2269. <p>Methods and their defaults:</p>

  2270. <ul class="simple">

  2271. <li><p><code class="docutils literal notranslate"><span class="pre">__lt__</span></code>: <a class="reference internal" href="constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></a></p></li>

  2272. <li><p><code class="docutils literal notranslate"><span class="pre">__gt__</span></code>: <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></p></li>

  2273. <li><p><code class="docutils literal notranslate"><span class="pre">__le__</span></code>: <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></p></li>

  2274. <li><p><code class="docutils literal notranslate"><span class="pre">__ge__</span></code>: <code class="xref py py-data docutils literal notranslate"><span class="pre">NotImplemented</span></code></p></li>

  2275. <li><p><code class="docutils literal notranslate"><span class="pre">__int__</span></code>: <code class="docutils literal notranslate"><span class="pre">1</span></code></p></li>

  2276. <li><p><code class="docutils literal notranslate"><span class="pre">__contains__</span></code>: <code class="docutils literal notranslate"><span class="pre">False</span></code></p></li>

  2277. <li><p><code class="docutils literal notranslate"><span class="pre">__len__</span></code>: <code class="docutils literal notranslate"><span class="pre">0</span></code></p></li>

  2278. <li><p><code class="docutils literal notranslate"><span class="pre">__iter__</span></code>: <code class="docutils literal notranslate"><span class="pre">iter([])</span></code></p></li>

  2279. <li><p><code class="docutils literal notranslate"><span class="pre">__exit__</span></code>: <code class="docutils literal notranslate"><span class="pre">False</span></code></p></li>

  2280. <li><p><code class="docutils literal notranslate"><span class="pre">__aexit__</span></code>: <code class="docutils literal notranslate"><span class="pre">False</span></code></p></li>

  2281. <li><p><code class="docutils literal notranslate"><span class="pre">__complex__</span></code>: <code class="docutils literal notranslate"><span class="pre">1j</span></code></p></li>

  2282. <li><p><code class="docutils literal notranslate"><span class="pre">__float__</span></code>: <code class="docutils literal notranslate"><span class="pre">1.0</span></code></p></li>

  2283. <li><p><code class="docutils literal notranslate"><span class="pre">__bool__</span></code>: <code class="docutils literal notranslate"><span class="pre">True</span></code></p></li>

  2284. <li><p><code class="docutils literal notranslate"><span class="pre">__index__</span></code>: <code class="docutils literal notranslate"><span class="pre">1</span></code></p></li>

  2285. <li><p><code class="docutils literal notranslate"><span class="pre">__hash__</span></code>: default hash for the mock</p></li>

  2286. <li><p><code class="docutils literal notranslate"><span class="pre">__str__</span></code>: default str for the mock</p></li>

  2287. <li><p><code class="docutils literal notranslate"><span class="pre">__sizeof__</span></code>: default sizeof for the mock</p></li>

  2288. </ul>

  2289. <p>For example:</p>

  2290. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  2291. <span class="gp">&gt;&gt;&gt; </span><span class="nb">int</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2292. <span class="go">1</span>

  2293. <span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2294. <span class="go">0</span>

  2295. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2296. <span class="go">[]</span>

  2297. <span class="gp">&gt;&gt;&gt; </span><span class="nb">object</span><span class="p">()</span> <span class="ow">in</span> <span class="n">mock</span>

  2298. <span class="go">False</span>

  2299. </pre></div>

  2300. </div>

  2301. <p>The two equality methods, <code class="xref py py-meth docutils literal notranslate"><span class="pre">__eq__()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__ne__()</span></code>, are special.

  2302. They do the default equality comparison on identity, using the

  2303. <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> attribute, unless you change their return value to

  2304. return something else:</p>

  2305. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">MagicMock</span><span class="p">()</span> <span class="o">==</span> <span class="mi">3</span>

  2306. <span class="go">False</span>

  2307. <span class="gp">&gt;&gt;&gt; </span><span class="n">MagicMock</span><span class="p">()</span> <span class="o">!=</span> <span class="mi">3</span>

  2308. <span class="go">True</span>

  2309. <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>

  2310. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__eq__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="kc">True</span>

  2311. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">==</span> <span class="mi">3</span>

  2312. <span class="go">True</span>

  2313. </pre></div>

  2314. </div>

  2315. <p>The return value of <code class="xref py py-meth docutils literal notranslate"><span class="pre">MagicMock.__iter__()</span></code> can be any iterable object and isn’t

  2316. required to be an iterator:</p>

  2317. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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>

  2318. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__iter__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="s1">&#39;c&#39;</span><span class="p">]</span>

  2319. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2320. <span class="go">[&#39;a&#39;, &#39;b&#39;, &#39;c&#39;]</span>

  2321. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2322. <span class="go">[&#39;a&#39;, &#39;b&#39;, &#39;c&#39;]</span>

  2323. </pre></div>

  2324. </div>

  2325. <p>If the return value <em>is</em> an iterator, then iterating over it once will consume

  2326. it and subsequent iterations will result in an empty list:</p>

  2327. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="fm">__iter__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">([</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="s1">&#39;c&#39;</span><span class="p">])</span>

  2328. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2329. <span class="go">[&#39;a&#39;, &#39;b&#39;, &#39;c&#39;]</span>

  2330. <span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2331. <span class="go">[]</span>

  2332. </pre></div>

  2333. </div>

  2334. <p><code class="docutils literal notranslate"><span class="pre">MagicMock</span></code> has all of the supported magic methods configured except for some

  2335. of the obscure and obsolete ones. You can still set these up if you want.</p>

  2336. <p>Magic methods that are supported but not setup by default in <code class="docutils literal notranslate"><span class="pre">MagicMock</span></code> are:</p>

  2337. <ul class="simple">

  2338. <li><p><code class="docutils literal notranslate"><span class="pre">__subclasses__</span></code></p></li>

  2339. <li><p><code class="docutils literal notranslate"><span class="pre">__dir__</span></code></p></li>

  2340. <li><p><code class="docutils literal notranslate"><span class="pre">__format__</span></code></p></li>

  2341. <li><p><code class="docutils literal notranslate"><span class="pre">__get__</span></code>, <code class="docutils literal notranslate"><span class="pre">__set__</span></code> and <code class="docutils literal notranslate"><span class="pre">__delete__</span></code></p></li>

  2342. <li><p><code class="docutils literal notranslate"><span class="pre">__reversed__</span></code> and <code class="docutils literal notranslate"><span class="pre">__missing__</span></code></p></li>

  2343. <li><p><code class="docutils literal notranslate"><span class="pre">__reduce__</span></code>, <code class="docutils literal notranslate"><span class="pre">__reduce_ex__</span></code>, <code class="docutils literal notranslate"><span class="pre">__getinitargs__</span></code>, <code class="docutils literal notranslate"><span class="pre">__getnewargs__</span></code>,

  2344. <code class="docutils literal notranslate"><span class="pre">__getstate__</span></code> and <code class="docutils literal notranslate"><span class="pre">__setstate__</span></code></p></li>

  2345. <li><p><code class="docutils literal notranslate"><span class="pre">__getformat__</span></code></p></li>

  2346. </ul>

  2347. <aside class="footnote-list brackets">

  2348. <aside class="footnote brackets" id="id9" role="doc-footnote">

  2349. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id7">2</a><span class="fn-bracket">]</span></span>

  2350. <p>Magic methods <em>should</em> be looked up on the class rather than the

  2351. instance. Different versions of Python are inconsistent about applying this

  2352. rule. The supported protocol methods should work with all supported versions

  2353. of Python.</p>

  2354. </aside>

  2355. <aside class="footnote brackets" id="id10" role="doc-footnote">

  2356. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id8">3</a><span class="fn-bracket">]</span></span>

  2357. <p>The function is basically hooked up to the class, but each <code class="docutils literal notranslate"><span class="pre">Mock</span></code>

  2358. instance is kept isolated from the others.</p>

  2359. </aside>

  2360. </aside>

  2361. </section>

  2362. </section>

  2363. <section id="helpers">

  2364. <h2>Helpers<a class="headerlink" href="#helpers" title="Link to this heading">¶</a></h2>

  2365. <section id="sentinel">

  2366. <h3>sentinel<a class="headerlink" href="#sentinel" title="Link to this heading">¶</a></h3>

  2367. <dl class="py data">

  2368. <dt class="sig sig-object py" id="unittest.mock.sentinel">

  2369. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">sentinel</span></span><a class="headerlink" href="#unittest.mock.sentinel" title="Link to this definition">¶</a></dt>

  2370. <dd><p>The <code class="docutils literal notranslate"><span class="pre">sentinel</span></code> object provides a convenient way of providing unique

  2371. objects for your tests.</p>

  2372. <p>Attributes are created on demand when you access them by name. Accessing

  2373. the same attribute will always return the same object. The objects

  2374. returned have a sensible repr so that test failure messages are readable.</p>

  2375. <div class="versionchanged">

  2376. <p><span class="versionmodified changed">Changed in version 3.7: </span>The <code class="docutils literal notranslate"><span class="pre">sentinel</span></code> attributes now preserve their identity when they are

  2377. <a class="reference internal" href="copy.html#module-copy" title="copy: Shallow and deep copy operations."><code class="xref py py-mod docutils literal notranslate"><span class="pre">copied</span></code></a> or <a class="reference internal" href="pickle.html#module-pickle" title="pickle: Convert Python objects to streams of bytes and back."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pickled</span></code></a>.</p>

  2378. </div>

  2379. </dd></dl>

  2380. 

  2381. <p>Sometimes when testing you need to test that a specific object is passed as an

  2382. argument to another method, or returned. It can be common to create named

  2383. sentinel objects to test this. <a class="reference internal" href="#unittest.mock.sentinel" title="unittest.mock.sentinel"><code class="xref py py-data docutils literal notranslate"><span class="pre">sentinel</span></code></a> provides a convenient way of

  2384. creating and testing the identity of objects like this.</p>

  2385. <p>In this example we monkey patch <code class="docutils literal notranslate"><span class="pre">method</span></code> to return <code class="docutils literal notranslate"><span class="pre">sentinel.some_object</span></code>:</p>

  2386. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">real</span> <span class="o">=</span> <span class="n">ProductionClass</span><span class="p">()</span>

  2387. <span class="gp">&gt;&gt;&gt; </span><span class="n">real</span><span class="o">.</span><span class="n">method</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;method&quot;</span><span class="p">)</span>

  2388. <span class="gp">&gt;&gt;&gt; </span><span class="n">real</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="n">sentinel</span><span class="o">.</span><span class="n">some_object</span>

  2389. <span class="gp">&gt;&gt;&gt; </span><span class="n">result</span> <span class="o">=</span> <span class="n">real</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>

  2390. <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">result</span> <span class="ow">is</span> <span class="n">sentinel</span><span class="o">.</span><span class="n">some_object</span>

  2391. <span class="gp">&gt;&gt;&gt; </span><span class="n">result</span>

  2392. <span class="go">sentinel.some_object</span>

  2393. </pre></div>

  2394. </div>

  2395. </section>

  2396. <section id="default">

  2397. <h3>DEFAULT<a class="headerlink" href="#default" title="Link to this heading">¶</a></h3>

  2398. <dl class="py data">

  2399. <dt class="sig sig-object py" id="unittest.mock.DEFAULT">

  2400. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">DEFAULT</span></span><a class="headerlink" href="#unittest.mock.DEFAULT" title="Link to this definition">¶</a></dt>

  2401. <dd><p>The <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a> object is a pre-created sentinel (actually

  2402. <code class="docutils literal notranslate"><span class="pre">sentinel.DEFAULT</span></code>). It can be used by <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a>

  2403. functions to indicate that the normal return value should be used.</p>

  2404. </dd></dl>

  2405. 

  2406. </section>

  2407. <section id="call">

  2408. <h3>call<a class="headerlink" href="#call" title="Link to this heading">¶</a></h3>

  2409. <dl class="py function">

  2410. <dt class="sig sig-object py" id="unittest.mock.call">

  2411. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">call</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.call" title="Link to this definition">¶</a></dt>

  2412. <dd><p><a class="reference internal" href="#unittest.mock.call" title="unittest.mock.call"><code class="xref py py-func docutils literal notranslate"><span class="pre">call()</span></code></a> is a helper object for making simpler assertions, for comparing with

  2413. <a class="reference internal" href="#unittest.mock.Mock.call_args" title="unittest.mock.Mock.call_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args</span></code></a>, <a class="reference internal" href="#unittest.mock.Mock.call_args_list" title="unittest.mock.Mock.call_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args_list</span></code></a>,

  2414. <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> and <a class="reference internal" href="#unittest.mock.Mock.method_calls" title="unittest.mock.Mock.method_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">method_calls</span></code></a>. <a class="reference internal" href="#unittest.mock.call" title="unittest.mock.call"><code class="xref py py-func docutils literal notranslate"><span class="pre">call()</span></code></a> can also be

  2415. used with <a class="reference internal" href="#unittest.mock.Mock.assert_has_calls" title="unittest.mock.Mock.assert_has_calls"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_has_calls()</span></code></a>.</p>

  2416. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  2417. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">a</span><span class="o">=</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  2418. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">()</span>

  2419. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">call_args_list</span> <span class="o">==</span> <span class="p">[</span><span class="n">call</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">a</span><span class="o">=</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="s1">&#39;bar&#39;</span><span class="p">),</span> <span class="n">call</span><span class="p">()]</span>

  2420. <span class="go">True</span>

  2421. </pre></div>

  2422. </div>

  2423. </dd></dl>

  2424. 

  2425. <dl class="py method">

  2426. <dt class="sig sig-object py" id="unittest.mock.call.call_list">

  2427. <span class="sig-prename descclassname"><span class="pre">call.</span></span><span class="sig-name descname"><span class="pre">call_list</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.call.call_list" title="Link to this definition">¶</a></dt>

  2428. <dd><p>For a call object that represents multiple calls, <a class="reference internal" href="#unittest.mock.call.call_list" title="unittest.mock.call.call_list"><code class="xref py py-meth docutils literal notranslate"><span class="pre">call_list()</span></code></a>

  2429. returns a list of all the intermediate calls as well as the

  2430. final call.</p>

  2431. </dd></dl>

  2432. 

  2433. <p><code class="docutils literal notranslate"><span class="pre">call_list</span></code> is particularly useful for making assertions on “chained calls”. A

  2434. chained call is multiple calls on a single line of code. This results in

  2435. multiple entries in <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a> on a mock. Manually constructing

  2436. the sequence of calls can be tedious.</p>

  2437. <p><a class="reference internal" href="#unittest.mock.call.call_list" title="unittest.mock.call.call_list"><code class="xref py py-meth docutils literal notranslate"><span class="pre">call_list()</span></code></a> can construct the sequence of calls from the same

  2438. chained call:</p>

  2439. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>

  2440. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">method</span><span class="p">(</span><span class="n">arg</span><span class="o">=</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">other</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)(</span><span class="mf">2.0</span><span class="p">)</span>

  2441. <span class="go">&lt;MagicMock name=&#39;mock().method().other()()&#39; id=&#39;...&#39;&gt;</span>

  2442. <span class="gp">&gt;&gt;&gt; </span><span class="n">kall</span> <span class="o">=</span> <span class="n">call</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">method</span><span class="p">(</span><span class="n">arg</span><span class="o">=</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">other</span><span class="p">(</span><span class="s1">&#39;bar&#39;</span><span class="p">)(</span><span class="mf">2.0</span><span class="p">)</span>

  2443. <span class="gp">&gt;&gt;&gt; </span><span class="n">kall</span><span class="o">.</span><span class="n">call_list</span><span class="p">()</span>

  2444. <span class="go">[call(1),</span>

  2445. <span class="go"> call().method(arg=&#39;foo&#39;),</span>

  2446. <span class="go"> call().method().other(&#39;bar&#39;),</span>

  2447. <span class="go"> call().method().other()(2.0)]</span>

  2448. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span> <span class="o">==</span> <span class="n">kall</span><span class="o">.</span><span class="n">call_list</span><span class="p">()</span>

  2449. <span class="go">True</span>

  2450. </pre></div>

  2451. </div>

  2452. <p id="calls-as-tuples">A <code class="docutils literal notranslate"><span class="pre">call</span></code> object is either a tuple of (positional args, keyword args) or

  2453. (name, positional args, keyword args) depending on how it was constructed. When

  2454. you construct them yourself this isn’t particularly interesting, but the <code class="docutils literal notranslate"><span class="pre">call</span></code>

  2455. objects that are in the <a class="reference internal" href="#unittest.mock.Mock.call_args" title="unittest.mock.Mock.call_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Mock.call_args</span></code></a>, <a class="reference internal" href="#unittest.mock.Mock.call_args_list" title="unittest.mock.Mock.call_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Mock.call_args_list</span></code></a> and

  2456. <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Mock.mock_calls</span></code></a> attributes can be introspected to get at the individual

  2457. arguments they contain.</p>

  2458. <p>The <code class="docutils literal notranslate"><span class="pre">call</span></code> objects in <a class="reference internal" href="#unittest.mock.Mock.call_args" title="unittest.mock.Mock.call_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Mock.call_args</span></code></a> and <a class="reference internal" href="#unittest.mock.Mock.call_args_list" title="unittest.mock.Mock.call_args_list"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Mock.call_args_list</span></code></a>

  2459. are two-tuples of (positional args, keyword args) whereas the <code class="docutils literal notranslate"><span class="pre">call</span></code> objects

  2460. in <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Mock.mock_calls</span></code></a>, along with ones you construct yourself, are

  2461. three-tuples of (name, positional args, keyword args).</p>

  2462. <p>You can use their “tupleness” to pull out the individual arguments for more

  2463. complex introspection and assertions. The positional arguments are a tuple

  2464. (an empty tuple if there are no positional arguments) and the keyword

  2465. arguments are a dictionary:</p>

  2466. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  2467. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="n">arg</span><span class="o">=</span><span class="s1">&#39;one&#39;</span><span class="p">,</span> <span class="n">arg2</span><span class="o">=</span><span class="s1">&#39;two&#39;</span><span class="p">)</span>

  2468. <span class="gp">&gt;&gt;&gt; </span><span class="n">kall</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">call_args</span>

  2469. <span class="gp">&gt;&gt;&gt; </span><span class="n">kall</span><span class="o">.</span><span class="n">args</span>

  2470. <span class="go">(1, 2, 3)</span>

  2471. <span class="gp">&gt;&gt;&gt; </span><span class="n">kall</span><span class="o">.</span><span class="n">kwargs</span>

  2472. <span class="go">{&#39;arg&#39;: &#39;one&#39;, &#39;arg2&#39;: &#39;two&#39;}</span>

  2473. <span class="gp">&gt;&gt;&gt; </span><span class="n">kall</span><span class="o">.</span><span class="n">args</span> <span class="ow">is</span> <span class="n">kall</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>

  2474. <span class="go">True</span>

  2475. <span class="gp">&gt;&gt;&gt; </span><span class="n">kall</span><span class="o">.</span><span class="n">kwargs</span> <span class="ow">is</span> <span class="n">kall</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>

  2476. <span class="go">True</span>

  2477. </pre></div>

  2478. </div>

  2479. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>

  2480. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">foo</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="n">arg</span><span class="o">=</span><span class="s1">&#39;two&#39;</span><span class="p">,</span> <span class="n">arg2</span><span class="o">=</span><span class="s1">&#39;three&#39;</span><span class="p">)</span>

  2481. <span class="go">&lt;MagicMock name=&#39;mock.foo()&#39; id=&#39;...&#39;&gt;</span>

  2482. <span class="gp">&gt;&gt;&gt; </span><span class="n">kall</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>

  2483. <span class="gp">&gt;&gt;&gt; </span><span class="n">name</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="n">kall</span>

  2484. <span class="gp">&gt;&gt;&gt; </span><span class="n">name</span>

  2485. <span class="go">&#39;foo&#39;</span>

  2486. <span class="gp">&gt;&gt;&gt; </span><span class="n">args</span>

  2487. <span class="go">(4, 5, 6)</span>

  2488. <span class="gp">&gt;&gt;&gt; </span><span class="n">kwargs</span>

  2489. <span class="go">{&#39;arg&#39;: &#39;two&#39;, &#39;arg2&#39;: &#39;three&#39;}</span>

  2490. <span class="gp">&gt;&gt;&gt; </span><span class="n">name</span> <span class="ow">is</span> <span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span>

  2491. <span class="go">True</span>

  2492. </pre></div>

  2493. </div>

  2494. </section>

  2495. <section id="create-autospec">

  2496. <h3>create_autospec<a class="headerlink" href="#create-autospec" title="Link to this heading">¶</a></h3>

  2497. <dl class="py function">

  2498. <dt class="sig sig-object py" id="unittest.mock.create_autospec">

  2499. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">create_autospec</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">spec</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">spec_set</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">instance</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.create_autospec" title="Link to this definition">¶</a></dt>

  2500. <dd><p>Create a mock object using another object as a spec. Attributes on the

  2501. mock will use the corresponding attribute on the <em>spec</em> object as their

  2502. spec.</p>

  2503. <p>Functions or methods being mocked will have their arguments checked to

  2504. ensure that they are called with the correct signature.</p>

  2505. <p>If <em>spec_set</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> then attempting to set attributes that don’t exist

  2506. on the spec object will raise an <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>.</p>

  2507. <p>If a class is used as a spec then the return value of the mock (the

  2508. instance of the class) will have the same spec. You can use a class as the

  2509. spec for an instance object by passing <code class="docutils literal notranslate"><span class="pre">instance=True</span></code>. The returned mock

  2510. will only be callable if instances of the mock are callable.</p>

  2511. <p><a class="reference internal" href="#unittest.mock.create_autospec" title="unittest.mock.create_autospec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_autospec()</span></code></a> also takes arbitrary keyword arguments that are passed to

  2512. the constructor of the created mock.</p>

  2513. </dd></dl>

  2514. 

  2515. <p>See <a class="reference internal" href="#auto-speccing"><span class="std std-ref">Autospeccing</span></a> for examples of how to use auto-speccing with

  2516. <a class="reference internal" href="#unittest.mock.create_autospec" title="unittest.mock.create_autospec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_autospec()</span></code></a> and the <em>autospec</em> argument to <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a>.</p>

  2517. <div class="versionchanged">

  2518. <p><span class="versionmodified changed">Changed in version 3.8: </span><a class="reference internal" href="#unittest.mock.create_autospec" title="unittest.mock.create_autospec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_autospec()</span></code></a> now returns an <a class="reference internal" href="#unittest.mock.AsyncMock" title="unittest.mock.AsyncMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncMock</span></code></a> if the target is

  2519. an async function.</p>

  2520. </div>

  2521. </section>

  2522. <section id="any">

  2523. <h3>ANY<a class="headerlink" href="#any" title="Link to this heading">¶</a></h3>

  2524. <dl class="py data">

  2525. <dt class="sig sig-object py" id="unittest.mock.ANY">

  2526. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">ANY</span></span><a class="headerlink" href="#unittest.mock.ANY" title="Link to this definition">¶</a></dt>

  2527. <dd></dd></dl>

  2528. 

  2529. <p>Sometimes you may need to make assertions about <em>some</em> of the arguments in a

  2530. call to mock, but either not care about some of the arguments or want to pull

  2531. them individually out of <a class="reference internal" href="#unittest.mock.Mock.call_args" title="unittest.mock.Mock.call_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">call_args</span></code></a> and make more complex

  2532. assertions on them.</p>

  2533. <p>To ignore certain arguments you can pass in objects that compare equal to

  2534. <em>everything</em>. Calls to <a class="reference internal" href="#unittest.mock.Mock.assert_called_with" title="unittest.mock.Mock.assert_called_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_with()</span></code></a> and

  2535. <a class="reference internal" href="#unittest.mock.Mock.assert_called_once_with" title="unittest.mock.Mock.assert_called_once_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_once_with()</span></code></a> will then succeed no matter what was

  2536. passed in.</p>

  2537. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  2538. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="nb">object</span><span class="p">())</span>

  2539. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="n">ANY</span><span class="p">)</span>

  2540. </pre></div>

  2541. </div>

  2542. <p><a class="reference internal" href="#unittest.mock.ANY" title="unittest.mock.ANY"><code class="xref py py-data docutils literal notranslate"><span class="pre">ANY</span></code></a> can also be used in comparisons with call lists like

  2543. <a class="reference internal" href="#unittest.mock.Mock.mock_calls" title="unittest.mock.Mock.mock_calls"><code class="xref py py-attr docutils literal notranslate"><span class="pre">mock_calls</span></code></a>:</p>

  2544. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  2545. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>

  2546. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>

  2547. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="p">(</span><span class="nb">object</span><span class="p">())</span>

  2548. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span> <span class="o">==</span> <span class="p">[</span><span class="n">call</span><span class="p">(</span><span class="mi">1</span><span class="p">),</span> <span class="n">call</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="n">ANY</span><span class="p">]</span>

  2549. <span class="go">True</span>

  2550. </pre></div>

  2551. </div>

  2552. <p><a class="reference internal" href="#unittest.mock.ANY" title="unittest.mock.ANY"><code class="xref py py-data docutils literal notranslate"><span class="pre">ANY</span></code></a> is not limited to comparisons with call objects and so

  2553. can also be used in test assertions:</p>

  2554. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">TestStringMethods</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>

  2555. 

  2556.     <span class="k">def</span> <span class="nf">test_split</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2557.         <span class="n">s</span> <span class="o">=</span> <span class="s1">&#39;hello world&#39;</span>

  2558.         <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">s</span><span class="o">.</span><span class="n">split</span><span class="p">(),</span> <span class="p">[</span><span class="s1">&#39;hello&#39;</span><span class="p">,</span> <span class="n">ANY</span><span class="p">])</span>

  2559. </pre></div>

  2560. </div>

  2561. </section>

  2562. <section id="filter-dir">

  2563. <h3>FILTER_DIR<a class="headerlink" href="#filter-dir" title="Link to this heading">¶</a></h3>

  2564. <dl class="py data">

  2565. <dt class="sig sig-object py" id="unittest.mock.FILTER_DIR">

  2566. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">FILTER_DIR</span></span><a class="headerlink" href="#unittest.mock.FILTER_DIR" title="Link to this definition">¶</a></dt>

  2567. <dd></dd></dl>

  2568. 

  2569. <p><a class="reference internal" href="#unittest.mock.FILTER_DIR" title="unittest.mock.FILTER_DIR"><code class="xref py py-data docutils literal notranslate"><span class="pre">FILTER_DIR</span></code></a> is a module level variable that controls the way mock objects

  2570. respond to <a class="reference internal" href="functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a>. The default is <code class="docutils literal notranslate"><span class="pre">True</span></code>,

  2571. which uses the filtering described below, to only show useful members. If you

  2572. dislike this filtering, or need to switch it off for diagnostic purposes, then

  2573. set <code class="docutils literal notranslate"><span class="pre">mock.FILTER_DIR</span> <span class="pre">=</span> <span class="pre">False</span></code>.</p>

  2574. <p>With filtering on, <code class="docutils literal notranslate"><span class="pre">dir(some_mock)</span></code> shows only useful attributes and will

  2575. include any dynamically created attributes that wouldn’t normally be shown.

  2576. If the mock was created with a <em>spec</em> (or <em>autospec</em> of course) then all the

  2577. attributes from the original are shown, even if they haven’t been accessed

  2578. yet:</p>

  2579. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">dir</span><span class="p">(</span><span class="n">Mock</span><span class="p">())</span>

  2580. <span class="go">[&#39;assert_any_call&#39;,</span>

  2581. <span class="go"> &#39;assert_called&#39;,</span>

  2582. <span class="go"> &#39;assert_called_once&#39;,</span>

  2583. <span class="go"> &#39;assert_called_once_with&#39;,</span>

  2584. <span class="go"> &#39;assert_called_with&#39;,</span>

  2585. <span class="go"> &#39;assert_has_calls&#39;,</span>

  2586. <span class="go"> &#39;assert_not_called&#39;,</span>

  2587. <span class="go"> &#39;attach_mock&#39;,</span>

  2588. <span class="go"> ...</span>

  2589. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">urllib</span> <span class="kn">import</span> <span class="n">request</span>

  2590. <span class="gp">&gt;&gt;&gt; </span><span class="nb">dir</span><span class="p">(</span><span class="n">Mock</span><span class="p">(</span><span class="n">spec</span><span class="o">=</span><span class="n">request</span><span class="p">))</span>

  2591. <span class="go">[&#39;AbstractBasicAuthHandler&#39;,</span>

  2592. <span class="go"> &#39;AbstractDigestAuthHandler&#39;,</span>

  2593. <span class="go"> &#39;AbstractHTTPHandler&#39;,</span>

  2594. <span class="go"> &#39;BaseHandler&#39;,</span>

  2595. <span class="go"> ...</span>

  2596. </pre></div>

  2597. </div>

  2598. <p>Many of the not-very-useful (private to <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> rather than the thing being

  2599. mocked) underscore and double underscore prefixed attributes have been

  2600. filtered from the result of calling <a class="reference internal" href="functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> on a <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a>. If you dislike this

  2601. behaviour you can switch it off by setting the module level switch

  2602. <a class="reference internal" href="#unittest.mock.FILTER_DIR" title="unittest.mock.FILTER_DIR"><code class="xref py py-data docutils literal notranslate"><span class="pre">FILTER_DIR</span></code></a>:</p>

  2603. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest</span> <span class="kn">import</span> <span class="n">mock</span>

  2604. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">FILTER_DIR</span> <span class="o">=</span> <span class="kc">False</span>

  2605. <span class="gp">&gt;&gt;&gt; </span><span class="nb">dir</span><span class="p">(</span><span class="n">mock</span><span class="o">.</span><span class="n">Mock</span><span class="p">())</span>

  2606. <span class="go">[&#39;_NonCallableMock__get_return_value&#39;,</span>

  2607. <span class="go"> &#39;_NonCallableMock__get_side_effect&#39;,</span>

  2608. <span class="go"> &#39;_NonCallableMock__return_value_doc&#39;,</span>

  2609. <span class="go"> &#39;_NonCallableMock__set_return_value&#39;,</span>

  2610. <span class="go"> &#39;_NonCallableMock__set_side_effect&#39;,</span>

  2611. <span class="go"> &#39;__call__&#39;,</span>

  2612. <span class="go"> &#39;__class__&#39;,</span>

  2613. <span class="go"> ...</span>

  2614. </pre></div>

  2615. </div>

  2616. <p>Alternatively you can just use <code class="docutils literal notranslate"><span class="pre">vars(my_mock)</span></code> (instance members) and

  2617. <code class="docutils literal notranslate"><span class="pre">dir(type(my_mock))</span></code> (type members) to bypass the filtering irrespective of

  2618. <code class="xref py py-const docutils literal notranslate"><span class="pre">mock.FILTER_DIR</span></code>.</p>

  2619. </section>

  2620. <section id="mock-open">

  2621. <h3>mock_open<a class="headerlink" href="#mock-open" title="Link to this heading">¶</a></h3>

  2622. <dl class="py function">

  2623. <dt class="sig sig-object py" id="unittest.mock.mock_open">

  2624. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">mock_open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mock</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">read_data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.mock_open" title="Link to this definition">¶</a></dt>

  2625. <dd><p>A helper function to create a mock to replace the use of <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>. It works

  2626. for <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> called directly or used as a context manager.</p>

  2627. <p>The <em>mock</em> argument is the mock object to configure. If <code class="docutils literal notranslate"><span class="pre">None</span></code> (the

  2628. default) then a <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> will be created for you, with the API limited

  2629. to methods or attributes available on standard file handles.</p>

  2630. <p><em>read_data</em> is a string for the <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code>,

  2631. <a class="reference internal" href="io.html#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>, and <a class="reference internal" href="io.html#io.IOBase.readlines" title="io.IOBase.readlines"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readlines()</span></code></a> methods

  2632. of the file handle to return.  Calls to those methods will take data from

  2633. <em>read_data</em> until it is depleted.  The mock of these methods is pretty

  2634. simplistic: every time the <em>mock</em> is called, the <em>read_data</em> is rewound to

  2635. the start.  If you need more control over the data that you are feeding to

  2636. the tested code you will need to customize this mock for yourself.  When that

  2637. is insufficient, one of the in-memory filesystem packages on <a class="reference external" href="https://pypi.org">PyPI</a> can offer a realistic filesystem for testing.</p>

  2638. <div class="versionchanged">

  2639. <p><span class="versionmodified changed">Changed in version 3.4: </span>Added <a class="reference internal" href="io.html#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> and <a class="reference internal" href="io.html#io.IOBase.readlines" title="io.IOBase.readlines"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readlines()</span></code></a> support.

  2640. The mock of <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> changed to consume <em>read_data</em> rather

  2641. than returning it on each call.</p>

  2642. </div>

  2643. <div class="versionchanged">

  2644. <p><span class="versionmodified changed">Changed in version 3.5: </span><em>read_data</em> is now reset on each call to the <em>mock</em>.</p>

  2645. </div>

  2646. <div class="versionchanged">

  2647. <p><span class="versionmodified changed">Changed in version 3.8: </span>Added <a class="reference internal" href="stdtypes.html#container.__iter__" title="container.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> to implementation so that iteration

  2648. (such as in for loops) correctly consumes <em>read_data</em>.</p>

  2649. </div>

  2650. </dd></dl>

  2651. 

  2652. <p>Using <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> as a context manager is a great way to ensure your file handles

  2653. are closed properly and is becoming common:</p>

  2654. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;/some/path&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  2655.     <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;something&#39;</span><span class="p">)</span>

  2656. </pre></div>

  2657. </div>

  2658. <p>The issue is that even if you mock out the call to <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> it is the

  2659. <em>returned object</em> that is used as a context manager (and has <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> and

  2660. <a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> called).</p>

  2661. <p>Mocking context managers with a <a class="reference internal" href="#unittest.mock.MagicMock" title="unittest.mock.MagicMock"><code class="xref py py-class docutils literal notranslate"><span class="pre">MagicMock</span></code></a> is common enough and fiddly

  2662. enough that a helper function is useful.</p>

  2663. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">mock_open</span><span class="p">()</span>

  2664. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.open&#39;</span><span class="p">,</span> <span class="n">m</span><span class="p">):</span>

  2665. <span class="gp">... </span>    <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">h</span><span class="p">:</span>

  2666. <span class="gp">... </span>        <span class="n">h</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;some stuff&#39;</span><span class="p">)</span>

  2667. <span class="gp">...</span>

  2668. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">mock_calls</span>

  2669. <span class="go">[call(&#39;foo&#39;, &#39;w&#39;),</span>

  2670. <span class="go"> call().__enter__(),</span>

  2671. <span class="go"> call().write(&#39;some stuff&#39;),</span>

  2672. <span class="go"> call().__exit__(None, None, None)]</span>

  2673. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span>

  2674. <span class="gp">&gt;&gt;&gt; </span><span class="n">handle</span> <span class="o">=</span> <span class="n">m</span><span class="p">()</span>

  2675. <span class="gp">&gt;&gt;&gt; </span><span class="n">handle</span><span class="o">.</span><span class="n">write</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s1">&#39;some stuff&#39;</span><span class="p">)</span>

  2676. </pre></div>

  2677. </div>

  2678. <p>And for reading files:</p>

  2679. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.open&#39;</span><span class="p">,</span> <span class="n">mock_open</span><span class="p">(</span><span class="n">read_data</span><span class="o">=</span><span class="s1">&#39;bibble&#39;</span><span class="p">))</span> <span class="k">as</span> <span class="n">m</span><span class="p">:</span>

  2680. <span class="gp">... </span>    <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">h</span><span class="p">:</span>

  2681. <span class="gp">... </span>        <span class="n">result</span> <span class="o">=</span> <span class="n">h</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>

  2682. <span class="gp">...</span>

  2683. <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  2684. <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">result</span> <span class="o">==</span> <span class="s1">&#39;bibble&#39;</span>

  2685. </pre></div>

  2686. </div>

  2687. </section>

  2688. <section id="autospeccing">

  2689. <span id="auto-speccing"></span><h3>Autospeccing<a class="headerlink" href="#autospeccing" title="Link to this heading">¶</a></h3>

  2690. <p>Autospeccing is based on the existing <code class="xref py py-attr docutils literal notranslate"><span class="pre">spec</span></code> feature of mock. It limits the

  2691. api of mocks to the api of an original object (the spec), but it is recursive

  2692. (implemented lazily) so that attributes of mocks only have the same api as

  2693. the attributes of the spec. In addition mocked functions / methods have the

  2694. same call signature as the original so they raise a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if they are

  2695. called incorrectly.</p>

  2696. <p>Before I explain how auto-speccing works, here’s why it is needed.</p>

  2697. <p><a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> is a very powerful and flexible object, but it suffers from two flaws

  2698. when used to mock out objects from a system under test. One of these flaws is

  2699. specific to the <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> api and the other is a more general problem with using

  2700. mock objects.</p>

  2701. <p>First the problem specific to <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a>. <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> has two assert methods that are

  2702. extremely handy: <a class="reference internal" href="#unittest.mock.Mock.assert_called_with" title="unittest.mock.Mock.assert_called_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_with()</span></code></a> and

  2703. <a class="reference internal" href="#unittest.mock.Mock.assert_called_once_with" title="unittest.mock.Mock.assert_called_once_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assert_called_once_with()</span></code></a>.</p>

  2704. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><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">name</span><span class="o">=</span><span class="s1">&#39;Thing&#39;</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  2705. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>

  2706. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</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>

  2707. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>

  2708. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</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>

  2709. <span class="gt">Traceback (most recent call last):</span>

  2710. <span class="w"> </span><span class="c">...</span>

  2711. <span class="gr">AssertionError</span>: <span class="n">Expected &#39;mock&#39; to be called once. Called 2 times.</span>

  2712. </pre></div>

  2713. </div>

  2714. <p>Because mocks auto-create attributes on demand, and allow you to call them

  2715. with arbitrary arguments, if you misspell one of these assert methods then

  2716. your assertion is gone:</p>

  2717. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><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">name</span><span class="o">=</span><span class="s1">&#39;Thing&#39;</span><span class="p">,</span> <span class="n">return_value</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>

  2718. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>

  2719. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assret_called_once_with</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">)</span>  <span class="c1"># Intentional typo!</span>

  2720. </pre></div>

  2721. </div>

  2722. <p>Your tests can pass silently and incorrectly because of the typo.</p>

  2723. <p>The second issue is more general to mocking. If you refactor some of your

  2724. code, rename members and so on, any tests for code that is still using the

  2725. <em>old api</em> but uses mocks instead of the real objects will still pass. This

  2726. means your tests can all pass even though your code is broken.</p>

  2727. <p>Note that this is another reason why you need integration tests as well as

  2728. unit tests. Testing everything in isolation is all fine and dandy, but if you

  2729. don’t test how your units are “wired together” there is still lots of room

  2730. for bugs that tests might have caught.</p>

  2731. <p><code class="xref py py-mod docutils literal notranslate"><span class="pre">mock</span></code> already provides a feature to help with this, called speccing. If you

  2732. use a class or instance as the <code class="xref py py-attr docutils literal notranslate"><span class="pre">spec</span></code> for a mock then you can only access

  2733. attributes on the mock that exist on the real class:</p>

  2734. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">urllib</span> <span class="kn">import</span> <span class="n">request</span>

  2735. <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">spec</span><span class="o">=</span><span class="n">request</span><span class="o">.</span><span class="n">Request</span><span class="p">)</span>

  2736. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">assret_called_with</span>  <span class="c1"># Intentional typo!</span>

  2737. <span class="gt">Traceback (most recent call last):</span>

  2738. <span class="w"> </span><span class="c">...</span>

  2739. <span class="gr">AttributeError</span>: <span class="n">Mock object has no attribute &#39;assret_called_with&#39;</span>

  2740. </pre></div>

  2741. </div>

  2742. <p>The spec only applies to the mock itself, so we still have the same issue

  2743. with any methods on the mock:</p>

  2744. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">has_data</span><span class="p">()</span>

  2745. <span class="go">&lt;mock.Mock object at 0x...&gt;</span>

  2746. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">has_data</span><span class="o">.</span><span class="n">assret_called_with</span><span class="p">()</span>  <span class="c1"># Intentional typo!</span>

  2747. </pre></div>

  2748. </div>

  2749. <p>Auto-speccing solves this problem. You can either pass <code class="docutils literal notranslate"><span class="pre">autospec=True</span></code> to

  2750. <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> / <a class="reference internal" href="#unittest.mock.patch.object" title="unittest.mock.patch.object"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch.object()</span></code></a> or use the <a class="reference internal" href="#unittest.mock.create_autospec" title="unittest.mock.create_autospec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_autospec()</span></code></a> function to create a

  2751. mock with a spec. If you use the <code class="docutils literal notranslate"><span class="pre">autospec=True</span></code> argument to <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> then the

  2752. object that is being replaced will be used as the spec object. Because the

  2753. speccing is done “lazily” (the spec is created as attributes on the mock are

  2754. accessed) you can use it with very complex or deeply nested objects (like

  2755. modules that import modules that import modules) without a big performance

  2756. hit.</p>

  2757. <p>Here’s an example of it in use:</p>

  2758. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">urllib</span> <span class="kn">import</span> <span class="n">request</span>

  2759. <span class="gp">&gt;&gt;&gt; </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.request&#39;</span><span class="p">,</span> <span class="n">autospec</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

  2760. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_request</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  2761. <span class="gp">&gt;&gt;&gt; </span><span class="n">request</span> <span class="ow">is</span> <span class="n">mock_request</span>

  2762. <span class="go">True</span>

  2763. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_request</span><span class="o">.</span><span class="n">Request</span>

  2764. <span class="go">&lt;MagicMock name=&#39;request.Request&#39; spec=&#39;Request&#39; id=&#39;...&#39;&gt;</span>

  2765. </pre></div>

  2766. </div>

  2767. <p>You can see that <code class="xref py py-class docutils literal notranslate"><span class="pre">request.Request</span></code> has a spec. <code class="xref py py-class docutils literal notranslate"><span class="pre">request.Request</span></code> takes two

  2768. arguments in the constructor (one of which is <em>self</em>). Here’s what happens if

  2769. we try to call it incorrectly:</p>

  2770. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">req</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">Request</span><span class="p">()</span>

  2771. <span class="gt">Traceback (most recent call last):</span>

  2772. <span class="w"> </span><span class="c">...</span>

  2773. <span class="gr">TypeError</span>: <span class="n">&lt;lambda&gt;() takes at least 2 arguments (1 given)</span>

  2774. </pre></div>

  2775. </div>

  2776. <p>The spec also applies to instantiated classes (i.e. the return value of

  2777. specced mocks):</p>

  2778. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">req</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">Request</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  2779. <span class="gp">&gt;&gt;&gt; </span><span class="n">req</span>

  2780. <span class="go">&lt;NonCallableMagicMock name=&#39;request.Request()&#39; spec=&#39;Request&#39; id=&#39;...&#39;&gt;</span>

  2781. </pre></div>

  2782. </div>

  2783. <p><code class="xref py py-class docutils literal notranslate"><span class="pre">Request</span></code> objects are not callable, so the return value of instantiating our

  2784. mocked out <code class="xref py py-class docutils literal notranslate"><span class="pre">request.Request</span></code> is a non-callable mock. With the spec in place

  2785. any typos in our asserts will raise the correct error:</p>

  2786. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">req</span><span class="o">.</span><span class="n">add_header</span><span class="p">(</span><span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;eggs&#39;</span><span class="p">)</span>

  2787. <span class="go">&lt;MagicMock name=&#39;request.Request().add_header()&#39; id=&#39;...&#39;&gt;</span>

  2788. <span class="gp">&gt;&gt;&gt; </span><span class="n">req</span><span class="o">.</span><span class="n">add_header</span><span class="o">.</span><span class="n">assret_called_with</span>  <span class="c1"># Intentional typo!</span>

  2789. <span class="gt">Traceback (most recent call last):</span>

  2790. <span class="w"> </span><span class="c">...</span>

  2791. <span class="gr">AttributeError</span>: <span class="n">Mock object has no attribute &#39;assret_called_with&#39;</span>

  2792. <span class="gp">&gt;&gt;&gt; </span><span class="n">req</span><span class="o">.</span><span class="n">add_header</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="s1">&#39;spam&#39;</span><span class="p">,</span> <span class="s1">&#39;eggs&#39;</span><span class="p">)</span>

  2793. </pre></div>

  2794. </div>

  2795. <p>In many cases you will just be able to add <code class="docutils literal notranslate"><span class="pre">autospec=True</span></code> to your existing

  2796. <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> calls and then be protected against bugs due to typos and api

  2797. changes.</p>

  2798. <p>As well as using <em>autospec</em> through <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> there is a

  2799. <a class="reference internal" href="#unittest.mock.create_autospec" title="unittest.mock.create_autospec"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_autospec()</span></code></a> for creating autospecced mocks directly:</p>

  2800. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">urllib</span> <span class="kn">import</span> <span class="n">request</span>

  2801. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_request</span> <span class="o">=</span> <span class="n">create_autospec</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>

  2802. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock_request</span><span class="o">.</span><span class="n">Request</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="s1">&#39;bar&#39;</span><span class="p">)</span>

  2803. <span class="go">&lt;NonCallableMagicMock name=&#39;mock.Request()&#39; spec=&#39;Request&#39; id=&#39;...&#39;&gt;</span>

  2804. </pre></div>

  2805. </div>

  2806. <p>This isn’t without caveats and limitations however, which is why it is not

  2807. the default behaviour. In order to know what attributes are available on the

  2808. spec object, autospec has to introspect (access attributes) the spec. As you

  2809. traverse attributes on the mock a corresponding traversal of the original

  2810. object is happening under the hood. If any of your specced objects have

  2811. properties or descriptors that can trigger code execution then you may not be

  2812. able to use autospec. On the other hand it is much better to design your

  2813. objects so that introspection is safe <a class="footnote-reference brackets" href="#id12" id="id11" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a>.</p>

  2814. <p>A more serious problem is that it is common for instance attributes to be

  2815. created in the <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method and not to exist on the class at all.

  2816. <em>autospec</em> can’t know about any dynamically created attributes and restricts

  2817. the api to visible attributes.</p>

  2818. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Something</span><span class="p">:</span>

  2819. <span class="gp">... </span>  <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2820. <span class="gp">... </span>    <span class="bp">self</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">33</span>

  2821. <span class="gp">...</span>

  2822. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.Something&#39;</span><span class="p">,</span> <span class="n">autospec</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>

  2823. <span class="gp">... </span>  <span class="n">thing</span> <span class="o">=</span> <span class="n">Something</span><span class="p">()</span>

  2824. <span class="gp">... </span>  <span class="n">thing</span><span class="o">.</span><span class="n">a</span>

  2825. <span class="gp">...</span>

  2826. <span class="gt">Traceback (most recent call last):</span>

  2827. <span class="w">  </span><span class="c">...</span>

  2828. <span class="gr">AttributeError</span>: <span class="n">Mock object has no attribute &#39;a&#39;</span>

  2829. </pre></div>

  2830. </div>

  2831. <p>There are a few different ways of resolving this problem. The easiest, but

  2832. not necessarily the least annoying, way is to simply set the required

  2833. attributes on the mock after creation. Just because <em>autospec</em> doesn’t allow

  2834. you to fetch attributes that don’t exist on the spec it doesn’t prevent you

  2835. setting them:</p>

  2836. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.Something&#39;</span><span class="p">,</span> <span class="n">autospec</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>

  2837. <span class="gp">... </span>  <span class="n">thing</span> <span class="o">=</span> <span class="n">Something</span><span class="p">()</span>

  2838. <span class="gp">... </span>  <span class="n">thing</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">33</span>

  2839. <span class="gp">...</span>

  2840. </pre></div>

  2841. </div>

  2842. <p>There is a more aggressive version of both <em>spec</em> and <em>autospec</em> that <em>does</em>

  2843. prevent you setting non-existent attributes. This is useful if you want to

  2844. ensure your code only <em>sets</em> valid attributes too, but obviously it prevents

  2845. this particular scenario:</p>

  2846. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.Something&#39;</span><span class="p">,</span> <span class="n">autospec</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">spec_set</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>

  2847. <span class="gp">... </span>  <span class="n">thing</span> <span class="o">=</span> <span class="n">Something</span><span class="p">()</span>

  2848. <span class="gp">... </span>  <span class="n">thing</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">33</span>

  2849. <span class="gp">...</span>

  2850. <span class="gt">Traceback (most recent call last):</span>

  2851. <span class="w"> </span><span class="c">...</span>

  2852. <span class="gr">AttributeError</span>: <span class="n">Mock object has no attribute &#39;a&#39;</span>

  2853. </pre></div>

  2854. </div>

  2855. <p>Probably the best way of solving the problem is to add class attributes as

  2856. default values for instance members initialised in <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>.

  2857. Note that if

  2858. you are only setting default attributes in <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> then providing them via

  2859. class attributes (shared between instances of course) is faster too. e.g.</p>

  2860. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Something</span><span class="p">:</span>

  2861.     <span class="n">a</span> <span class="o">=</span> <span class="mi">33</span>

  2862. </pre></div>

  2863. </div>

  2864. <p>This brings up another issue. It is relatively common to provide a default

  2865. value of <code class="docutils literal notranslate"><span class="pre">None</span></code> for members that will later be an object of a different type.

  2866. <code class="docutils literal notranslate"><span class="pre">None</span></code> would be useless as a spec because it wouldn’t let you access <em>any</em>

  2867. attributes or methods on it. As <code class="docutils literal notranslate"><span class="pre">None</span></code> is <em>never</em> going to be useful as a

  2868. spec, and probably indicates a member that will normally of some other type,

  2869. autospec doesn’t use a spec for members that are set to <code class="docutils literal notranslate"><span class="pre">None</span></code>. These will

  2870. just be ordinary mocks (well - MagicMocks):</p>

  2871. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Something</span><span class="p">:</span>

  2872. <span class="gp">... </span>    <span class="n">member</span> <span class="o">=</span> <span class="kc">None</span>

  2873. <span class="gp">...</span>

  2874. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">create_autospec</span><span class="p">(</span><span class="n">Something</span><span class="p">)</span>

  2875. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">member</span><span class="o">.</span><span class="n">foo</span><span class="o">.</span><span class="n">bar</span><span class="o">.</span><span class="n">baz</span><span class="p">()</span>

  2876. <span class="go">&lt;MagicMock name=&#39;mock.member.foo.bar.baz()&#39; id=&#39;...&#39;&gt;</span>

  2877. </pre></div>

  2878. </div>

  2879. <p>If modifying your production classes to add defaults isn’t to your liking

  2880. then there are more options. One of these is simply to use an instance as the

  2881. spec rather than the class. The other is to create a subclass of the

  2882. production class and add the defaults to the subclass without affecting the

  2883. production class. Both of these require you to use an alternative object as

  2884. the spec. Thankfully <a class="reference internal" href="#unittest.mock.patch" title="unittest.mock.patch"><code class="xref py py-func docutils literal notranslate"><span class="pre">patch()</span></code></a> supports this - you can simply pass the

  2885. alternative object as the <em>autospec</em> argument:</p>

  2886. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Something</span><span class="p">:</span>

  2887. <span class="gp">... </span>  <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

  2888. <span class="gp">... </span>    <span class="bp">self</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">33</span>

  2889. <span class="gp">...</span>

  2890. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">SomethingForTest</span><span class="p">(</span><span class="n">Something</span><span class="p">):</span>

  2891. <span class="gp">... </span>  <span class="n">a</span> <span class="o">=</span> <span class="mi">33</span>

  2892. <span class="gp">...</span>

  2893. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s1">&#39;__main__.Something&#39;</span><span class="p">,</span> <span class="n">autospec</span><span class="o">=</span><span class="n">SomethingForTest</span><span class="p">)</span>

  2894. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span> <span class="o">=</span> <span class="n">p</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

  2895. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">a</span>

  2896. <span class="go">&lt;NonCallableMagicMock name=&#39;Something.a&#39; spec=&#39;int&#39; id=&#39;...&#39;&gt;</span>

  2897. </pre></div>

  2898. </div>

  2899. <aside class="footnote-list brackets">

  2900. <aside class="footnote brackets" id="id12" role="doc-footnote">

  2901. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id11">4</a><span class="fn-bracket">]</span></span>

  2902. <p>This only applies to classes or already instantiated objects. Calling

  2903. a mocked class to create a mock instance <em>does not</em> create a real instance.

  2904. It is only attribute lookups - along with calls to <a class="reference internal" href="functions.html#dir" title="dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">dir()</span></code></a> - that are done.</p>

  2905. </aside>

  2906. </aside>

  2907. </section>

  2908. <section id="sealing-mocks">

  2909. <h3>Sealing mocks<a class="headerlink" href="#sealing-mocks" title="Link to this heading">¶</a></h3>

  2910. <dl class="py function">

  2911. <dt class="sig sig-object py" id="unittest.mock.seal">

  2912. <span class="sig-prename descclassname"><span class="pre">unittest.mock.</span></span><span class="sig-name descname"><span class="pre">seal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mock</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.mock.seal" title="Link to this definition">¶</a></dt>

  2913. <dd><p>Seal will disable the automatic creation of mocks when accessing an attribute of

  2914. the mock being sealed or any of its attributes that are already mocks recursively.</p>

  2915. <p>If a mock instance with a name or a spec is assigned to an attribute

  2916. it won’t be considered in the sealing chain. This allows one to prevent seal from

  2917. fixing part of the mock object.</p>

  2918. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><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>

  2919. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">submock</span><span class="o">.</span><span class="n">attribute1</span> <span class="o">=</span> <span class="mi">2</span>

  2920. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">not_submock</span> <span class="o">=</span> <span class="n">mock</span><span class="o">.</span><span class="n">Mock</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;sample_name&quot;</span><span class="p">)</span>

  2921. <span class="gp">&gt;&gt;&gt; </span><span class="n">seal</span><span class="p">(</span><span class="n">mock</span><span class="p">)</span>

  2922. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">new_attribute</span>  <span class="c1"># This will raise AttributeError.</span>

  2923. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">submock</span><span class="o">.</span><span class="n">attribute2</span>  <span class="c1"># This will raise AttributeError.</span>

  2924. <span class="gp">&gt;&gt;&gt; </span><span class="n">mock</span><span class="o">.</span><span class="n">not_submock</span><span class="o">.</span><span class="n">attribute2</span>  <span class="c1"># This won&#39;t raise.</span>

  2925. </pre></div>

  2926. </div>

  2927. <div class="versionadded">

  2928. <p><span class="versionmodified added">New in version 3.7.</span></p>

  2929. </div>

  2930. </dd></dl>

  2931. 

  2932. </section>

  2933. </section>

  2934. <section id="order-of-precedence-of-side-effect-return-value-and-wraps">

  2935. <h2>Order of precedence of <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code> and <em>wraps</em><a class="headerlink" href="#order-of-precedence-of-side-effect-return-value-and-wraps" title="Link to this heading">¶</a></h2>

  2936. <p>The order of their precedence is:</p>

  2937. <ol class="arabic simple">

  2938. <li><p><a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a></p></li>

  2939. <li><p><a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a></p></li>

  2940. <li><p><em>wraps</em></p></li>

  2941. </ol>

  2942. <p>If all three are set, mock will return the value from <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a>,

  2943. ignoring <a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a> and the wrapped object altogether. If any

  2944. two are set, the one with the higher precedence will return the value.

  2945. Regardless of the order of which was set first, the order of precedence

  2946. remains unchanged.</p>

  2947. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">Mock</span>

  2948. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">Order</span><span class="p">:</span>

  2949. <span class="gp">... </span>    <span class="nd">@staticmethod</span>

  2950. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">get_value</span><span class="p">():</span>

  2951. <span class="gp">... </span>        <span class="k">return</span> <span class="s2">&quot;third&quot;</span>

  2952. <span class="gp">...</span>

  2953. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">spec</span><span class="o">=</span><span class="n">Order</span><span class="p">,</span> <span class="n">wraps</span><span class="o">=</span><span class="n">Order</span><span class="p">)</span>

  2954. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;first&quot;</span><span class="p">]</span>

  2955. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s2">&quot;second&quot;</span>

  2956. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  2957. <span class="go">&#39;first&#39;</span>

  2958. </pre></div>

  2959. </div>

  2960. <p>As <code class="docutils literal notranslate"><span class="pre">None</span></code> is the default value of <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a>, if you reassign

  2961. its value back to <code class="docutils literal notranslate"><span class="pre">None</span></code>, the order of precedence will be checked between

  2962. <a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a> and the wrapped object, ignoring

  2963. <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a>.</p>

  2964. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="kc">None</span>

  2965. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  2966. <span class="go">&#39;second&#39;</span>

  2967. </pre></div>

  2968. </div>

  2969. <p>If the value being returned by <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> is <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a>,

  2970. it is ignored and the order of precedence moves to the successor to obtain the

  2971. value to return.</p>

  2972. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest.mock</span> <span class="kn">import</span> <span class="n">DEFAULT</span>

  2973. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="p">[</span><span class="n">DEFAULT</span><span class="p">]</span>

  2974. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  2975. <span class="go">&#39;second&#39;</span>

  2976. </pre></div>

  2977. </div>

  2978. <p>When <a class="reference internal" href="#unittest.mock.Mock" title="unittest.mock.Mock"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mock</span></code></a> wraps an object, the default value of

  2979. <a class="reference internal" href="#unittest.mock.Mock.return_value" title="unittest.mock.Mock.return_value"><code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code></a> will be <a class="reference internal" href="#unittest.mock.DEFAULT" title="unittest.mock.DEFAULT"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT</span></code></a>.</p>

  2980. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">spec</span><span class="o">=</span><span class="n">Order</span><span class="p">,</span> <span class="n">wraps</span><span class="o">=</span><span class="n">Order</span><span class="p">)</span>

  2981. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">return_value</span>

  2982. <span class="go">sentinel.DEFAULT</span>

  2983. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">return_value</span>

  2984. <span class="go">sentinel.DEFAULT</span>

  2985. </pre></div>

  2986. </div>

  2987. <p>The order of precedence will ignore this value and it will move to the last

  2988. successor which is the wrapped object.</p>

  2989. <p>As the real call is being made to the wrapped object, creating an instance of

  2990. this mock will return the real instance of the class. The positional arguments,

  2991. if any, required by the wrapped object must be passed.</p>

  2992. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock_instance</span> <span class="o">=</span> <span class="n">order_mock</span><span class="p">()</span>

  2993. <span class="gp">&gt;&gt;&gt; </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">order_mock_instance</span><span class="p">,</span> <span class="n">Order</span><span class="p">)</span>

  2994. <span class="go">True</span>

  2995. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock_instance</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  2996. <span class="go">&#39;third&#39;</span>

  2997. </pre></div>

  2998. </div>

  2999. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">DEFAULT</span>

  3000. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  3001. <span class="go">&#39;third&#39;</span>

  3002. </pre></div>

  3003. </div>

  3004. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s2">&quot;second&quot;</span>

  3005. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  3006. <span class="go">&#39;second&#39;</span>

  3007. </pre></div>

  3008. </div>

  3009. <p>But if you assign <code class="docutils literal notranslate"><span class="pre">None</span></code> to it, this will not be ignored as it is an

  3010. explicit assignment. So, the order of precedence will not move to the wrapped

  3011. object.</p>

  3012. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="kc">None</span>

  3013. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span> <span class="ow">is</span> <span class="kc">None</span>

  3014. <span class="go">True</span>

  3015. </pre></div>

  3016. </div>

  3017. <p>Even if you set all three at once when initializing the mock, the order of

  3018. precedence remains the same:</p>

  3019. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">spec</span><span class="o">=</span><span class="n">Order</span><span class="p">,</span> <span class="n">wraps</span><span class="o">=</span><span class="n">Order</span><span class="p">,</span>

  3020. <span class="gp">... </span>                  <span class="o">**</span><span class="p">{</span><span class="s2">&quot;get_value.side_effect&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;first&quot;</span><span class="p">],</span>

  3021. <span class="gp">... </span>                     <span class="s2">&quot;get_value.return_value&quot;</span><span class="p">:</span> <span class="s2">&quot;second&quot;</span><span class="p">}</span>

  3022. <span class="gp">... </span>                  <span class="p">)</span>

  3023. <span class="gp">...</span>

  3024. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  3025. <span class="go">&#39;first&#39;</span>

  3026. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="kc">None</span>

  3027. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  3028. <span class="go">&#39;second&#39;</span>

  3029. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">DEFAULT</span>

  3030. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  3031. <span class="go">&#39;third&#39;</span>

  3032. </pre></div>

  3033. </div>

  3034. <p>If <a class="reference internal" href="#unittest.mock.Mock.side_effect" title="unittest.mock.Mock.side_effect"><code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code></a> is exhausted, the order of precedence will not

  3035. cause a value to be obtained from the successors. Instead, <code class="docutils literal notranslate"><span class="pre">StopIteration</span></code>

  3036. exception is raised.</p>

  3037. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span> <span class="o">=</span> <span class="n">Mock</span><span class="p">(</span><span class="n">spec</span><span class="o">=</span><span class="n">Order</span><span class="p">,</span> <span class="n">wraps</span><span class="o">=</span><span class="n">Order</span><span class="p">)</span>

  3038. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">side_effect</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;first side effect value&quot;</span><span class="p">,</span>

  3039. <span class="gp">... </span>                                    <span class="s2">&quot;another side effect value&quot;</span><span class="p">]</span>

  3040. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s2">&quot;second&quot;</span>

  3041. </pre></div>

  3042. </div>

  3043. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  3044. <span class="go">&#39;first side effect value&#39;</span>

  3045. <span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  3046. <span class="go">&#39;another side effect value&#39;</span>

  3047. </pre></div>

  3048. </div>

  3049. <div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">order_mock</span><span class="o">.</span><span class="n">get_value</span><span class="p">()</span>

  3050. <span class="gt">Traceback (most recent call last):</span>

  3051. <span class="w"> </span><span class="c">...</span>

  3052. <span class="gr">StopIteration</span>

  3053. </pre></div>

  3054. </div>

  3055. </section>

  3056. </section>

  3057. 

  3058. 

  3059.             <div class="clearer"></div>

  3060.           </div>

  3061.         </div>

  3062.       </div>

  3063.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  3064.         <div class="sphinxsidebarwrapper">

  3065.   <div>

  3066.     <h3><a href="../contents.html">Table of Contents</a></h3>

  3067.     <ul>

  3068. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code> — mock object library</a><ul>

  3069. <li><a class="reference internal" href="#quick-guide">Quick Guide</a></li>

  3070. <li><a class="reference internal" href="#the-mock-class">The Mock Class</a><ul>

  3071. <li><a class="reference internal" href="#calling">Calling</a></li>

  3072. <li><a class="reference internal" href="#deleting-attributes">Deleting Attributes</a></li>

  3073. <li><a class="reference internal" href="#mock-names-and-the-name-attribute">Mock names and the name attribute</a></li>

  3074. <li><a class="reference internal" href="#attaching-mocks-as-attributes">Attaching Mocks as Attributes</a></li>

  3075. </ul>

  3076. </li>

  3077. <li><a class="reference internal" href="#the-patchers">The patchers</a><ul>

  3078. <li><a class="reference internal" href="#patch">patch</a></li>

  3079. <li><a class="reference internal" href="#patch-object">patch.object</a></li>

  3080. <li><a class="reference internal" href="#patch-dict">patch.dict</a></li>

  3081. <li><a class="reference internal" href="#patch-multiple">patch.multiple</a></li>

  3082. <li><a class="reference internal" href="#patch-methods-start-and-stop">patch methods: start and stop</a></li>

  3083. <li><a class="reference internal" href="#patch-builtins">patch builtins</a></li>

  3084. <li><a class="reference internal" href="#test-prefix">TEST_PREFIX</a></li>

  3085. <li><a class="reference internal" href="#nesting-patch-decorators">Nesting Patch Decorators</a></li>

  3086. <li><a class="reference internal" href="#where-to-patch">Where to patch</a></li>

  3087. <li><a class="reference internal" href="#patching-descriptors-and-proxy-objects">Patching Descriptors and Proxy Objects</a></li>

  3088. </ul>

  3089. </li>

  3090. <li><a class="reference internal" href="#magicmock-and-magic-method-support">MagicMock and magic method support</a><ul>

  3091. <li><a class="reference internal" href="#mocking-magic-methods">Mocking Magic Methods</a></li>

  3092. <li><a class="reference internal" href="#magic-mock">Magic Mock</a></li>

  3093. </ul>

  3094. </li>

  3095. <li><a class="reference internal" href="#helpers">Helpers</a><ul>

  3096. <li><a class="reference internal" href="#sentinel">sentinel</a></li>

  3097. <li><a class="reference internal" href="#default">DEFAULT</a></li>

  3098. <li><a class="reference internal" href="#call">call</a></li>

  3099. <li><a class="reference internal" href="#create-autospec">create_autospec</a></li>

  3100. <li><a class="reference internal" href="#any">ANY</a></li>

  3101. <li><a class="reference internal" href="#filter-dir">FILTER_DIR</a></li>

  3102. <li><a class="reference internal" href="#mock-open">mock_open</a></li>

  3103. <li><a class="reference internal" href="#autospeccing">Autospeccing</a></li>

  3104. <li><a class="reference internal" href="#sealing-mocks">Sealing mocks</a></li>

  3105. </ul>

  3106. </li>

  3107. <li><a class="reference internal" href="#order-of-precedence-of-side-effect-return-value-and-wraps">Order of precedence of <code class="xref py py-attr docutils literal notranslate"><span class="pre">side_effect</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">return_value</span></code> and <em>wraps</em></a></li>

  3108. </ul>

  3109. </li>

  3110. </ul>

  3111. 

  3112.   </div>

  3113.   <div>

  3114.     <h4>Previous topic</h4>

  3115.     <p class="topless"><a href="unittest.html"

  3116.                           title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> — Unit testing framework</a></p>

  3117.   </div>

  3118.   <div>

  3119.     <h4>Next topic</h4>

  3120.     <p class="topless"><a href="unittest.mock-examples.html"

  3121.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code> — getting started</a></p>

  3122.   </div>

  3123.   <div role="note" aria-label="source link">

  3124.     <h3>This Page</h3>

  3125.     <ul class="this-page-menu">

  3126.       <li><a href="../bugs.html">Report a Bug</a></li>

  3127.       <li>

  3128.         <a href="https://github.com/python/cpython/blob/main/Doc/library/unittest.mock.rst"

  3129.             rel="nofollow">Show Source

  3130.         </a>

  3131.       </li>

  3132.     </ul>

  3133.   </div>

  3134.         </div>

  3135. <div id="sidebarbutton" title="Collapse sidebar">

  3136. <span>«</span>

  3137. </div>

  3138. 

  3139.       </div>

  3140.       <div class="clearer"></div>

  3141.     </div>  

  3142.     <div class="related" role="navigation" aria-label="related navigation">

  3143.       <h3>Navigation</h3>

  3144.       <ul>

  3145.         <li class="right" style="margin-right: 10px">

  3146.           <a href="../genindex.html" title="General Index"

  3147.              >index</a></li>

  3148.         <li class="right" >

  3149.           <a href="../py-modindex.html" title="Python Module Index"

  3150.              >modules</a> |</li>

  3151.         <li class="right" >

  3152.           <a href="unittest.mock-examples.html" title="unittest.mock — getting started"

  3153.              >next</a> |</li>

  3154.         <li class="right" >

  3155.           <a href="unittest.html" title="unittest — Unit testing framework"

  3156.              >previous</a> |</li>

  3157. 

  3158.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  3159.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  3160.           <li class="switchers">

  3161.             <div class="language_switcher_placeholder"></div>

  3162.             <div class="version_switcher_placeholder"></div>

  3163.           </li>

  3164.           <li>

  3165.               

  3166.           </li>

  3167.     <li id="cpython-language-and-version">

  3168.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  3169.     </li>

  3170. 

  3171.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  3172.           <li class="nav-item nav-item-2"><a href="development.html" >Development Tools</a> &#187;</li>

  3173.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code> — mock object library</a></li>

  3174.                 <li class="right">

  3175.                     

  3176. 

  3177.     <div class="inline-search" role="search">

  3178.         <form class="inline-search" action="../search.html" method="get">

  3179.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  3180.           <input type="submit" value="Go" />

  3181.         </form>

  3182.     </div>

  3183.                      |

  3184.                 </li>

  3185.             <li class="right">

  3186. <label class="theme-selector-label">

  3187.     Theme

  3188.     <select class="theme-selector" oninput="activateTheme(this.value)">

  3189.         <option value="auto" selected>Auto</option>

  3190.         <option value="light">Light</option>

  3191.         <option value="dark">Dark</option>

  3192.     </select>

  3193. </label> |</li>

  3194.             

  3195.       </ul>

  3196.     </div>  

  3197.     <div class="footer">

  3198.     &copy; 

  3199.       <a href="../copyright.html">

  3200.     

  3201.     Copyright

  3202.     

  3203.       </a>

  3204.      2001-2024, Python Software Foundation.

  3205.     <br />

  3206.     This page is licensed under the Python Software Foundation License Version 2.

  3207.     <br />

  3208.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  3209.     <br />

  3210.     

  3211.       See <a href="/license.html">History and License</a> for more information.<br />

  3212.     

  3213.     

  3214.     <br />

  3215. 

  3216.     The Python Software Foundation is a non-profit corporation.

  3217. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  3218. <br />

  3219.     <br />

  3220.       Last updated on Apr 09, 2024 (13:47 UTC).

  3221.     

  3222.       <a href="/bugs.html">Found a bug</a>?

  3223.     

  3224.     <br />

  3225. 

  3226.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  3227.     </div>

  3228. 

  3229.   </body>

  3230. </html>
上海开阖软件有限公司 沪ICP备12045867号-1