This file is indexed.

/usr/share/doc/python-pytest/html/logging.html is in python-pytest-doc 3.3.2-2.

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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
<!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>Logging &#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.3',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </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="next" title="Good Integration Practices" href="goodpractices.html" />
    <link rel="prev" title="Writing plugins" href="writing_plugins.html" />
   
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">

  </head>
  <body>
  
  
  


    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="goodpractices.html" title="Good Integration Practices"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="writing_plugins.html" title="Writing plugins"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="contents.html">pytest-3.3</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="logging">
<span id="id1"></span><h1>Logging<a class="headerlink" href="#logging" title="Permalink to this headline"></a></h1>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>This feature is a drop-in replacement for the <a class="reference external" href="https://pypi.org/project/pytest-catchlog/">pytest-catchlog</a> plugin and they will conflict
with each other. The backward compatibility API with <code class="docutils literal"><span class="pre">pytest-capturelog</span></code>
has been dropped when this feature was introduced, so if for that reason you
still need <code class="docutils literal"><span class="pre">pytest-catchlog</span></code> you can disable the internal feature by
adding to your <code class="docutils literal"><span class="pre">pytest.ini</span></code>:</p>
<div class="last highlight-ini"><div class="highlight"><pre><span></span><span class="k">[pytest]</span>
    <span class="na">addopts</span><span class="o">=</span><span class="s">-p no:logging</span>
</pre></div>
</div>
</div>
<p>Log messages are captured by default and for each failed test will be shown in
the same manner as captured stdout and stderr.</p>
<p>Running without options:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pytest</span>
</pre></div>
</div>
<p>Shows failed tests like so:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">-----------------------</span> <span class="n">Captured</span> <span class="n">stdlog</span> <span class="n">call</span> <span class="o">----------------------</span>
<span class="n">test_reporting</span><span class="o">.</span><span class="n">py</span>    <span class="mi">26</span> <span class="n">INFO</span>     <span class="n">text</span> <span class="n">going</span> <span class="n">to</span> <span class="n">logger</span>
<span class="o">-----------------------</span> <span class="n">Captured</span> <span class="n">stdout</span> <span class="n">call</span> <span class="o">----------------------</span>
<span class="n">text</span> <span class="n">going</span> <span class="n">to</span> <span class="n">stdout</span>
<span class="o">-----------------------</span> <span class="n">Captured</span> <span class="n">stderr</span> <span class="n">call</span> <span class="o">----------------------</span>
<span class="n">text</span> <span class="n">going</span> <span class="n">to</span> <span class="n">stderr</span>
<span class="o">====================</span> <span class="mi">2</span> <span class="n">failed</span> <span class="ow">in</span> <span class="mf">0.02</span> <span class="n">seconds</span> <span class="o">=====================</span>
</pre></div>
</div>
<p>By default each captured log message shows the module, line number, log level
and message.  Showing the exact module and line number is useful for testing and
debugging.  If desired the log format and date format can be specified to
anything that the logging module supports.</p>
<p>Running pytest specifying formatting options:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pytest</span> <span class="o">--</span><span class="n">log</span><span class="o">-</span><span class="nb">format</span><span class="o">=</span><span class="s2">&quot;</span><span class="si">%(asctime)s</span><span class="s2"> </span><span class="si">%(levelname)s</span><span class="s2"> </span><span class="si">%(message)s</span><span class="s2">&quot;</span> \
        <span class="o">--</span><span class="n">log</span><span class="o">-</span><span class="n">date</span><span class="o">-</span><span class="nb">format</span><span class="o">=</span><span class="s2">&quot;%Y-%m-</span><span class="si">%d</span><span class="s2"> %H:%M:%S&quot;</span>
</pre></div>
</div>
<p>Shows failed tests like so:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">-----------------------</span> <span class="n">Captured</span> <span class="n">stdlog</span> <span class="n">call</span> <span class="o">----------------------</span>
<span class="mi">2010</span><span class="o">-</span><span class="mi">04</span><span class="o">-</span><span class="mi">10</span> <span class="mi">14</span><span class="p">:</span><span class="mi">48</span><span class="p">:</span><span class="mi">44</span> <span class="n">INFO</span> <span class="n">text</span> <span class="n">going</span> <span class="n">to</span> <span class="n">logger</span>
<span class="o">-----------------------</span> <span class="n">Captured</span> <span class="n">stdout</span> <span class="n">call</span> <span class="o">----------------------</span>
<span class="n">text</span> <span class="n">going</span> <span class="n">to</span> <span class="n">stdout</span>
<span class="o">-----------------------</span> <span class="n">Captured</span> <span class="n">stderr</span> <span class="n">call</span> <span class="o">----------------------</span>
<span class="n">text</span> <span class="n">going</span> <span class="n">to</span> <span class="n">stderr</span>
<span class="o">====================</span> <span class="mi">2</span> <span class="n">failed</span> <span class="ow">in</span> <span class="mf">0.02</span> <span class="n">seconds</span> <span class="o">=====================</span>
</pre></div>
</div>
<p>These options can also be customized through a configuration file:</p>
<div class="highlight-ini"><div class="highlight"><pre><span></span><span class="k">[pytest]</span>
<span class="na">log_format</span> <span class="o">=</span> <span class="s">%(asctime)s %(levelname)s %(message)s</span>
<span class="na">log_date_format</span> <span class="o">=</span> <span class="s">%Y-%m-%d %H:%M:%S</span>
</pre></div>
</div>
<p>Further it is possible to disable reporting logs on failed tests completely
with:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pytest</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="nb">print</span><span class="o">-</span><span class="n">logs</span>
</pre></div>
</div>
<p>Or in you <code class="docutils literal"><span class="pre">pytest.ini</span></code>:</p>
<div class="highlight-ini"><div class="highlight"><pre><span></span><span class="k">[pytest]</span>
<span class="na">log_print</span> <span class="o">=</span> <span class="s">False</span>
</pre></div>
</div>
<p>Shows failed tests in the normal manner as no logs were captured:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">-----------------------</span> <span class="n">Captured</span> <span class="n">stdout</span> <span class="n">call</span> <span class="o">----------------------</span>
<span class="n">text</span> <span class="n">going</span> <span class="n">to</span> <span class="n">stdout</span>
<span class="o">-----------------------</span> <span class="n">Captured</span> <span class="n">stderr</span> <span class="n">call</span> <span class="o">----------------------</span>
<span class="n">text</span> <span class="n">going</span> <span class="n">to</span> <span class="n">stderr</span>
<span class="o">====================</span> <span class="mi">2</span> <span class="n">failed</span> <span class="ow">in</span> <span class="mf">0.02</span> <span class="n">seconds</span> <span class="o">=====================</span>
</pre></div>
</div>
<p>Inside tests it is possible to change the log level for the captured log
messages.  This is supported by the <code class="docutils literal"><span class="pre">caplog</span></code> fixture:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_foo</span><span class="p">(</span><span class="n">caplog</span><span class="p">):</span>
    <span class="n">caplog</span><span class="o">.</span><span class="n">set_level</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
    <span class="k">pass</span>
</pre></div>
</div>
<p>By default the level is set on the handler used to catch the log messages,
however as a convenience it is also possible to set the log level of any
logger:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_foo</span><span class="p">(</span><span class="n">caplog</span><span class="p">):</span>
    <span class="n">caplog</span><span class="o">.</span><span class="n">set_level</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">,</span> <span class="n">logger</span><span class="o">=</span><span class="s1">&#39;root.baz&#39;</span><span class="p">)</span>
    <span class="k">pass</span>
</pre></div>
</div>
<p>It is also possible to use a context manager to temporarily change the log
level:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_bar</span><span class="p">(</span><span class="n">caplog</span><span class="p">):</span>
    <span class="k">with</span> <span class="n">caplog</span><span class="o">.</span><span class="n">at_level</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">):</span>
        <span class="k">pass</span>
</pre></div>
</div>
<p>Again, by default the level of the handler is affected but the level of any
logger can be changed instead with:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_bar</span><span class="p">(</span><span class="n">caplog</span><span class="p">):</span>
    <span class="k">with</span> <span class="n">caplog</span><span class="o">.</span><span class="n">at_level</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">CRITICAL</span><span class="p">,</span> <span class="n">logger</span><span class="o">=</span><span class="s1">&#39;root.baz&#39;</span><span class="p">):</span>
        <span class="k">pass</span>
</pre></div>
</div>
<p>Lastly all the logs sent to the logger during the test run are made available on
the fixture in the form of both the LogRecord instances and the final log text.
This is useful for when you want to assert on the contents of a message:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_baz</span><span class="p">(</span><span class="n">caplog</span><span class="p">):</span>
    <span class="n">func_under_test</span><span class="p">()</span>
    <span class="k">for</span> <span class="n">record</span> <span class="ow">in</span> <span class="n">caplog</span><span class="o">.</span><span class="n">records</span><span class="p">:</span>
        <span class="k">assert</span> <span class="n">record</span><span class="o">.</span><span class="n">levelname</span> <span class="o">!=</span> <span class="s1">&#39;CRITICAL&#39;</span>
    <span class="k">assert</span> <span class="s1">&#39;wally&#39;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">caplog</span><span class="o">.</span><span class="n">text</span>
</pre></div>
</div>
<p>For all the available attributes of the log records see the
<code class="docutils literal"><span class="pre">logging.LogRecord</span></code> class.</p>
<p>You can also resort to <code class="docutils literal"><span class="pre">record_tuples</span></code> if all you want to do is to ensure,
that certain messages have been logged under a given logger name with a given
severity and message:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_foo</span><span class="p">(</span><span class="n">caplog</span><span class="p">):</span>
    <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">&#39;boo </span><span class="si">%s</span><span class="s1">&#39;</span><span class="p">,</span> <span class="s1">&#39;arg&#39;</span><span class="p">)</span>

    <span class="k">assert</span> <span class="n">caplog</span><span class="o">.</span><span class="n">record_tuples</span> <span class="o">==</span> <span class="p">[</span>
        <span class="p">(</span><span class="s1">&#39;root&#39;</span><span class="p">,</span> <span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">,</span> <span class="s1">&#39;boo arg&#39;</span><span class="p">),</span>
    <span class="p">]</span>
</pre></div>
</div>
<p>You can call <code class="docutils literal"><span class="pre">caplog.clear()</span></code> to reset the captured log records in a test:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_something_with_clearing_records</span><span class="p">(</span><span class="n">caplog</span><span class="p">):</span>
    <span class="n">some_method_that_creates_log_records</span><span class="p">()</span>
    <span class="n">caplog</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span>
    <span class="n">your_test_method</span><span class="p">()</span>
    <span class="k">assert</span> <span class="p">[</span><span class="s1">&#39;Foo&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="p">[</span><span class="n">rec</span><span class="o">.</span><span class="n">message</span> <span class="k">for</span> <span class="n">rec</span> <span class="ow">in</span> <span class="n">caplog</span><span class="o">.</span><span class="n">records</span><span class="p">]</span>
</pre></div>
</div>
<div class="section" id="live-logs">
<h2>Live Logs<a class="headerlink" href="#live-logs" title="Permalink to this headline"></a></h2>
<p>By default, pytest will output any logging records with a level higher or
equal to WARNING. In order to actually see these logs in the console you have to
disable pytest output capture by passing <code class="docutils literal"><span class="pre">-s</span></code>.</p>
<p>You can specify the logging level for which log records with equal or higher
level are printed to the console by passing <code class="docutils literal"><span class="pre">--log-cli-level</span></code>. This setting
accepts the logging level names as seen in python's documentation or an integer
as the logging level num.</p>
<p>Additionally, you can also specify <code class="docutils literal"><span class="pre">--log-cli-format</span></code> and
<code class="docutils literal"><span class="pre">--log-cli-date-format</span></code> which mirror and default to <code class="docutils literal"><span class="pre">--log-format</span></code> and
<code class="docutils literal"><span class="pre">--log-date-format</span></code> if not provided, but are applied only to the console
logging handler.</p>
<p>All of the CLI log options can also be set in the configuration INI file. The
option names are:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">log_cli_level</span></code></li>
<li><code class="docutils literal"><span class="pre">log_cli_format</span></code></li>
<li><code class="docutils literal"><span class="pre">log_cli_date_format</span></code></li>
</ul>
<p>If you need to record the whole test suite logging calls to a file, you can pass
<code class="docutils literal"><span class="pre">--log-file=/path/to/log/file</span></code>. This log file is opened in write mode which
means that it will be overwritten at each run tests session.</p>
<p>You can also specify the logging level for the log file by passing
<code class="docutils literal"><span class="pre">--log-file-level</span></code>. This setting accepts the logging level names as seen in
python's documentation(ie, uppercased level names) or an integer as the logging
level num.</p>
<p>Additionally, you can also specify <code class="docutils literal"><span class="pre">--log-file-format</span></code> and
<code class="docutils literal"><span class="pre">--log-file-date-format</span></code> which are equal to <code class="docutils literal"><span class="pre">--log-format</span></code> and
<code class="docutils literal"><span class="pre">--log-date-format</span></code> but are applied to the log file logging handler.</p>
<p>All of the log file options can also be set in the configuration INI file. The
option names are:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">log_file</span></code></li>
<li><code class="docutils literal"><span class="pre">log_file_level</span></code></li>
<li><code class="docutils literal"><span class="pre">log_file_format</span></code></li>
<li><code class="docutils literal"><span class="pre">log_file_date_format</span></code></li>
</ul>
</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="backwards-compatibility.html">Backwards Compatibility</a></li>
  <li><a href="license.html">License</a></li>
</ul>
  <hr>
  <ul>
<li><a class="reference internal" href="#">Logging</a><ul>
<li><a class="reference internal" href="#live-logs">Live Logs</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
  <li><a href="contents.html">Documentation overview</a><ul>
      <li>Previous: <a href="writing_plugins.html" title="previous chapter">Writing plugins</a></li>
      <li>Next: <a href="goodpractices.html" title="next chapter">Good Integration Practices</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 2018, holger krekel and pytest-dev team.
    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
  </div>
  

  </body>
</html>