python-pytest-doc 3.3.2-2 / usr / share / doc / python-pytest / html / warnings.html

This file is indexed.

/usr/share/doc/python-pytest/html/warnings.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
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
<!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>Warnings Capture &#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="Doctest integration for modules and test files" href="doctest.html" />
    <link rel="prev" title="Capturing of the stdout/stderr output" href="capture.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="doctest.html" title="Doctest integration for modules and test files"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="capture.html" title="Capturing of the stdout/stderr output"
             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="warnings-capture">
<span id="warnings"></span><h1>Warnings Capture<a class="headerlink" href="#warnings-capture" title="Permalink to this headline"></a></h1>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.1.</span></p>
</div>
<p>Starting from version <code class="docutils literal"><span class="pre">3.1</span></code>, pytest now automatically catches warnings during test execution
and displays them at the end of the session:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># content of test_show_warnings.py</span>
<span class="kn">import</span> <span class="nn">warnings</span>

<span class="k">def</span> <span class="nf">api_v1</span><span class="p">():</span>
    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="ne">UserWarning</span><span class="p">(</span><span class="s2">&quot;api v1, should use functions from v2&quot;</span><span class="p">))</span>
    <span class="k">return</span> <span class="mi">1</span>

<span class="k">def</span> <span class="nf">test_one</span><span class="p">():</span>
    <span class="k">assert</span> <span class="n">api_v1</span><span class="p">()</span> <span class="o">==</span> <span class="mi">1</span>
</pre></div>
</div>
<p>Running pytest now produces this output:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ pytest test_show_warnings.py
=========================== test session starts ============================
platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y
rootdir: $REGENDOC_TMPDIR, inifile:
collected 1 item

test_show_warnings.py .                                              [100%]

============================= warnings summary =============================
test_show_warnings.py::test_one
  $REGENDOC_TMPDIR/test_show_warnings.py:4: UserWarning: api v1, should use functions from v2
    warnings.warn(UserWarning(&quot;api v1, should use functions from v2&quot;))

-- Docs: http://doc.pytest.org/en/latest/warnings.html
=================== 1 passed, 1 warnings in 0.12 seconds ===================
</pre></div>
</div>
<p>Pytest by default catches all warnings except for <code class="docutils literal"><span class="pre">DeprecationWarning</span></code> and <code class="docutils literal"><span class="pre">PendingDeprecationWarning</span></code>.</p>
<p>The <code class="docutils literal"><span class="pre">-W</span></code> flag can be passed to control which warnings will be displayed or even turn
them into errors:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ pytest -q test_show_warnings.py -W error::UserWarning
F                                                                    [100%]
================================= FAILURES =================================
_________________________________ test_one _________________________________

    def test_one():
&gt;       assert api_v1() == 1

test_show_warnings.py:8:
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

    def api_v1():
&gt;       warnings.warn(UserWarning(&quot;api v1, should use functions from v2&quot;))
E       UserWarning: api v1, should use functions from v2

test_show_warnings.py:4: UserWarning
1 failed in 0.12 seconds
</pre></div>
</div>
<p>The same option can be set in the <code class="docutils literal"><span class="pre">pytest.ini</span></code> file using the <code class="docutils literal"><span class="pre">filterwarnings</span></code> ini option.
For example, the configuration below will ignore all user warnings, but will transform
all other warnings into errors.</p>
<div class="highlight-ini"><div class="highlight"><pre><span></span><span class="k">[pytest]</span>
<span class="na">filterwarnings</span> <span class="o">=</span><span class="s"></span>
<span class="s">    error</span>
<span class="s">    ignore::UserWarning</span>
</pre></div>
</div>
<p>When a warning matches more than one option in the list, the action for the last matching option
is performed.</p>
<p>Both <code class="docutils literal"><span class="pre">-W</span></code> command-line option and <code class="docutils literal"><span class="pre">filterwarnings</span></code> ini option are based on Python's own
<a class="reference external" href="https://docs.python.org/3/using/cmdline.html?highlight=#cmdoption-W">-W option</a> and <a class="reference external" href="https://docs.python.org/3/library/warnings.html#warnings.simplefilter">warnings.simplefilter</a>, so please refer to those sections in the Python
documentation for other examples and advanced usage.</p>
<div class="section" id="pytest-mark-filterwarnings">
<h2><code class="docutils literal"><span class="pre">&#64;pytest.mark.filterwarnings</span></code><a class="headerlink" href="#pytest-mark-filterwarnings" title="Permalink to this headline"></a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 3.2.</span></p>
</div>
<p>You can use the <code class="docutils literal"><span class="pre">&#64;pytest.mark.filterwarnings</span></code> to add warning filters to specific test items,
allowing you to have finer control of which warnings should be captured at test, class or
even module level:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">warnings</span>

<span class="k">def</span> <span class="nf">api_v1</span><span class="p">():</span>
    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="ne">UserWarning</span><span class="p">(</span><span class="s2">&quot;api v1, should use functions from v2&quot;</span><span class="p">))</span>
    <span class="k">return</span> <span class="mi">1</span>

<span class="nd">@pytest.mark.filterwarnings</span><span class="p">(</span><span class="s1">&#39;ignore:api v1&#39;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_one</span><span class="p">():</span>
    <span class="k">assert</span> <span class="n">api_v1</span><span class="p">()</span> <span class="o">==</span> <span class="mi">1</span>
</pre></div>
</div>
<p>Filters applied using a mark take precedence over filters passed on the command line or configured
by the <code class="docutils literal"><span class="pre">filterwarnings</span></code> ini option.</p>
<p>You may apply a filter to all tests of a class by using the <code class="docutils literal"><span class="pre">filterwarnings</span></code> mark as a class
decorator or to all tests in a module by setting the <code class="docutils literal"><span class="pre">pytestmark</span></code> variable:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="c1"># turns all warnings into errors for this module</span>
<span class="n">pytestmark</span> <span class="o">=</span> <span class="n">pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">filterwarnings</span><span class="p">(</span><span class="s1">&#39;error&#39;</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p><code class="docutils literal"><span class="pre">DeprecationWarning</span></code> and <code class="docutils literal"><span class="pre">PendingDeprecationWarning</span></code> are hidden by the standard library
by default so you have to explicitly configure them to be displayed in 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">filterwarnings</span> <span class="o">=</span><span class="s"></span>
<span class="s">    once::DeprecationWarning</span>
<span class="s">    once::PendingDeprecationWarning</span>
</pre></div>
</div>
</div>
<p><em>Credits go to Florian Schulze for the reference implementation in the</em> <a class="reference external" href="https://github.com/fschulze/pytest-warnings">pytest-warnings</a>
<em>plugin.</em></p>
</div>
<div class="section" id="disabling-warning-capture">
<h2>Disabling warning capture<a class="headerlink" href="#disabling-warning-capture" title="Permalink to this headline"></a></h2>
<p>This feature is enabled by default but can be disabled entirely in your <code class="docutils literal"><span class="pre">pytest.ini</span></code> file with:</p>
<blockquote>
<div><div class="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:warnings</span>
</pre></div>
</div>
</div></blockquote>
<p>Or passing <code class="docutils literal"><span class="pre">-p</span> <span class="pre">no:warnings</span></code> in the command-line.</p>
</div>
<div class="section" id="warns">
<span id="asserting-warnings-with-the-warns-function"></span><span id="assertwarnings"></span><span id="asserting-warnings"></span><span id="id1"></span><h2>Asserting warnings with the warns function<a class="headerlink" href="#warns" title="Permalink to this headline"></a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.8.</span></p>
</div>
<p>You can check that code raises a particular warning using <code class="docutils literal"><span class="pre">pytest.warns</span></code>,
which works in a similar manner to <a class="reference internal" href="assert.html#assertraises"><span class="std std-ref">raises</span></a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">warnings</span>
<span class="kn">import</span> <span class="nn">pytest</span>

<span class="k">def</span> <span class="nf">test_warning</span><span class="p">():</span>
    <span class="k">with</span> <span class="n">pytest</span><span class="o">.</span><span class="n">warns</span><span class="p">(</span><span class="ne">UserWarning</span><span class="p">):</span>
        <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;my warning&quot;</span><span class="p">,</span> <span class="ne">UserWarning</span><span class="p">)</span>
</pre></div>
</div>
<p>The test will fail if the warning in question is not raised. The keyword
argument <code class="docutils literal"><span class="pre">match</span></code> to assert that the exception matches a text or regex:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">warns</span><span class="p">(</span><span class="ne">UserWarning</span><span class="p">,</span> <span class="n">match</span><span class="o">=</span><span class="s1">&#39;must be 0 or None&#39;</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;value must be 0 or None&quot;</span><span class="p">,</span> <span class="ne">UserWarning</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">warns</span><span class="p">(</span><span class="ne">UserWarning</span><span class="p">,</span> <span class="n">match</span><span class="o">=</span><span class="sa">r</span><span class="s1">&#39;must be \d+$&#39;</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;value must be 42&quot;</span><span class="p">,</span> <span class="ne">UserWarning</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">warns</span><span class="p">(</span><span class="ne">UserWarning</span><span class="p">,</span> <span class="n">match</span><span class="o">=</span><span class="sa">r</span><span class="s1">&#39;must be \d+$&#39;</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;this is not here&quot;</span><span class="p">,</span> <span class="ne">UserWarning</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
  <span class="c">...</span>
<span class="gr">Failed</span>: <span class="n">DID NOT WARN. No warnings of type ...UserWarning... was emitted...</span>
</pre></div>
</div>
<p>You can also call <code class="docutils literal"><span class="pre">pytest.warns</span></code> on a function or code string:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pytest</span><span class="o">.</span><span class="n">warns</span><span class="p">(</span><span class="n">expected_warning</span><span class="p">,</span> <span class="n">func</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>
<span class="n">pytest</span><span class="o">.</span><span class="n">warns</span><span class="p">(</span><span class="n">expected_warning</span><span class="p">,</span> <span class="s2">&quot;func(*args, **kwargs)&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>The function also returns a list of all raised warnings (as
<code class="docutils literal"><span class="pre">warnings.WarningMessage</span></code> objects), which you can query for
additional information:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">pytest</span><span class="o">.</span><span class="n">warns</span><span class="p">(</span><span class="ne">RuntimeWarning</span><span class="p">)</span> <span class="k">as</span> <span class="n">record</span><span class="p">:</span>
    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;another warning&quot;</span><span class="p">,</span> <span class="ne">RuntimeWarning</span><span class="p">)</span>

<span class="c1"># check that only one warning was raised</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">record</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span>
<span class="c1"># check that the message matches</span>
<span class="k">assert</span> <span class="n">record</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">message</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="s2">&quot;another warning&quot;</span>
</pre></div>
</div>
<p>Alternatively, you can examine raised warnings in detail using the
<a class="reference internal" href="#recwarn"><span class="std std-ref">recwarn</span></a> fixture (see below).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><code class="docutils literal"><span class="pre">DeprecationWarning</span></code> and <code class="docutils literal"><span class="pre">PendingDeprecationWarning</span></code> are treated
differently; see <a class="reference internal" href="#ensuring-function-triggers"><span class="std std-ref">Ensuring a function triggers a deprecation warning</span></a>.</p>
</div>
</div>
<div class="section" id="recwarn">
<span id="recording-warnings"></span><span id="id2"></span><h2>Recording warnings<a class="headerlink" href="#recwarn" title="Permalink to this headline"></a></h2>
<p>You can record raised warnings either using <code class="docutils literal"><span class="pre">pytest.warns</span></code> or with
the <code class="docutils literal"><span class="pre">recwarn</span></code> fixture.</p>
<p>To record with <code class="docutils literal"><span class="pre">pytest.warns</span></code> without asserting anything about the warnings,
pass <code class="docutils literal"><span class="pre">None</span></code> as the expected warning type:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">pytest</span><span class="o">.</span><span class="n">warns</span><span class="p">(</span><span class="kc">None</span><span class="p">)</span> <span class="k">as</span> <span class="n">record</span><span class="p">:</span>
    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;user&quot;</span><span class="p">,</span> <span class="ne">UserWarning</span><span class="p">)</span>
    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;runtime&quot;</span><span class="p">,</span> <span class="ne">RuntimeWarning</span><span class="p">)</span>

<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">record</span><span class="p">)</span> <span class="o">==</span> <span class="mi">2</span>
<span class="k">assert</span> <span class="nb">str</span><span class="p">(</span><span class="n">record</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">message</span><span class="p">)</span> <span class="o">==</span> <span class="s2">&quot;user&quot;</span>
<span class="k">assert</span> <span class="nb">str</span><span class="p">(</span><span class="n">record</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">message</span><span class="p">)</span> <span class="o">==</span> <span class="s2">&quot;runtime&quot;</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">recwarn</span></code> fixture will record warnings for the whole function:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">warnings</span>

<span class="k">def</span> <span class="nf">test_hello</span><span class="p">(</span><span class="n">recwarn</span><span class="p">):</span>
    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;hello&quot;</span><span class="p">,</span> <span class="ne">UserWarning</span><span class="p">)</span>
    <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">recwarn</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span>
    <span class="n">w</span> <span class="o">=</span> <span class="n">recwarn</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="ne">UserWarning</span><span class="p">)</span>
    <span class="k">assert</span> <span class="nb">issubclass</span><span class="p">(</span><span class="n">w</span><span class="o">.</span><span class="n">category</span><span class="p">,</span> <span class="ne">UserWarning</span><span class="p">)</span>
    <span class="k">assert</span> <span class="nb">str</span><span class="p">(</span><span class="n">w</span><span class="o">.</span><span class="n">message</span><span class="p">)</span> <span class="o">==</span> <span class="s2">&quot;hello&quot;</span>
    <span class="k">assert</span> <span class="n">w</span><span class="o">.</span><span class="n">filename</span>
    <span class="k">assert</span> <span class="n">w</span><span class="o">.</span><span class="n">lineno</span>
</pre></div>
</div>
<p>Both <code class="docutils literal"><span class="pre">recwarn</span></code> and <code class="docutils literal"><span class="pre">pytest.warns</span></code> return the same interface for recorded
warnings: a WarningsRecorder instance. To view the recorded warnings, you can
iterate over this instance, call <code class="docutils literal"><span class="pre">len</span></code> on it to get the number of recorded
warnings, or index into it to get a particular recorded warning. It also
provides these methods:</p>
<dl class="class">
<dt id="_pytest.recwarn.WarningsRecorder">
<em class="property">class </em><code class="descname">WarningsRecorder</code><a class="reference internal" href="_modules/_pytest/recwarn.html#WarningsRecorder"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#_pytest.recwarn.WarningsRecorder" title="Permalink to this definition"></a></dt>
<dd><p>A context manager to record raised warnings.</p>
<p>Adapted from <cite>warnings.catch_warnings</cite>.</p>
<dl class="attribute">
<dt id="_pytest.recwarn.WarningsRecorder.list">
<code class="descname">list</code><a class="headerlink" href="#_pytest.recwarn.WarningsRecorder.list" title="Permalink to this definition"></a></dt>
<dd><p>The list of recorded warnings.</p>
</dd></dl>

<dl class="method">
<dt id="_pytest.recwarn.WarningsRecorder.pop">
<code class="descname">pop</code><span class="sig-paren">(</span><em>cls=&lt;class 'Warning'&gt;</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/_pytest/recwarn.html#WarningsRecorder.pop"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#_pytest.recwarn.WarningsRecorder.pop" title="Permalink to this definition"></a></dt>
<dd><p>Pop the first recorded warning, raise exception if not exists.</p>
</dd></dl>

<dl class="method">
<dt id="_pytest.recwarn.WarningsRecorder.clear">
<code class="descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/_pytest/recwarn.html#WarningsRecorder.clear"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#_pytest.recwarn.WarningsRecorder.clear" title="Permalink to this definition"></a></dt>
<dd><p>Clear the list of recorded warnings.</p>
</dd></dl>

</dd></dl>

<p>Each recorded warning has the attributes <code class="docutils literal"><span class="pre">message</span></code>, <code class="docutils literal"><span class="pre">category</span></code>,
<code class="docutils literal"><span class="pre">filename</span></code>, <code class="docutils literal"><span class="pre">lineno</span></code>, <code class="docutils literal"><span class="pre">file</span></code>, and <code class="docutils literal"><span class="pre">line</span></code>. The <code class="docutils literal"><span class="pre">category</span></code> is the
class of the warning. The <code class="docutils literal"><span class="pre">message</span></code> is the warning itself; calling
<code class="docutils literal"><span class="pre">str(message)</span></code> will return the actual message of the warning.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><code class="xref py py-class docutils literal"><span class="pre">RecordedWarning</span></code> was changed from a plain class to a namedtuple in pytest 3.1</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><code class="docutils literal"><span class="pre">DeprecationWarning</span></code> and <code class="docutils literal"><span class="pre">PendingDeprecationWarning</span></code> are treated
differently; see <a class="reference internal" href="#ensuring-function-triggers"><span class="std std-ref">Ensuring a function triggers a deprecation warning</span></a>.</p>
</div>
</div>
<div class="section" id="ensuring-function-triggers">
<span id="ensuring-a-function-triggers-a-deprecation-warning"></span><span id="id3"></span><h2>Ensuring a function triggers a deprecation warning<a class="headerlink" href="#ensuring-function-triggers" title="Permalink to this headline"></a></h2>
<p>You can also call a global helper for checking
that a certain function call triggers a <code class="docutils literal"><span class="pre">DeprecationWarning</span></code> or
<code class="docutils literal"><span class="pre">PendingDeprecationWarning</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">pytest</span>

<span class="k">def</span> <span class="nf">test_global</span><span class="p">():</span>
    <span class="n">pytest</span><span class="o">.</span><span class="n">deprecated_call</span><span class="p">(</span><span class="n">myfunction</span><span class="p">,</span> <span class="mi">17</span><span class="p">)</span>
</pre></div>
</div>
<p>By default, <code class="docutils literal"><span class="pre">DeprecationWarning</span></code> and <code class="docutils literal"><span class="pre">PendingDeprecationWarning</span></code> will not be
caught when using <code class="docutils literal"><span class="pre">pytest.warns</span></code> or <code class="docutils literal"><span class="pre">recwarn</span></code> because default Python warnings filters hide
them. If you wish to record them in your own code, use the
command <code class="docutils literal"><span class="pre">warnings.simplefilter('always')</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">warnings</span>
<span class="kn">import</span> <span class="nn">pytest</span>

<span class="k">def</span> <span class="nf">test_deprecation</span><span class="p">(</span><span class="n">recwarn</span><span class="p">):</span>
    <span class="n">warnings</span><span class="o">.</span><span class="n">simplefilter</span><span class="p">(</span><span class="s1">&#39;always&#39;</span><span class="p">)</span>
    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;deprecated&quot;</span><span class="p">,</span> <span class="ne">DeprecationWarning</span><span class="p">)</span>
    <span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">recwarn</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span>
    <span class="k">assert</span> <span class="n">recwarn</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="ne">DeprecationWarning</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also use it as a contextmanager:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">test_global</span><span class="p">():</span>
    <span class="k">with</span> <span class="n">pytest</span><span class="o">.</span><span class="n">deprecated_call</span><span class="p">():</span>
        <span class="n">myobject</span><span class="o">.</span><span class="n">deprecated_method</span><span class="p">()</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="backwards-compatibility.html">Backwards Compatibility</a></li>
  <li><a href="license.html">License</a></li>
</ul>
  <hr>
  <ul>
<li><a class="reference internal" href="#">Warnings Capture</a><ul>
<li><a class="reference internal" href="#pytest-mark-filterwarnings"><code class="docutils literal"><span class="pre">&#64;pytest.mark.filterwarnings</span></code></a></li>
<li><a class="reference internal" href="#disabling-warning-capture">Disabling warning capture</a></li>
<li><a class="reference internal" href="#warns">Asserting warnings with the warns function</a></li>
<li><a class="reference internal" href="#recwarn">Recording warnings</a></li>
<li><a class="reference internal" href="#ensuring-function-triggers">Ensuring a function triggers a deprecation warning</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
  <li><a href="contents.html">Documentation overview</a><ul>
      <li>Previous: <a href="capture.html" title="previous chapter">Capturing of the stdout/stderr output</a></li>
      <li>Next: <a href="doctest.html" title="next chapter">Doctest integration for modules and test files</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>

APT Browse - Built by Thomas Orozco.