This file is indexed.

/usr/share/doc/python-pytest-doc/html/doctest.html is in python-pytest-doc 3.0.6-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Doctest integration for modules and test files &#8212; pytest documentation</title>
    
    <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '3.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="shortcut icon" href="_static/pytest1favi.ico"/>
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="pytest documentation" href="contents.html" />
    <link rel="next" title="Marking test functions with attributes" href="mark.html" />
    <link rel="prev" title="Asserting Warnings" href="recwarn.html" />
   
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">

  </head>
  <body role="document">
  
  
  


    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="mark.html" title="Marking test functions with attributes"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="recwarn.html" title="Asserting Warnings"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="contents.html">pytest-3.0</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="doctest-integration-for-modules-and-test-files">
<h1>Doctest integration for modules and test files<a class="headerlink" href="#doctest-integration-for-modules-and-test-files" title="Permalink to this headline"></a></h1>
<p>By default all files matching the <code class="docutils literal"><span class="pre">test*.txt</span></code> pattern will
be run through the python standard <code class="docutils literal"><span class="pre">doctest</span></code> module.  You
can change the pattern by issuing:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pytest</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">glob</span><span class="o">=</span><span class="s1">&#39;*.rst&#39;</span>
</pre></div>
</div>
<p>on the command line. Since version <code class="docutils literal"><span class="pre">2.9</span></code>, <code class="docutils literal"><span class="pre">--doctest-glob</span></code>
can be given multiple times in the command-line.</p>
<p>You can also trigger running of doctests
from docstrings in all python modules (including regular
python test modules):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pytest</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">modules</span>
</pre></div>
</div>
<p>You can make these changes permanent in your project by
putting them into a pytest.ini file like this:</p>
<div class="highlight-ini"><div class="highlight"><pre><span></span><span class="c1"># content of pytest.ini</span>
<span class="k">[pytest]</span>
<span class="na">addopts</span> <span class="o">=</span> <span class="s">--doctest-modules</span>
</pre></div>
</div>
<p>If you then have a text file like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># content of example.rst</span>

<span class="n">hello</span> <span class="n">this</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">doctest</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">3</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">x</span>
<span class="mi">3</span>
</pre></div>
</div>
<p>and another like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># content of mymodule.py</span>
<span class="k">def</span> <span class="nf">something</span><span class="p">():</span>
    <span class="sd">&quot;&quot;&quot; a doctest in a docstring</span>
<span class="sd">    &gt;&gt;&gt; something()</span>
<span class="sd">    42</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">return</span> <span class="mi">42</span>
</pre></div>
</div>
<p>then you can just invoke <code class="docutils literal"><span class="pre">pytest</span></code> without command line options:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ pytest
======= test session starts ========
platform linux -- Python 3.5.2, pytest-3.0.6, py-1.4.33, pluggy-0.4.0
rootdir: $REGENDOC_TMPDIR, inifile: pytest.ini
collected 1 items

mymodule.py .

======= 1 passed in 0.12 seconds ========
</pre></div>
</div>
<p>It is possible to use fixtures using the <code class="docutils literal"><span class="pre">getfixture</span></code> helper:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># content of example.rst</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">tmp</span> <span class="o">=</span> <span class="n">getfixture</span><span class="p">(</span><span class="s1">&#39;tmpdir&#39;</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span> <span class="o">...</span>
<span class="o">&gt;&gt;&gt;</span>
</pre></div>
</div>
<p>Also, <a class="reference internal" href="fixture.html#usefixtures"><span class="std std-ref">Using fixtures from classes, modules or projects</span></a> and <a class="reference internal" href="fixture.html#autouse"><span class="std std-ref">Autouse fixtures (xUnit setup on steroids)</span></a> fixtures are supported
when executing text doctest files.</p>
<p>The standard <code class="docutils literal"><span class="pre">doctest</span></code> module provides some setting flags to configure the
strictness of doctest tests. In pytest You can enable those flags those flags
using the configuration file. To make pytest ignore trailing whitespaces and
ignore lengthy exception stack traces you can just write:</p>
<div class="highlight-ini"><div class="highlight"><pre><span></span><span class="k">[pytest]</span>
<span class="na">doctest_optionflags</span><span class="o">=</span> <span class="s">NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL</span>
</pre></div>
</div>
<p>pytest also introduces new options to allow doctests to run in Python 2 and
Python 3 unchanged:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">ALLOW_UNICODE</span></code>: when enabled, the <code class="docutils literal"><span class="pre">u</span></code> prefix is stripped from unicode
strings in expected doctest output.</li>
<li><code class="docutils literal"><span class="pre">ALLOW_BYTES</span></code>: when enabled, the <code class="docutils literal"><span class="pre">b</span></code> prefix is stripped from byte strings
in expected doctest output.</li>
</ul>
<p>As with any other option flag, these flags can be enabled in <code class="docutils literal"><span class="pre">pytest.ini</span></code> using
the <code class="docutils literal"><span class="pre">doctest_optionflags</span></code> ini option:</p>
<div class="highlight-ini"><div class="highlight"><pre><span></span><span class="k">[pytest]</span>
<span class="na">doctest_optionflags</span> <span class="o">=</span> <span class="s">ALLOW_UNICODE ALLOW_BYTES</span>
</pre></div>
</div>
<p>Alternatively, it can be enabled by an inline comment in the doc test
itself:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># content of example.rst</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">get_unicode_greeting</span><span class="p">()</span>  <span class="c1"># doctest: +ALLOW_UNICODE</span>
<span class="s1">&#39;Hello&#39;</span>
</pre></div>
</div>
<div class="section" id="the-doctest-namespace-fixture">
<h2>The &#8216;doctest_namespace&#8217; fixture<a class="headerlink" href="#the-doctest-namespace-fixture" title="Permalink to this headline"></a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.0.</span></p>
</div>
<p>The <code class="docutils literal"><span class="pre">doctest_namespace</span></code> fixture can be used to inject items into the
namespace in which your doctests run. It is intended to be used within
your own fixtures to provide the tests that use them with context.</p>
<p><code class="docutils literal"><span class="pre">doctest_namespace</span></code> is a standard <code class="docutils literal"><span class="pre">dict</span></code> object into which you
place the objects you want to appear in the doctest namespace:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># content of conftest.py</span>
<span class="kn">import</span> <span class="nn">numpy</span>
<span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span><span class="p">(</span><span class="n">autouse</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">add_np</span><span class="p">(</span><span class="n">doctest_namespace</span><span class="p">):</span>
    <span class="n">doctest_namespace</span><span class="p">[</span><span class="s1">&#39;np&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span>
</pre></div>
</div>
<p>which can then be used in your doctests directly:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># content of numpy.py</span>
<span class="k">def</span> <span class="nf">arange</span><span class="p">():</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    &gt;&gt;&gt; a = np.arange(10)</span>
<span class="sd">    &gt;&gt;&gt; len(a)</span>
<span class="sd">    10</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="output-format">
<h2>Output format<a class="headerlink" href="#output-format" title="Permalink to this headline"></a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.0.</span></p>
</div>
<p>You can change the diff output format on failure for your doctests
by using one of standard doctest modules format in options
(see <a class="reference external" href="http://docs.python.org/library/doctest.html#doctest.REPORT_UDIFF" title="(in Python v2.7)"><code class="docutils literal"><span class="pre">doctest.REPORT_UDIFF</span></code></a>, <a class="reference external" href="http://docs.python.org/library/doctest.html#doctest.REPORT_CDIFF" title="(in Python v2.7)"><code class="docutils literal"><span class="pre">doctest.REPORT_CDIFF</span></code></a>,
<a class="reference external" href="http://docs.python.org/library/doctest.html#doctest.REPORT_NDIFF" title="(in Python v2.7)"><code class="docutils literal"><span class="pre">doctest.REPORT_NDIFF</span></code></a>, <a class="reference external" href="http://docs.python.org/library/doctest.html#doctest.REPORT_ONLY_FIRST_FAILURE" title="(in Python v2.7)"><code class="docutils literal"><span class="pre">doctest.REPORT_ONLY_FIRST_FAILURE</span></code></a>):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pytest</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">modules</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">report</span> <span class="n">none</span>
<span class="n">pytest</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">modules</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">report</span> <span class="n">udiff</span>
<span class="n">pytest</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">modules</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">report</span> <span class="n">cdiff</span>
<span class="n">pytest</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">modules</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">report</span> <span class="n">ndiff</span>
<span class="n">pytest</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">modules</span> <span class="o">--</span><span class="n">doctest</span><span class="o">-</span><span class="n">report</span> <span class="n">only_first_failure</span>
</pre></div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="contents.html">
              <img class="logo" src="_static/pytest1.png" alt="Logo"/>
            </a></p><h3><a href="contents.html">Table Of Contents</a></h3>

<ul>
  <li><a href="index.html">Home</a></li>
  <li><a href="contents.html">Contents</a></li>
  <li><a href="getting-started.html">Install</a></li>
  <li><a href="example/index.html">Examples</a></li>
  <li><a href="customize.html">Customize</a></li>
  <li><a href="contact.html">Contact</a></li>
  <li><a href="talks.html">Talks/Posts</a></li>
  <li><a href="changelog.html">Changelog</a></li>
  <li><a href="license.html">License</a></li>
</ul>
  <hr>
  <ul>
<li><a class="reference internal" href="#">Doctest integration for modules and test files</a><ul>
<li><a class="reference internal" href="#the-doctest-namespace-fixture">The &#8216;doctest_namespace&#8217; fixture</a></li>
<li><a class="reference internal" href="#output-format">Output format</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
  <li><a href="contents.html">Documentation overview</a><ul>
      <li>Previous: <a href="recwarn.html" title="previous chapter">Asserting Warnings</a></li>
      <li>Next: <a href="mark.html" title="next chapter">Marking test functions with attributes</a></li>
  </ul></li>
</ul><h3>Useful Links</h3>
<ul>
  <li><a href="index.html">The pytest Website</a></li>
  <li><a href="contributing.html">Contribution Guide</a></li>
  <li><a href="https://pypi.python.org/pypi/pytest">pytest @ PyPI</a></li>
  <li><a href="https://github.com/pytest-dev/pytest/">pytest @ GitHub</a></li>
  <li><a href="http://plugincompat.herokuapp.com/">3rd party plugins</a></li>
  <li><a href="https://github.com/pytest-dev/pytest/issues">Issue Tracker</a></li>
  <li><a href="https://media.readthedocs.org/pdf/pytest/latest/pytest.pdf">PDF Documentation</a>
</ul>

<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>

  <div class="footer">
    &copy; Copyright 2017, holger krekel and pytest-dev team.
    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
  </div>
  

  </body>
</html>